Fetchbeam
登录开始采集
Fetchbeam
语言
开始采集
FETCHBEAM API

一个 API，把网址变成可用数据。

提交持久化采集任务、跟踪执行进度并下载结果，无需自行维护浏览器基础设施。

基础地址https://fetchbeam.com生产环境
POST /v1/captures
Authorization: Bearer fb_live_…
Content-Type: application/json

{
  "url": "https://example.com",
  "mode": "browser"
}
202 task queued
01 · QUICKSTART

完成第一次 API 请求

采集采用异步任务：先创建任务，再查询状态，成功后读取保存结果。

1

创建 API 密钥

在控制台生成密钥并立即保存。

2

提交网页地址

使用浏览器或自动采集模式。

3

读取采集结果

轮询任务直至成功，然后获取结果。

1. 创建 API 密钥

密钥以 fb_live_ 开头。FetchBeam 只保存指纹，完整密钥不会再次显示。

打开 API 密钥
02 · REQUEST

2. 提交采集任务

如果你的系统可能自动重试请求，请设置幂等键，避免重复创建任务。

curl -X POST https://fetchbeam.com/v1/captures \
  -H "Authorization: Bearer fb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: capture-products-001" \
  -d '{
    "url": "https://example.com/products",
    "mode": "browser",
    "outputs": ["html", "text", "extract"],
    "goal": "Product name, price and link"
  }'
202 已接受
{
  "success": true,
  "task_id": "6d06c8e8-…",
  "status": "QUEUED",
  "created_at": "2026-09-30T02:18:00.000Z",
  "retry_after": 1
}
03 · AUTH

身份认证

每个 /v1 请求都要在 Bearer 请求头中携带 API 密钥。不要把密钥放进前端代码或浏览器网址。

密钥仅应保存在服务端；怀疑泄露时请立即撤销。
04 · API

当前可用的公开 API

这里只列出已经实现的接口。尚在规划中的字段不会混进示例，复制后可直接用于真实接入。

POST/v1/capturesCreate a durable capture task
GET/v1/tasksList tasks; filter by status or search with q
GET/v1/tasks/{task_id}Read status and metadata
GET/v1/tasks/{task_id}/resultRead the saved result after SUCCESS
POST/v1/tasks/{task_id}/cancelCancel an unfinished task
POST/v1/batchesCreate an ordered batch
GET/v1/usageRead current usage and balance
GET/v1/credit-ledgerRead the account Credit ledger
GET/v1/packagesRead package options and the active package
POST/v1/packagesBuy a package with purchased Credits; requires Idempotency-Key
POST/v1/vouchers/redeemRedeem a one-time Credit voucher
05 · CAPTURE

创建采集

POST /v1/captures 会立即返回任务 ID。auto 和 browser 目前都会使用托管浏览器节点。

POST/v1/captures202
字段Type说明
urlstring必填Public HTTP or HTTPS URL, up to 2,048 characters
modeauto | browser可选Capture mode; defaults to auto
outputsstring[]可选Any of html, text, extract
goalstring可选Plain-language collection goal, up to 1,000 characters
allow_payg_fallbackboolean可选When a package is exhausted, explicitly allow 2-Credit pay-as-you-go capture
现在可用

托管浏览器采集、HTML、文本、确定性 Extract 输出、持久化任务、幂等请求和批量导出。

公开 API 暂未开放

直连 HTTP、截图、请求级 Cookie、代理与等待条件，以及由 API 直接触发的 AI 整理。现在请不要提交这些字段。

06 · TASKS

任务状态

任务资源是状态判断的唯一依据。建议每 3 秒查询一次；如果 Retry-After 要求等待更久，以响应头为准。

PENDING→QUEUED→STARTING→RUNNING→SUCCESS
GET/v1/tasks/{task_id}PENDING → QUEUED → STARTING → RUNNING → SUCCESS / FAILED / TIMEOUT / CANCELED
GET/v1/tasks/{task_id}/result任务进入 SUCCESS 后，可读取保存的 HTML、文本和确定性 Extract 输出。request_headers 仅对有效的 Pro / Business 套餐返回；request_headers_access 标明可用状态。 网页文件保留 24 小时，请及时下载。 HTTP 410 / RESULT_EXPIRED: 网页文件已过期，无法查看或下载。请重新采集。

