API 文档

一个端点、一个 op 字段。所有能力共用同一个请求形状。

快速开始

想先看看它返回什么，去 Playground。不用先读完这一页，填个关键词就能看到真实返回。

注册拿到 key（免费档 100 credit），然后：

curl -X POST https://widefetch.com/v1/call \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"google.search","params":{"keyword":"vector database"}}'

认证

Authorization: Bearer sk_…。key 在控制台里发，明文只在发出来那一刻出现一次（库里只存哈希）。

吊销立刻生效。一把 key 泄漏就吊销它再发一把。

发起调用

POST /v1/call

字段	类型	说明
op	string	要调的能力，见下方能力表
params	object	该能力的参数

有界同步：能在约 25 秒内跑完的，直接把结果返回。超过就返回 status: "running" 和一个 request_id，你拿它去轮询。浏览器类的能力（executor: browser）比较容易超过，http / api 那两档通常一两秒就回来。

{
  "request_id": "req_7Qn1vK…",
  "status": "done",          // done | running | failed
  "outcome": "ok",
  "credits_charged": 1,      // 0 when the call failed
  "timing": {
    "queued_ms": 400,
    "ran_ms": 8100,
    "attempts": 1            // >1 means it was retried
  },
  "result": { "items": [ … ] }
}

轮询结果

GET /v1/requests/{request_id}

返回形状和上面一样。建议 2 秒一次，退避到 5 秒。

计费口径

失败不收钱。验证码、限流、超时、我们这边没映射好，全算我们的问题，自动退回。
「没搜到」照常收钱。那是一个结论而不是故障，而成本已经发生了。

收费的 outcome

no_resultsokverified_page

不收费的 outcome

bad_paramscancelledcaptchaclaim_timeoutneeds_mappingnot_configuredrate_limitedtimeouttransient

没见过的 outcome 一律不收费。默认收钱会把我们的故障变成你的账单。

能力与参数

op	credit	参数	说明
brave.search	1	keyword*, limit, region, language	网页搜索结果：标题、链接、摘要。速度快，适合大量并发。	试一下
github.repo	1	repo*	单个 GitHub 仓库：星数、fork、开着的 issue、语言、协议和标签。	试一下
github.search	1	query*, sort, order, limit	GitHub 仓库搜索，可按星数、fork 数或更新时间排序。	试一下
google.search	1	keyword*, limit, language, region	Google 自然搜索结果：标题、地址、来源域名和摘要。	试一下
google.trends	1	keyword*, region	Google Trends 搜索兴趣：过去两年的周序列（0–100）。	试一下
hn.comments	1	keyword*, limit, sort, since	Hacker News 评论搜索：评论原文、作者和所属帖子。	试一下
hn.item	1	id*, comments	一个 Hacker News 帖子的完整讨论：正文和全部评论。	试一下
hn.search	1	keyword*, limit, sort, since, min_points	Hacker News 帖子：标题、外链、作者、分数、回复数和时间。	试一下

错误码

码	含义	下一步
400	参数不合法 / op 不存在	改请求。不扣费
401	key 不对或已吊销	换一把 key
402	credit 不够	升级或等下个月重置
403	这把 key 的白名单里没有这个能力	看响应里的 `error` 字段
429	超了速率或并发	退避重试。不扣费
502	我们这边或上游出问题	重试。不扣费

速率与并发

每把 key 默认 60 次/分钟，并发若干。超了是 429 而不是排队。

要更高的额度就说一声。