scraperapi-cli

ScraperAPI CLI（sapi）

sapi 是 ScraperAPI 官方命令行工具。适用于以下情况：

• 用户已经在终端中，希望立即获得结果，无需编写脚本。
• 抓取任务是 Shell 管道的一部分（sapi … | jq …、xargs、make、GitHub Actions）。
• 一次性定时任务（cron、launchd、systemd timer）需要调用 ScraperAPI，无需设置项目。
• 用户正在探索：测试 --render 或 --premium 是否能解决目标网站的问题，再决定是否将其用于代码中。

如果用户正在使用 Python、Node、PHP、Ruby 或 Java 编写应用程序代码，请引导他们使用相应的 SDK 技能；CLI 适用于 Shell，而非应用逻辑。

安装和身份验证

npm install -g scraperapi-cli    # requires Node.js 18+
sapi init                        # interactive: prompts for the key and validates it

非交互式设置（适用于 CI / Dockerfile）：

sapi init --api-key "$SCRAPERAPI_API_KEY"

API 密钥解析顺序

sapi 按以下顺序查找 API 密钥，并在找到第一个密钥后停止：

1. 命令中的 --api-key <key> 标志
2. SCRAPERAPI_API_KEY 环境变量
3. ~/.config/scraperapi/config.json（由 sapi init 写入）

在 CI 中，建议使用环境变量，这样密钥就不会出现在 Shell 历史记录和配置文件中。

输出约定——管道操作的重要说明

流	输出内容
stdout	数据（页面正文、JSON、表格行）
stderr	加载动画、警告、错误

当 stdout 不是 TTY（管道或重定向）时， sapi 会自动切换到 JSON 模式：

sapi scrape https://example.com | jq .body            # auto-JSON
sapi scrape https://example.com > out.json            # auto-JSON
sapi scrape https://example.com                       # human output (page body to stdout)

在 TTY 中使用 --json 强制启用 JSON 模式。使用 --output html|markdown|text|json|csv 强制指定正文格式。--output 会覆盖非 TTY 下自动启用 JSON 的规则，因此你可以将原始 HTML 或 Markdown 传递给其他工具，而不会将其包装在 JSON 中。

对于高成本调用， sapi 不会提示用户确认。如果你想在运行请求前查看费用，请使用 sapi cost。

sapi scrape <url>——同步抓取

核心命令。将页面正文返回到 stdout。

sapi scrape https://example.com
sapi scrape https://example.com --render                       # +10 credits, JS rendering
sapi scrape https://example.com --render --wait-for "#main"    # wait for selector
sapi scrape https://example.com --country gb                   # geotarget UK
sapi scrape https://example.com --premium                      # +10 credits, residential proxies
sapi scrape https://example.com --ultra-premium                # +30 credits, hardest sites
sapi scrape https://example.com --autoparse --json             # structured JSON for supported sites
sapi scrape https://example.com --screenshot --json            # PNG (+10 credits) returned as base64 in JSON
sapi scrape https://example.com --async                        # submit as async job, prints jobId

升级方案

始终从成本最低的选项开始，仅在请求失败时升级：

1. 默认选项（1 个积分）。如果返回 200，即完成。
2. 如果页面通过 JavaScript 加载内容（SPA、已填充数据的表格、无限滚动），使用 --render。+10 个积分。
3. 如果网站从数据中心 IP 返回 403 / 拦截页面，使用 --premium。+10 个积分。
4. 只有面对最难处理的反机器人网站（Cloudflare Turnstile、复杂的指纹识别）时，才使用 --ultra-premium。+30 个积分。

组合使用标志会增加积分消耗——--render --premium 每次成功约消耗 20 个积分。

标志参考

标志	说明	积分
--render	JavaScript 渲染	+10
--premium	住宅代理	+10
--ultra-premium	高级反机器人绕过	+30
--screenshot	PNG 截图（JSON 模式下为 base64）	+10
--autoparse	支持的网站自动解析为 JSON	—
--country <cc>	ISO 3166-1（例如 us、gb、de）	—
--device <type>	mobile 或 desktop 用户代理	—
--output <fmt>	html、markdown、text、json、csv	—
--session <n>	粘性会话编号（重复使用 IP）	—
--wait-for <sel>	等待的 CSS 选择器（需要 --render）	—
--timeout <sec>	请求超时（默认 70）	—
--async	作为异步任务提交，打印任务 ID 后退出	—
--json	强制使用 JSON 输出模式	—
--api-key <key>	为单次调用覆盖已配置的 API 密钥	—

