Integrierte Websuche

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

Die Antwort ist eine gewöhnliche Chat Completion mit zwei Ergänzungen. Die Antwort verweist mit Zahlen in eckigen Klammern auf die Suchergebnisse, sources sagt, wofür jede Zahl steht, und annotations markiert, wo jedes davon zitiert wird:

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

Die Suche einschalten

Die Suche ist ein Feld der Anfrage und standardmäßig aus. Es wird nichts gesucht, außer eine Anfrage sendet es.

Bei /v1/messages steht das Feld auf oberster Ebene des Bodys, neben model und messages:

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

Was eine Anfrage mit Suche tut

• Die API durchsucht das Web nach der letzten User-Nachricht. Frühere Turns der Konversation geben der Suche ihren Kontext.
• Die Suche läuft bei jeder Anfrage, die web_search: true sendet. Das Modell entscheidet nicht, ob es sucht.
• Die Ergebnisse werden dem Modell als nummerierte Quellen vorgelegt, und das Modell schreibt seine Antwort daraus.
• Die Antwort beginnt, wenn die Suche abgeschlossen ist. Eine gestreamte Anfrage sendet bis dahin nichts, weder Header noch Events, planen Sie daher eine längere Wartezeit bis zum ersten Chunk ein.

Was die Antwort enthält

• Die Antwort hat die übliche Form ihres Endpunkts. Die Antwort steht in choices[0].message.content (ein text-Block bei /v1/messages).
• Der Text kann Markierungen wie [1] und [2] hinter den Aussagen tragen, die sie belegen. Jede Zahl steht für eines der Ergebnisse, die das Modell gelesen hat.
• sources benennt diese Ergebnisse: ein Eintrag für jedes Ergebnis, das dem Modell gegeben wurde, mit index, title und url. Der Marker [1] ist der Eintrag mit index 1. Ergebnisse, die die Antwort nicht zitiert, sind ebenfalls aufgeführt.
• Bei /v1/chat/completions hat die Nachricht außerdem annotations, in der Form von OpenAI: ein url_citation für jede Quelle, die ein Marker nennt, mit url, title sowie start_index und end_index, der Position des Markers in content, in Zeichen gezählt (das Ende ist nicht eingeschlossen).
• In einem Stream kommt sources mit dem letzten Chunk, bei /v1/messages mit dem Event message_delta. Die Annotationen kommen in einem Chunk direkt vor dem letzten, als delta.annotations.
• sources ist nur vorhanden, wenn die Suche dieser Anfrage etwas gefunden hat. Eine Antwort ohne dieses Feld wurde ohne Suchergebnisse geschrieben.

Wie Suchen gezählt werden

Jeder Plan enthält eine Anzahl Suchen pro Tag:

• Eine Anfrage, deren Suche etwas gefunden hat, verbraucht eine Suche des Tageskontingents. Eine Suche, die nichts gefunden hat, verbraucht keine.
• Chat und API teilen das Kontingent des Kontos, dem der Key gehört.
• Die Zählung beginnt jeden Tag um 00:00 UTC von neuem.
• Die Suchergebnisse sind Input-Tokens der Anfrage und werden mit dem Rest des Prompts berechnet.

Pläne vergleichen

Wenn die Suchen des Tages aufgebraucht sind

Eine Anfrage, die web_search: true nach der letzten Suche des Tages sendet, wird nicht abgelehnt. Sie wird ohne Suche beantwortet: Der Status ist 200, und die Antwort hat kein sources.

Suche als eigenes Tool

web_search: true ist der einzige Schalter für die hier beschriebene Suche. Eine Funktion, die Sie in tools definieren und web_search nennen, ist eines Ihrer eigenen Tools: Das Modell gibt einen Aufruf zurück, und Ihr Code führt die Suche aus und sendet das Ergebnis zurück.

Such-Tool-Typen anderer Plattformen, etwa web_search_20250305 bei /v1/messages oder {"type": "web_search"} bei /v1/responses, starten hier keine Suche.

Fehler

Die Websuche fügt weder einen Statuscode noch einen Fehlertyp hinzu. Eine Suche, die nichts findet, oder ein Tag ohne verbleibende Suchen ergibt eine normale Antwort ohne Suchergebnisse. Jeder andere Fehler ist derselbe wie bei einer Anfrage ohne Suche. Fehlerbehandlung