Ingebouwde webzoekopdracht

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

Het antwoord is een gewone chat completion met twee toevoegingen. Het antwoord verwijst met nummers tussen vierkante haken naar de zoekresultaten, sources zegt waar elk nummer voor staat, en annotations markeert waar elk ervan wordt aangehaald:

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

Zoeken inschakelen

Zoeken is een veld van de aanvraag en staat standaard uit. Er wordt niets gezocht tenzij een aanvraag het meestuurt.

Op /v1/messages staat het veld op het hoogste niveau van de body, naast model en messages:

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

Wat een aanvraag met zoekopdracht doet

• De API zoekt op het web naar het laatste gebruikersbericht. Eerdere beurten van het gesprek geven de zoekopdracht haar context.
• De zoekopdracht wordt uitgevoerd bij elke aanvraag die web_search: true meestuurt. Het model kiest niet of het zoekt.
• De resultaten worden als genummerde bronnen aan het model voorgelegd, en het model schrijft zijn antwoord daaruit.
• Het antwoord begint zodra het zoeken klaar is. Een aanvraag met streaming stuurt tot dan niets, geen headers en geen events, dus houd rekening met een langere wachttijd vóór de eerste chunk.

Wat het antwoord bevat

• Het antwoord heeft de gebruikelijke vorm van zijn endpoint. Het antwoord staat in choices[0].message.content (een text-blok op /v1/messages).
• De tekst kan markeringen bevatten zoals [1] en [2] na de uitspraken die ze onderbouwen. Elk nummer staat voor een van de resultaten die het model heeft gelezen.
• sources noemt die resultaten: één item voor elk resultaat dat het model kreeg, met index, title en url. De markering [1] is het item met index 1. Resultaten die het antwoord niet aanhaalt, staan ook in de lijst.
• Op /v1/chat/completions heeft het bericht ook annotations, in de vorm van OpenAI: één url_citation voor elke bron die een markering noemt, met url, title, en start_index en end_index, de positie van de markering in content, geteld in tekens (het einde hoort er niet bij).
• In een stream komt sources mee met de laatste chunk, en op /v1/messages met het event message_delta. De annotations komen in één chunk vlak vóór de laatste, als delta.annotations.
• sources is er alleen als de zoekopdracht van deze aanvraag iets vond. Een antwoord zonder is geschreven zonder zoekresultaten.

Hoe zoekopdrachten worden geteld

Elk plan bevat een aantal zoekopdrachten per dag:

• Een aanvraag waarvan de zoekopdracht iets heeft gevonden, gebruikt één zoekopdracht van de toelage van die dag. Een zoekopdracht die niets vond, gebruikt er geen.
• Chat en API delen de toelage van het account dat de sleutel bezit.
• De telling begint elke dag om 00:00 UTC opnieuw.
• De zoekresultaten zijn inputtokens van de aanvraag en worden met de rest van de prompt gefactureerd.

Vergelijk de plannen

Als de zoekopdrachten van de dag op zijn

Een aanvraag die web_search: true meestuurt na de laatste zoekopdracht van de dag, wordt niet geweigerd. Ze wordt zonder zoekopdracht beantwoord: de status is 200 en het antwoord heeft geen sources.

Zoeken als eigen tool

web_search: true is de enige schakelaar voor het hier beschreven zoeken. Een functie die je in tools definieert en web_search noemt, is een van je eigen tools: het model geeft een aanroep terug, en je code voert de zoekopdracht uit en stuurt het resultaat terug.

Zoektooltypen van andere platforms, zoals web_search_20250305 op /v1/messages of {"type": "web_search"} op /v1/responses, starten hier geen zoekopdracht.

Fouten

Webzoeken voegt geen statuscode en geen fouttype toe. Een zoekopdracht die niets vindt, of een dag zonder resterende zoekopdrachten, geeft een normaal antwoord zonder zoekresultaten. Elke andere fout is dezelfde als bij een aanvraag zonder zoekopdracht. Foutafhandeling