没有交互式确认步骤—— sapi scrape 会立即运行请求。使用 sapi cost <url>（见下文）可预览积分消耗，而不会花费积分。

sapi cost <url>——预览积分消耗

sapi cost https://example.com                   # base cost
sapi cost https://example.com --render          # with JS rendering
sapi cost https://example.com --render --premium
sapi cost https://example.com --render --json   # machine-readable

接受与 sapi scrape 相同的参数标志（--async 和 --timeout 除外），并打印类似 25 credits 的结果。适合在运行高成本批处理前进行预检——如果所选标志组合的成本高于预期，可将其接入脚本以便快速失败。

sapi jobs — 异步抓取

批量处理、目标网站响应较慢或需要提交后即返回的任务，请使用异步模式。

sapi scrape https://example.com --async              # returns a jobId on stdout
sapi jobs list                                        # list all jobs
sapi jobs get <jobId>                                 # poll until done, print result
sapi jobs get <jobId> --no-poll                       # one-shot status check
sapi jobs cancel <jobId>                              # cancel a running job
sapi jobs batch urls.txt                              # submit up to 50,000 URLs from a file

urls.txt 中每行包含一个 URL。URL 数量超过约 100 个时，批处理是更合适的选择——循环调用同步 sapi scrape 会耗尽并发请求额度并触发 429 错误。

惯用的批处理流水线

sapi jobs batch 会返回一个 JSON 数组——每个已提交的任务对应一个条目，并且各自拥有一个 id。使用 sapi jobs get 轮询每个子任务：

# 1. Submit a batch, grab every child job id.
sapi jobs batch urls.txt --json | jq -r '.[].id' > job-ids.txt

# 2. Wait for each one (`jobs get` polls automatically until finished).
while read -r ID; do
  sapi jobs get "$ID" --json >> batch-results.ndjson
done < job-ids.txt

# 3. Extract bodies that succeeded.
jq -s '[.[] | select(.status=="finished") | .response.body]' batch-results.ndjson

sapi structured — 支持网站的预解析 JSON

目标网站是 Amazon、Google、Walmart、eBay 或 Redfin 时，请优先使用 structured，而不是 scrape + --autoparse + 手动解析。这些端点会返回简洁且架构稳定的 JSON。

# Amazon
sapi structured amazon product https://amazon.com/dp/B09XYZ
sapi structured amazon search "wireless headphones"
sapi structured amazon offers https://amazon.com/dp/B09XYZ
sapi structured amazon reviews https://amazon.com/dp/B09XYZ

# Google
sapi structured google serp "best espresso machine"
sapi structured google news "artificial intelligence"
sapi structured google jobs "software engineer remote"
sapi structured google shopping "standing desk"
sapi structured google maps "coffee shops near me"

# Walmart / eBay / Redfin
sapi structured walmart product https://walmart.com/ip/123456
sapi structured ebay product https://ebay.com/itm/123456
sapi structured redfin listing https://redfin.com/home/12345
sapi structured redfin search "Austin TX"
sapi structured redfin agents "Portland OR"

所有结构化命令都接受 --json，用于输出原始结果（通过管道传输时会自动启用）。各垂直领域的架构请参阅 docs.scraperapi.com。

sapi crawler — 全站爬取

sapi crawler start example.com           # kick off a crawl, prints jobId
sapi crawler status <jobId>              # progress
sapi crawler results <jobId>             # list discovered URLs (human table)
sapi crawler results <jobId> --json      # JSON object: { jobId, urls: [...] }

爬虫用于发现某个域名下的 URL。之后若要抓取每个 URL，请将结果传给 sapi jobs batch：

sapi crawler results "$CRAWL" --json | jq -r '.urls[]' > urls.txt
sapi jobs batch urls.txt

