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 才會。普通請求永遠不聯網。