网页搜索与抓取
用同一个 API Key 调用网页搜索和网页正文抓取，按次计费。
两个端点：POST /tools/v1/search 返回搜索结果，POST /tools/v1/fetch 返回网页正文（Markdown）。
它们是 JuCode 平台自己的接口，不是模型，与 OpenAI、Anthropic 兼容端点分开：不需要选择模型或分组，
鉴权方式与对话接口相同。逐字段说明见 API 参考的网页搜索和
网页抓取。
网页搜索
curl https://api.jucode.cn/tools/v1/search \
-H "Authorization: Bearer $JUCODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "rust async runtime comparison", "max_results": 5}'| 字段 | 类型 | 说明 |
|---|---|---|
query | string | 必填，最多 400 字符 |
engine | string | auto（默认）、parallel、brave |
max_results | integer | 1–10，默认 10 |
freshness | string | 只返回这段时间内发布的网页：day、week、month、year |
auto 由网关按可用性选择引擎，某个引擎故障时自动换用另一个。
{
"object": "web.search",
"engine": "parallel",
"query": "rust async runtime comparison",
"results": [
{
"title": "Async Rust runtimes compared",
"url": "https://example.com/runtimes",
"snippet": "Tokio remains the default choice ...",
"published_at": "2026-08-14"
}
]
}engine 是实际响应的引擎。published_at 为 YYYY-MM-DD，引擎未提供时省略。
网页抓取
curl https://api.jucode.cn/tools/v1/fetch \
-H "Authorization: Bearer $JUCODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/runtimes", "engine": "jina"}'| 字段 | 类型 | 说明 |
|---|---|---|
url | string | 必填，http:// 或 https:// 开头的绝对地址，不能包含账号密码，不能是 localhost 或内网 IP |
engine | string | jina（默认）、firecrawl、parallel |
{
"object": "web.fetch",
"engine": "jina",
"url": "https://example.com/runtimes",
"title": "Async Rust runtimes compared",
"content": "# Async Rust runtimes compared\n\n...",
"status": 200
}url 是抓取的地址：firecrawl 返回跳转后的最终地址，其他引擎返回请求的地址。
status 是目标网页返回的 HTTP 状态码，published_at 是网页发布日期（YYYY-MM-DD），引擎未提供时都省略。
status 为 4xx/5xx 时，content 是该错误页面的内容，本次调用照常计费。
目标网页取不到时（域名无法解析、页面没有正文等）返回 422 fetch_failed，不扣费。
firecrawl 会渲染需要 JavaScript 的页面，适合 jina 抓不到正文的网站。
计费与限流
按次计费，每次成功调用扣一次费用，失败的请求不扣费。费用只从账户余额扣除，不使用套餐额度； 组织 Key 从组织余额扣除。API Key 设置的花费上限对这两个接口同样生效。
当前价格（实时读取 GET /api/tools/pricing）：
价格加载中…
每个用户每分钟的调用次数有上限（搜索与抓取合计），超出返回 429 rpm_limit，一分钟后恢复。
调用记录出现在控制台的用量日志里，显示为「网页搜索 · 引擎」或「网页抓取 · 引擎」。
错误
错误信封与其他 /v1/* 端点相同，见错误码。这两个端点特有的：
| HTTP | code | 含义 |
|---|---|---|
| 400 | invalid_web_request | 参数不合法，例如 query 为空、engine 不存在 |
| 400 | engine_disabled | 该引擎已停用，换一个引擎 |
| 402 | billing_rejected | 余额不足，充值后再试 |
| 422 | fetch_failed | 引擎没能取到这个网页，例如域名无法解析或页面没有正文；不扣费，可以换一个引擎再试 |
| 429 | rpm_limit | 超出每分钟调用上限，一分钟后再试 |
| 502 / 503 | upstream_unavailable | 所选引擎的所有上游暂时不可用，稍后重试或换一个引擎 |