sapi pipeline — DataPipeline 项目

项目在 ScraperAPI 仪表板中配置；CLI 用于启动运行并读取结果。

sapi pipeline list                  # list your projects
sapi pipeline run <projectId>       # trigger a run, prints jobId
sapi pipeline status <jobId>        # check run status
sapi pipeline results <jobId>       # fetch results

如果用户想要定期抓取，但尚无项目，请引导他们前往仪表板——sapi 不会创建项目。

sapi account — 额度与密钥管理

sapi account                        # human summary: credits left, plan, period
sapi account --json                 # machine-readable
sapi account keys list              # list API keys on the account
sapi account keys create            # create a new key (returns once — copy it)
sapi account keys revoke <keyId>    # revoke a key

启动任何大型任务之前，务必先运行 sapi account——这是确认密钥可用且额度充足的最省事方法。

sapi config — 持久化默认值

sapi config list
sapi config get api_key
sapi config set default_country gb
sapi config set default_output_format markdown
sapi config set default_timeout 90

可设置的键：api_key、default_country、default_output_format、default_timeout。如果机器由多人共用，请使用 SCRAPERAPI_API_KEY 环境变量，而不是 config set api_key。

Shell 示例

抓取页面，用 pup 提取标题并追加到 CSV

URL="https://example.com"
TITLE=$(sapi scrape "$URL" --json | jq -r .body | pup 'title text{}')
echo "$URL,$TITLE" >> titles.csv

通过 cron 每日检查价格

# crontab: 7am every day
0 7 * * * /usr/local/bin/sapi structured amazon product https://amazon.com/dp/B09XYZ --json \
  | jq '{ts: now, price: .pricing}' >> ~/prices.ndjson

使用 xargs 并行抓取

# Run 5 in parallel; --json puts one record per line (no prompts to worry about).
cat urls.txt | xargs -n1 -P5 sapi scrape --render --json > out.ndjson

URL 数量超过约 100 个时，优先使用 sapi jobs batch，而不是此方法——这样可以绕过并发请求限制。

在 CI 中遇到错误时立即失败

sapi 遇到任何错误都会以非零状态码退出，因此 set -e 可以按预期工作：

set -euo pipefail
sapi account --json | jq -e '.credits > 1000'             # fails the build if low
sapi scrape "$URL" --output markdown > page.md

遇到拦截时升级方案

sapi scrape "$URL" --output html > out.html \
  || sapi scrape "$URL" --render --output html > out.html \
  || sapi scrape "$URL" --premium --output html > out.html

从低成本方案逐步升级到高成本方案，仅当前一档失败时才为下一档付费。--output html 会在每次重定向中保留原始 HTML；若不使用它，非 TTY 规则会将正文封装为 JSON。

何时不应使用 sapi

• 在应用程序代码中（Python、Node、PHP、Ruby、Java）——请使用对应的 SDK 技能；通过 shell 调用 CLI 很脆弱。
• 在 Shell 脚本中对数千个 URL 进行紧密循环处理——请改用 sapi jobs batch 提交批次，让 ScraperAPI 处理并发和重试。
• 需要 Webhook 投递的长期定时项目——DataPipeline（在仪表板中配置）才是合适的产品；CLI 可以启动运行，但不能替代项目模型。

故障排除

症状	可能原因	修复方法
command not found: sapi	未安装，或 npm 全局 bin 不在 $PATH 中	npm install -g scraperapi-cli；检查 npm config get prefix
401 Invalid API key	缺少密钥或密钥错误	运行 sapi account 确认；重新运行 sapi init
访问公开页面时出现 403	数据中心 IP 被拦截	使用 --premium 重试，然后使用 --ultra-premium
sapi 返回 429	达到并发请求限制	改用 sapi jobs batch，或添加 xargs -P 上限
脚本一直挂起	默认超时为 70 秒，目标网站响应较慢	使用 --timeout 120，或使用 --async
输出是 JSON 而不是 HTML	stdout 通过管道传输 → 自动输出 JSON	若要在管道中获取原始 HTML，请使用 --output html 强制指定

完整参数参考和当前额度费用请参阅 docs.scraperapi.com。