Web Search

让 Claude 在回答时实时联网搜索。适用于查最新信息:新闻、价格、版本、日程、训练数据截止后的事实。

快速开始

在 /v1/messages 请求的 tools 数组里加一条。模型自己决定要不要搜、搜什么、搜几次:

curl https://synthorai.io/v1/messages \
  -H "x-api-key: $YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "tools": [{"type": "synthorai:web_search"}],
    "messages": [
      {"role": "user", "content": "What is the latest Claude model?"}
    ]
  }'

ℹ

只有在 tools 里显式加了 synthorai:web_search 才会联网。不加就是普通请求——行为和成本完全不变。

可选参数

synthorai:web_search 条目上的所有字段都可选:

参数	说明
`max_uses`	单次请求最多搜几轮(控制成本)。不填用平台默认。默认 3,上限 10。
`allowed_domains`	只在这些域名里搜(如 `["arxiv.org","github.com"]`)。
`blocked_domains`	排除这些域名。

{
  "type": "synthorai:web_search",
  "max_uses": 3,
  "allowed_domains": ["anthropic.com", "openai.com"]
}

响应结构

带搜索的响应在 content 里依次包含以下块类型:

server_tool_use - 模型发起的搜索(含所用查询词)。
web_search_tool_result - 搜索结果(标题、URL、摘要)。
text - 基于结果的最终回答,含来源引用。

usage 对象里会多一个字段,告诉你本次实际执行了几次搜索:

"usage": {
  "input_tokens": 14577,
  "output_tokens": 331,
  "server_tool_use": { "web_search_requests": 2 }
}

计费

项目	价格
搜索费	$0.01 / 次搜索
搜索结果 token	按所用模型的标准 input 单价

计费分两部分:每次执行的搜索按 $0.01 计,加上搜回来的网页内容按 input token 计费(每次约 7,000~14,000 token)。带搜索的请求明显比普通请求贵,用 max_uses 控制搜索轮数。

控制成本三招:

设 max_uses 限制搜索轮数。

用 prompt cache(带 cache_control 时结果会被缓存,多轮对话省很多)。

用 allowed_domains 收窄搜索范围。

参考实测(claude-sonnet-4-6,无缓存):

轻度(2 次搜索,查个事实):≈ $0.07 / 请求

重度(8 次搜索,做研究):≈ $0.33 / 请求

OpenAI 协议下怎么用

synthorai:web_search 在 /v1/chat/completions 与 /v1/responses 上同样可用 —— 写法与发给 /v1/messages 的那条声明完全一致。各端点分别返回什么:两个 OpenAI 兼容端点上,我们检索到的来源以 OpenAI 的 annotations(url_citation 形状)返回 —— chat completions 挂在 message 上,responses 挂在 output_text 条目上;/v1/messages 上同一次搜索则以 server_tool_use 与 web_search_tool_result 块返回。所有端点的 usage 都覆盖搜索经过的每一轮 —— 你被计费的 token 就是你看得到的 token。代理到 OpenRouter 的渠道也可以改用上游自己的搜索工具语法(如 tools:[{"type":"openrouter:web_search"}])。synthorai: 参数在 /v1/messages、/v1/chat/completions 与 /v1/responses 上被接受 —— 发到 Gemini 系端点会返回一条说明情况的 400,而不是把一个模型不认识的工具直发上游。拿不准可以联系我们确认你这把 key 该怎么用。

保留的工具名

在你声明 synthorai:web_search 期间,裸名 web_search 是保留的:用这个名字声明你自己的工具会得到一条指明工具名的 400。把你的工具改个名,或去掉 synthorai: 参数即可。原因是我们正是以那个名字注入搜索工具的,两个同名工具同时到达模型时,双方都无法判断回来的调用是谁的。若你**没有**使用 synthorai: 参数,用这个名字声明自己的工具完全不受影响 —— 我们不注入,也就不会冲突。

常见问题

我用 Claude Code / Anthropic SDK,能用吗?

能——用 /v1/messages 端点 + synthorai:web_search。如果你的 key 绑定的是纯 OpenAI 格式的中转渠道,原生搜索工具可能不生效,这种情况我们会给你单独配好。

搜索失败会怎样?

单次搜索失败不计费,模型会收到失败提示并尝试换个方式或基于已有知识回答,不会整个请求报错。

会不会我没要求就联网?

不会。只有你在 tools 里显式加了 synthorai:web_search 才会。普通请求永远不联网。