Inbyggd webbsökning

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
  }'

Svaret är en vanlig chat completion med två tillägg. Svaret hänvisar till sökresultaten med nummer inom hakparenteser, sources anger vad varje nummer står för, och annotations markerar var var och en citeras:

{
  "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"
    }
  ]
}

Slå på sökning

Sökning är ett fält i begäran, avstängt som standard. Ingenting söks om inte en begäran skickar det.

På /v1/messages ligger fältet på bodyns översta nivå, bredvid model och messages:

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

Vad en begäran med sökning gör

• API:et söker på webben efter det sista användarmeddelandet. Konversationens tidigare vändningar ger sökningen dess sammanhang.
• Sökningen körs på varje begäran som skickar web_search: true. Modellen väljer inte om den ska söka.
• Resultaten läggs framför modellen som numrerade källor, och modellen skriver sitt svar utifrån dem.
• Svaret börjar när sökningen är klar. En streamad begäran skickar ingenting, varken headers eller händelser, före dess, så räkna med en längre väntan före den första chunken.

Vad svaret innehåller

• Svaret har den vanliga formen för sin endpoint. Svaret finns i choices[0].message.content (ett text-block på /v1/messages).
• Texten kan bära markörer som [1] och [2] efter de påståenden de stöder. Varje nummer står för ett av de resultat som modellen läste.
• sources namnger dessa resultat: en post för varje resultat som modellen fick, med index, title och url. Markören [1] är posten med index 1. Resultat som svaret inte citerar listas också.
• På /v1/chat/completions har meddelandet också annotations, i OpenAI-form: en url_citation för varje källa som en markör namnger, med url, title samt start_index och end_index, markörens position i content räknad i tecken (slutet ingår inte).
• I en ström kommer sources med den sista chunken, och på /v1/messages med händelsen message_delta. Annotations kommer i en chunk strax före den sista, som delta.annotations.
• sources finns bara om sökningen för denna begäran fann något. Ett svar utan det skrevs utan sökresultat.

Hur sökningar räknas

Varje plan ingår med ett antal sökningar per dag:

• En begäran vars sökning hittade något använder en sökning av dagens kvot. En sökning som inte hittade något använder ingen.
• Chatten och API:et delar kvoten för det konto som äger nyckeln.
• Räkningen börjar om varje dag kl. 00:00 UTC.
• Sökresultaten är inputtokens i begäran och faktureras tillsammans med resten av prompten.

Jämför planerna

När dagens sökningar är förbrukade

En begäran som skickar web_search: true efter dagens sista sökning avvisas inte. Den besvaras utan sökning: statusen är 200 och svaret har inga sources.

Sökning som ett eget verktyg

web_search: true är den enda omkopplaren för den sökning som beskrivs här. En funktion som du definierar i tools och döper till web_search är ett av dina egna verktyg: modellen returnerar ett anrop, och din kod kör sökningen och skickar tillbaka resultatet.

Söktyper för verktyg på andra plattformar, som web_search_20250305 på /v1/messages eller {"type": "web_search"} på /v1/responses, startar ingen sökning här.

Fel

Webbsökning lägger inte till någon statuskod och ingen feltyp. En sökning som inte hittar något, eller en dag utan sökningar kvar, ger ett normalt svar utan sökresultat. Varje annat fel är detsamma som för en begäran utan sökning. Felhantering