快速回答
LLMWebSearch API 对一次搜索返回什么?
LLMWebSearch 返回 JSON,包含 query、created_at、credits_used 以及一个按排名排列的 results 数组。每条结果包含其位置、标题、URL、host 和摘要,以及一个 content_status;当它为 ok 时,页面的正文内容位于 content 中,并带有一个 word_count。一次最多读取 3 个页面的搜索花费 1 积分,低至 US$1.20/千次搜索(截至 2026 年 10 月)。无需 KYC;用加密货币支付。
哪些字段描述此次调用?
/search 响应的顶层。
| 字段 | 类型 | 含义 |
|---|---|---|
query | string | 我们实际执行的查询,已去除首尾空格 |
created_at | string | 搜索执行的时间,ISO 8601 格式,UTC 时区 |
credits_used | integer | 此次调用的费用:1;当 read 为 4 到 10 时为 2 |
results | array | 按排名排列的结果,最优在前,最多 max_results 条 |
每条结果包含哪些字段?
页面或搜索结果未提供的字段会被省略,而不会以空值发送。
| 字段 | 类型 | 出现时机 | 含义 |
|---|---|---|---|
position | integer | 始终 | 搜索中的排名,从 1 开始 |
title | string | 始终 | 结果的标题 |
url | string | 始终 | 页面的地址 |
host | string | 始终 | 页面的主机名,便于分组或引用 |
snippet | string | 始终 | 搜索展示的简短摘录 |
published_at | string | 当日期已知时 | 来自页面或搜索结果的发布日期 |
content_status | string | 始终 | 页面是否已读取,若未读取,原因是什么 |
content | string | 当 content_status 为 ok 时 | 正文内容,格式为 Markdown 或纯文本,在 max_chars 处截断 |
word_count | integer | 当 content_status 为 ok 时 | 整个提取文本中的词数,在截断前统计 |
target_status | integer | 搭配 target_refused | 网站返回的 HTTP 状态码,例如 403 或 429 |
每个 content_status 分别代表什么?
这些都不会改变本次搜索的价格。它们描述的是单个页面,绝不代表整个调用。
content_status | 含义 | 智能体应当怎么做 |
|---|---|---|
ok | 页面已读取;content 保存其正文 | 直接使用并引用 url |
not_requested | 结果超出了 read 的数量 | 调高 read,如有需要可通过 /extract 读取 |
blocked_by_robots | 该网站的 robots.txt 不允许我们的读取器访问此页面 | 改用摘要片段或其他来源 |
blocked_by_site_policy | 网站声明了 Content-Signal: ai-input=no | 改用摘要片段或其他来源 |
target_refused | 网站拒绝了请求;参见 target_status | 不要重试该页面;改用其他来源 |
fetch_failed | DNS、TLS 或连接错误,或页面已不存在 | 尝试其他结果;稍后重试可能成功 |
fetch_timeout | 页面未在 15 秒内响应 | 尝试其他结果;稍后重试可能成功 |
unsupported_content | 该链接是我们无法转换为文本的文件 | 改用摘要片段或其他结果 |
完整响应是什么样的?
下方示例请求了 5 条结果,其中前 4 条被读取,因此消耗 2 个积分。结果 1 和 3 已读取。结果 2 所属网站的 robots.txt 阻止了我们的读取器,结果 4 拒绝了请求,结果 5 超出 read。标题、URL 和数值仅为示例。
{
"query": "how to rotate api keys without downtime",
"created_at": "2026-10-22T10:15:04Z",
"credits_used": 2,
"results": [
{
"position": 1,
"title": "Rotating API keys",
"url": "https://docs.example.com/security/key-rotation",
"host": "docs.example.com",
"snippet": "Create a second key, deploy it everywhere, then revoke the first one.",
"published_at": "2026-09-30",
"content_status": "ok",
"content": "# Rotating API keys\n\n## Zero-downtime rotation\n\n1. Create a second key.\n2. Deploy it to every service.\n3. Revoke the old key.",
"word_count": 948
},
{
"position": 2,
"title": "Key rotation checklist",
"url": "https://blog.example.org/key-rotation-checklist",
"host": "blog.example.org",
"snippet": "Keep two keys active during the switch and alert on the old one.",
"content_status": "blocked_by_robots"
},
{
"position": 3,
"title": "Secrets management basics",
"url": "https://security.example.net/secrets-basics",
"host": "security.example.net",
"snippet": "Never commit keys to a repository.",
"content_status": "ok",
"content": "# Secrets management basics\n\n**Never** commit keys to a repository.",
"word_count": 1310
},
{
"position": 4,
"title": "Key management service guide",
"url": "https://cloud.example.com/kms-guide",
"host": "cloud.example.com",
"snippet": "Store keys in a managed vault and rotate them on a schedule.",
"content_status": "target_refused",
"target_status": 403
},
{
"position": 5,
"title": "API key best practices",
"url": "https://dev.example.com/api-key-best-practices",
"host": "dev.example.com",
"snippet": "Scope each key to one service and one environment.",
"content_status": "not_requested"
}
]
}哪些结果会得到 not_requested 以外的页面状态?
只有前 read 条结果,以及一次 /extract 调用中的每一项。这些才是我们的阅读器真正尝试抓取的页面。在 read 条之后的所有内容都保持 not_requested,无论网站本来会返回什么。
顺序从不改变:阅读器按位置 1、2、3 依次处理,绝不会跳过前面失败的结果去读后面的结果。如果 agent 需要替代一个被拒绝的页面,它可以通过 /extract 读取下一条结果。
extract 响应长什么样?
/extract 会返回 credits_used 和一个 results 数组,顺序与你发送的 URL 一致。每一项包含 url 和 content_status;启用 ok 时会额外返回 title、content 和 word_count,启用 target_refused 时会额外返回 target_status。不会有 position、host 或 snippet,因为没有运行搜索。
extract 参考文档 提供了一个完整示例,并说明了积分如何计算。
如何把结果转换成模型的上下文?
给来源编号,把 URL 放在每个来源旁边,只传模型需要的内容。紧凑的布局效果很好:先 [1] title — url,然后是该页面的内容,再是下一个来源。让模型用相同的编号引用。
当某条结果没有内容时,改为给模型它的摘要片段,并说明这只是摘要片段。这样可以避免模型基于它从未见过的页面作答。Python 页面 有一个简短的循环,能在 token 预算内完成上述所有操作。
响应格式:常见问题
内容始终是 Markdown 吗?
默认是 Markdown。发送 format: "text" 可以获得不含标记的纯文本,例如当你只需统计字数或对页面分类时。字段名仍是 content。
为什么有些结果缺少 published_at?
许多页面没有标注日期,有些搜索结果也不显示日期。这种情况下该字段会被省略,因此使用前请先检查它是否存在。
以后会出现新字段吗?
会。在版本 1 中,字段可能会新增,但绝不会重命名或删除。请让你的解析器忽略它不认识的字段。
内容会存储在你们这边吗?
不会。我们不会用你的查询或 API 返回的内容训练任何模型,也不会自行添加任何禁止存储结果的规则;你读取的页面所属网站的权利仍然适用。我们的请求日志只保留每次调用的简短记录,详见隐私页面。