内蔵Web検索

web_search: true を指定すると、モデルは最新の検索結果を根拠に回答します。

POST https://api.shannon-ai.com/v1/chat/completions

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

response = client.chat.completions.create(
    model="shannon-3",
    messages=[{"role": "user", "content": "What is the weather forecast for Lisbon this weekend?"}],
    extra_body={"web_search": True},  # a Shannon field, so it goes in extra_body
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });

const response = await client.chat.completions.create({
  model: "shannon-3",
  messages: [{ role: "user", content: "What is the weather forecast for Lisbon this weekend?" }],
  web_search: true,
});

console.log(response.choices[0].message.content);

curl https://api.shannon-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "messages": [
      {"role": "user", "content": "What is the weather forecast for Lisbon this weekend?"}
    ],
    "web_search": true
  }'

応答は通常のチャット補完で、二つの追加があります。回答は角括弧で囲んだ番号で検索結果を参照し、sources は各番号が何を指すかを示し、annotations はそれぞれがどこで引用されているかを示します。

200 JSON

{
  "id": "chatcmpl-3e5a7c9b1d2f4a6c8e0b2d4f6a8c1e3b",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Saturday in Lisbon is forecast to be sunny with a high near 24 °C [1]. Sunday turns cloudy, with a chance of light rain in the afternoon [2].",
        "reasoning_content": null,
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "start_index": 66,
              "end_index": 69,
              "url": "https://weather.example/lisbon/weekend",
              "title": "Lisbon weather: weekend outlook"
            }
          },
          {
            "type": "url_citation",
            "url_citation": {
              "start_index": 137,
              "end_index": 140,
              "url": "https://forecast.example/pt/lisbon/sunday",
              "title": "Sunday forecast for Lisbon"
            }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2874,
    "completion_tokens": 41,
    "total_tokens": 2915
  },
  "sources": [
    {
      "index": 1,
      "title": "Lisbon weather: weekend outlook",
      "url": "https://weather.example/lisbon/weekend"
    },
    {
      "index": 2,
      "title": "Sunday forecast for Lisbon",
      "url": "https://forecast.example/pt/lisbon/sunday"
    },
    {
      "index": 3,
      "title": "Portugal: the week ahead",
      "url": "https://news.example/portugal/weather-week"
    }
  ]
}

検索をオンにする

検索はリクエストのフィールドで、デフォルトではオフです。リクエストが指定しない限り、何も検索されません。

フィールド	型	デフォルト	説明	適用モデル
`web_search`	`boolean`	`false`	`true` を指定すると、このリクエストのウェブ検索を実行し、回答する前に結果をモデルに渡します。	`shannon-coder-1` を除くすべての Shannon モデル

エンドポイント	ウェブ検索	方法
`/v1/chat/completions`	はい	リクエストボディに `"web_search": true`。
`/v1/messages`	はい	リクエストボディに `"web_search": true`。
`/v1/responses`	—	このエンドポイントは、モデルだけで回答します。検索付きの回答が必要な場合は、上の二つのいずれかを使ってください。

/v1/messages では、このフィールドはボディの最上位で、model と messages の隣に置きます。

リクエストボディ

{
  "model": "shannon-3",
  "web_search": true,
  "messages": [
    {
      "role": "user",
      "content": "What is the weather forecast for Lisbon this weekend?"
    }
  ]
}

検索付きリクエストの動作

API は、最後のユーザーメッセージについてウェブを検索します。会話のそれ以前のターンが、検索の文脈になります。
web_search: true を送信したすべてのリクエストで、検索が実行されます。検索するかどうかをモデルが選ぶことはありません。
結果は番号付きのソースとしてモデルの前に置かれ、モデルはそれらから回答を書きます。
応答は、検索が終わると始まります。ストリームのリクエストは、それまでヘッダーもイベントも送信しないため、最初のチャンクまでの待ち時間を長めに見込んでください。

応答の内容

応答は、そのエンドポイントの通常の形式です。回答は choices[0].message.content にあります（/v1/messages では text ブロック）。
テキストには、根拠となる記述の後ろに [1] や [2] のようなマーカーが付くことがあります。各番号は、モデルが読んだ結果のひとつを表します。
sources はそれらの結果を示します。モデルに渡された結果ごとにひとつのエントリがあり、index、title、url を持ちます。マーカー [1] は index が 1 のエントリです。回答が引用していない結果も一覧に含まれます。
/v1/chat/completions では、メッセージに OpenAI 形式の annotations も含まれます。マーカーが示すソースごとにひとつの url_citation があり、url、title、start_index、end_index を持ちます。マーカーの位置は content 内で文字数で数えた値です（終了位置は含みません）。
ストリームでは、sources は最後のチャンクと一緒に届き、/v1/messages では message_delta イベントと一緒に届きます。アノテーションは、最後の直前のチャンクに delta.annotations として届きます。
sources は、このリクエストの検索で何かが見つかった場合にのみ存在します。これがない応答は、検索結果なしで書かれました。

検索の数え方

すべてのプランに、一日あたりの検索回数が含まれています。

プラン	一日あたりの検索回数
無料	3
プラス	30
Standard	50
プロ	60

検索で結果が見つかったリクエストは、その日の枠のうち一回分の検索を使います。何も見つからなかった検索は、枠を使いません。
チャットと API は、キーを所有するアカウントの枠を共有します。
カウントは毎日 00:00 UTC にリセットされます。
検索結果はリクエストの入力トークンとなり、プロンプトの他の部分と一緒に課金されます。

プランを比較する

その日の検索回数を使い切ったとき

その日の最後の検索の後に web_search: true を送信したリクエストは、拒否されません。検索なしで応答されます。ステータスは 200 で、応答に sources はありません。

独自のツールとしての検索

web_search: true は、ここで説明している検索の唯一のスイッチです。tools で定義して web_search と名付けた関数は、あなた自身のツールのひとつです。モデルが呼び出しを返し、お使いのコードが検索を実行して結果を送り返します。

他のプラットフォームの検索ツールタイプ（/v1/messages の web_search_20250305 や、/v1/responses の {"type": "web_search"} など）では、ここでは検索が開始されません。

エラー

ウェブ検索によって、ステータスコードもエラータイプも追加されません。何も見つからなかった検索や、その日の検索回数が残っていない場合は、検索結果なしの通常の回答になります。それ以外のエラーは、検索なしのリクエストと同じです。エラー処理