Indbygget websøgning

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 er en almindelig chat completion med to tilføjelser. Svaret peger på søgeresultaterne med tal i kantede parenteser, sources fortæller, hvad hvert tal står for, og annotations markerer, hvor hvert af dem citeres:

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

Sådan slår du søgning til

Søgning er et felt i anmodningen, som standard slået fra. Der søges ikke, medmindre en anmodning sender det.

På /v1/messages står feltet på øverste niveau i body'en, ved siden af model og messages:

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

Hvad en anmodning med søgning gør

• API'et søger på nettet efter den sidste brugerbesked. Samtalens tidligere ture giver søgningen dens kontekst.
• Søgningen kører på hver anmodning, der sender web_search: true. Modellen vælger ikke, om der skal søges.
• Resultaterne lægges foran modellen som nummererede kilder, og modellen skriver sit svar ud fra dem.
• Svaret starter, når søgningen er færdig. En anmodning med streaming sender intet, hverken headers eller hændelser, før da, så regn med en længere ventetid før det første chunk.

Hvad svaret indeholder

• Svaret har sit endpoints sædvanlige form. Svaret står i choices[0].message.content (en text-blok på /v1/messages).
• Teksten kan indeholde mærker som [1] og [2] efter de udsagn, de understøtter. Hvert tal står for et af de resultater, modellen læste.
• sources navngiver disse resultater: én post for hvert resultat, modellen fik, med index, title og url. Markøren [1] er posten med index 1. Resultater, som svaret ikke citerer, er også med på listen.
• På /v1/chat/completions har beskeden også annotations, i OpenAI-formen: én url_citation for hver kilde, en markør nævner, med url, title samt start_index og end_index, markørens position i content talt i tegn (slutningen er ikke med).
• I en stream kommer sources med det sidste chunk, og på /v1/messages med message_delta-hændelsen. Annotationerne kommer i ét chunk lige før det sidste, som delta.annotations.
• sources er der kun, hvis søgningen i denne anmodning fandt noget. Et svar uden det blev skrevet uden søgeresultater.

Hvordan søgninger tælles

Hver plan indeholder et antal søgninger per dag:

• En anmodning, hvor søgningen fandt noget, bruger én søgning af dagens kvote. En søgning, der intet fandt, bruger ingen.
• Chat og API deler kvoten for den konto, der ejer nøglen.
• Tællingen starter forfra hver dag kl. 00:00 UTC.
• Søgeresultaterne er input-tokens i anmodningen og afregnes sammen med resten af prompten.

Sammenlign planerne

Når dagens søgninger er brugt op

En anmodning, der sender web_search: true efter dagens sidste søgning, afvises ikke. Den besvares uden søgning: statussen er 200, og svaret har ingen sources.

Søgning som dit eget værktøj

web_search: true er den eneste kontakt for den søgning, der er beskrevet her. En funktion, du selv definerer i tools og kalder web_search, er et af dine egne værktøjer: modellen returnerer et kald, og din kode kører søgningen og sender resultatet tilbage.

Søgeværktøjstyper fra andre platforme, f.eks. web_search_20250305 på /v1/messages eller {"type": "web_search"} på /v1/responses, starter ikke en søgning her.

Fejl

Websøgning tilføjer ingen statuskode og ingen fejltype. En søgning, der intet finder, eller en dag uden søgninger tilbage, giver et normalt svar uden søgeresultater. Alle andre fejl er de samme som for en anmodning uden søgning. Fejlhåndtering