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`	单次请求最多搜几轮(控制成本)。不填用平台默认。
`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.10 / 次搜索
搜索结果 token	按所用模型的标准 input 单价

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

控制成本三招:

设 max_uses 限制搜索轮数。

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

用 allowed_domains 收窄搜索范围。

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

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

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

OpenAI 协议下怎么用

如果你走 /v1/chat/completions(OpenAI 格式),用法取决于你的 key 绑定的渠道:绑 OpenRouter 类渠道的,用该上游的搜索工具写法(如 tools:[{"type":"openrouter:web_search"}]);其余情况优先用 /v1/messages + synthorai:web_search,兼容性最好。联系我们,我们按你的 key 帮你确认最合适的写法。

常见问题

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

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

搜索失败会怎样?

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

会不会我没要求就联网?

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