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