Web Search

Claude がリアルタイムでウェブ検索しながら回答できるようにします。最新ニュース・価格・バージョン・スケジュール・学習カットオフ後の事実の調査に最適です。

クイックスタート

/v1/messages リクエストの tools 配列に 1 エントリ追加するだけです。検索するかどうか・何を・何回検索するかはモデルが自動判断します:

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 / 回の検索
検索結果のトークン	使用モデルの標準 input 単価

課金は 2 つの部分からなります: 実行された検索ごとに $0.01、加えて返されたウェブコンテンツが input トークンとして課金されます（検索 1 回あたり約 7,000〜14,000 トークン）。検索付きリクエストは通常のリクエストよりかなり高くなります。max_uses で検索回数を制限してください。

コストを抑える 3 つの方法:

max_uses を設定して検索ラウンド数を制限する。

プロンプトキャッシュを活用する（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 互換の 2 つのエンドポイントでは、取得したソースが OpenAI の annotations(url_citation 形式)として返ります — chat completions ではメッセージに、responses では output_text 項目に付きます。/v1/messages では同じ検索が server_tool_use と web_search_tool_result ブロックとして返ります。いずれのエンドポイントでも usage は検索が要した全ラウンドを含むため、課金されるトークンと表示されるトークンは一致します。OpenRouter にプロキシするチャネルでは、上流独自の検索ツール構文(例:tools:[{"type":"openrouter:web_search"}])も使えます。synthorai: パラメータは /v1/messages、/v1/chat/completions、/v1/responses で受け付けます。Gemini 系エンドポイントに送ると、モデルが認識しないツールを上流へ素通しするのではなく、その旨を説明する 400 を返します。ご不明な場合はお問い合わせください。お使いのキーに適した方法をご案内します。

予約済みツール名

synthorai:web_search を宣言している間、裸の名前 web_search は予約されています。この名前で独自ツールを宣言すると、その名前を示す 400 が返ります。ツール名を変更するか、synthorai: パラメータを外してください。当社はまさにこの名前で検索ツールを注入するため、同名のツールが 2 つモデルに届くと、返ってきた呼び出しがどちらのものか判別できなくなります。synthorai: パラメータを使わずにこの名前で独自ツールを宣言する場合は影響ありません — 注入が行われないため衝突しません。

よくある質問

Claude Code / Anthropic SDK を使っていますが、使用できますか?

はい。/v1/messages エンドポイントに synthorai:web_search を指定して使用できます。純粋な OpenAI 形式のリレーチャンネルにバインドされているキーの場合、ネイティブ検索ツールが機能しないことがあります。その場合は専用チャンネルを設定いたします。

検索が失敗した場合はどうなりますか?

失敗した検索ラウンドは課金されません。モデルは失敗通知を受け取り、別のクエリで再試行するか、既存の知識をもとに回答します。リクエスト全体がエラーになることはありません。

要求していないのにウェブ検索が実行されることはありますか?

ありません。tools 配列に synthorai:web_search を明示的に追加した場合のみウェブ検索が実行されます。通常のリクエストでは絶対に検索は行われません。