Innebygd websøk

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 vanlig chat completion med to tillegg. Svaret peker til søkeresultatene med tall i hakeparenteser, sources sier hva hvert tall står for, og annotations markerer hvor hver av dem siteres:

{
  "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øk

Søk er et felt i forespørselen, av som standard. Ingenting søkes etter med mindre en forespørsel sender det.

På /v1/messages ligger feltet på øverste nivå i kroppen, ved siden av model og messages:

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

Hva en forespørsel med søk gjør

• API-et søker på nettet etter den siste brukermeldingen. Tidligere runder i samtalen gir søket kontekst.
• Søket kjører på hver forespørsel som sender web_search: true. Modellen velger ikke om det skal søkes.
• Resultatene legges fram for modellen som nummererte kilder, og modellen skriver svaret sitt ut fra dem.
• Svaret starter når søket er ferdig. En forespørsel med streaming sender ingenting, verken headere eller hendelser, før da, så regn med en lengre ventetid før den første chunken.

Hva svaret inneholder

• Svaret har den vanlige formen for endepunktet. Svaret står i choices[0].message.content (en text-blokk på /v1/messages).
• Teksten kan ha markører som [1] og [2] etter påstandene de støtter. Hvert nummer står for et av resultatene modellen leste.
• sources navngir disse resultatene: én oppføring for hvert resultat modellen fikk, med index, title og url. Markøren [1] er oppføringen med index 1. Resultater som svaret ikke siterer, står også i listen.
• På /v1/chat/completions har meldingen også annotations, i OpenAI-formen: én url_citation for hver kilde en markør navngir, med url, title, og start_index og end_index, posisjonen til markøren i content talt i tegn (slutten er ikke med).
• I en strøm kommer sources med den siste chunken, og på /v1/messages med hendelsen message_delta. Annotasjonene kommer i én chunk rett før den siste, som delta.annotations.
• sources finnes bare når søket i denne forespørselen fant noe. Et svar uten er skrevet uten søkeresultater.

Hvordan søk telles

Hver plan inkluderer et antall søk per dag:

• En forespørsel der søket fant noe, bruker ett søk av dagens kvote. Et søk som ikke fant noe, bruker ingen.
• Chat og API deler kvoten til kontoen som eier nøkkelen.
• Tellingen starter på nytt hver dag kl. 00:00 UTC.
• Søkeresultatene er input-tokens i forespørselen og faktureres sammen med resten av prompten.

Sammenlign planene

Når dagens søk er brukt opp

En forespørsel som sender web_search: true etter dagens siste søk, avvises ikke. Den besvares uten søk: statusen er 200 og svaret har ingen sources.

Søk som et eget verktøy

web_search: true er den eneste bryteren for søket som beskrives her. En funksjon du definerer i tools og kaller web_search, er et av dine egne verktøy: modellen returnerer et kall, og koden din kjører søket og sender resultatet tilbake.

Søkeverktøytyper fra andre plattformer, som web_search_20250305 på /v1/messages eller {"type": "web_search"} på /v1/responses, starter ikke et søk her.

Feil

Websøk legger ikke til noen statuskode og ingen feiltype. Et søk som ikke finner noe, eller en dag uten søk igjen, gir et vanlig svar uten søkeresultater. Alle andre feil er de samme som for en forespørsel uten søk. Feilhåndtering