轮询任务并读取结果

进入任意终态后都应停止轮询。只有 SUCCESS 才读取 /result；其他状态会返回 RESULT_UNAVAILABLE。

JavaScript
const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

let task;
do {
  const response = await fetch(
    "https://fetchbeam.com/v1/tasks/6d06c8e8-…",
    { headers: { Authorization: "Bearer fb_live_YOUR_API_KEY" } }
  );
  ({ task } = await response.json());

  if (["FAILED", "TIMEOUT", "CANCELED"].includes(task.status)) {
    throw new Error(task.error_message || "Capture " + task.status);
  }
  if (task.status !== "SUCCESS") await delay(3000);
} while (task.status !== "SUCCESS");

const result = await fetch(
  "https://fetchbeam.com/v1/tasks/" + task.id + "/result",
  { headers: { Authorization: "Bearer fb_live_YOUR_API_KEY" } }
).then((response) => response.json());
07 · AI

AI 整理

AI 整理目前在登录后的控制台中运行，并且要先完成网页采集。goal 会随任务保存并指导分析，但仅通过公开 API 创建任务不会自动调用模型。

FetchBeam 会先清洗保存的 HTML，再发送给 Qwen。清洗后页面超过 300,000 字符时会跳过 AI，但原始采集结果和规则提取仍然可用。
08 · BATCHES

批量采集

一次创建多个持久采集任务，查看有序进度、重试失败项，并将成功结果合并下载。

POST/v1/batchesCreate an ordered batch
GET/v1/batches/{batch_id}Read progress and items
POST/v1/batches/{batch_id}/retryRetry one failed item
POST/v1/batches/{batch_id}/cancelCancel unfinished items
GET/v1/batches/{batch_id}/export?format=csvDownload successful results
GET/v1/batches/{batch_id}/export?format=jsonlDownload JSON Lines

只能重试 FAILED 或 TIMEOUT 项，并会为替换任务重新预留额度。

成功结果可以导出为 CSV、JSON 或 JSONL。

创建一个批次

cURL
curl -X POST https://fetchbeam.com/v1/batches \
  -H "Authorization: Bearer fb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-products-001" \
  -d '{
    "name": "Supplier pages",
    "urls": [
      "https://example.com/products/1",
      "https://example.com/products/2"
    ],
    "outputs": ["html", "text", "extract"]
  }'
09 · CREDITS

额度与限制

浏览器采集成功扣 2 Credits，或扣 1 次有效套餐的采集次数；AI 智能提取按量成功扣 2 Credits；有效套餐 Developer / Pro / Business 分别为 2 / 1 / 0 Credits/次。失败任务会释放预留。

浏览器采集2 Credits
AI 智能提取2 Credits（Developer 2 / Pro 1 / Business 0）

默认限制与试用额度

试用账户100 Credits / 14 天
并发数试用账户 1 个
批量网址试用账户 10 个；按套餐最高 100 个
创建采集每账户每小时 30 次
创建批次每账户每小时 10 次
API 密钥每账户最多 10 个有效密钥
10 · ERRORS

错误处理

错误响应会返回稳定错误码和 X-Request-Id。需要协助时，请一并提供该响应头。

JSON
{
  "success": false,
  "code": "INVALID_REQUEST",
  "error": "A readable message"
}
HTTPCode说明
400INVALID_REQUEST请求体或参数无效。
401INVALID_API_KEYBearer 密钥缺失、无效或已撤销。
402INSUFFICIENT_CREDITS账户可用 Credits 不足。
404RESULT_UNAVAILABLE任务还没有可读取的保存结果。
409TASK_NOT_RETRYABLE当前资源状态不允许该操作。
413BODY_TOO_LARGE请求体或生成的导出文件过大。
422FEATURE_NOT_AVAILABLE请求的引擎或功能尚未开放。
429RATE_LIMITED请等待后再提交请求。
503SERVICE_UNAVAILABLE临时故障请使用指数退避重试。