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

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

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

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

プロンプトキャッシュを活用する（cache_control 使用時に結果がキャッシュされ、マルチターン会話で大幅に節約できます）。

allowed_domains で検索範囲を絞り込む。

参考ベンチマーク（claude-sonnet-4-6、キャッシュなし）:

軽度（検索 2 回、事実確認）: ≈ $0.25 / リクエスト

重度（検索 8 回、リサーチ）: ≈ $1.05 / リクエスト

OpenAI 互換エンドポイントでの使用

/v1/chat/completions（OpenAI 形式）を使用する場合、動作はキーがバインドされているチャンネルに依存します。OpenRouter にプロキシするチャンネルはそのアップストリームの検索ツール構文を使用してください（例: tools:[{"type":"openrouter:web_search"}]）。それ以外のケースでは、/v1/messages + synthorai:web_search が最も互換性が高いため推奨します。お使いのキーに最適な方法についてはお気軽にお問い合わせください。

よくある質問

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

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

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

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

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

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