Cerca web

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

La resposta és una chat completion normal amb dues addicions. La resposta apunta als resultats de la cerca amb nombres entre claudàtors, sources diu què representa cada nombre i annotations marca on se cita cadascun:

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

Activació de la cerca

La cerca és un camp de la sol·licitud, desactivat per defecte. No es cerca res tret que una sol·licitud l'enviï.

A /v1/messages, el camp és al nivell superior del cos, al costat de model i messages:

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

Què fa una sol·licitud amb cerca

• L'API cerca a la web l'últim missatge d'usuari. Els torns anteriors de la conversa donen context a la cerca.
• La cerca s'executa a cada sol·licitud que envia web_search: true. El model no tria si cerca o no.
• Els resultats es posen davant del model com a fonts numerades, i el model escriu la seva resposta a partir d'ells.
• La resposta comença quan la cerca ha acabat. Una sol·licitud amb streaming no envia res, ni capçaleres ni esdeveniments, fins aleshores, així que compta amb una espera més llarga abans del primer fragment.

Què conté la resposta

• La resposta té la forma habitual del seu endpoint. La resposta és a choices[0].message.content (un bloc text a /v1/messages).
• El text pot portar marcadors com [1] i [2] després de les afirmacions que recolzen. Cada nombre representa un dels resultats que el model ha llegit.
• sources anomena aquests resultats: una entrada per a cada resultat que s'ha donat al model, amb index, title i url. El marcador [1] és l'entrada amb index 1. També s'hi llisten els resultats que la resposta no cita.
• A /v1/chat/completions el missatge també té annotations, amb la forma d'OpenAI: un url_citation per a cada font que anomena un marcador, amb url, title, i start_index i end_index, la posició del marcador a content comptada en caràcters (el final no s'inclou).
• En un stream sources arriba amb l'últim fragment, i a /v1/messages amb l'esdeveniment message_delta. Les anotacions arriben en un fragment just abans de l'últim, com a delta.annotations.
• sources només hi és si la cerca d'aquesta sol·licitud ha trobat alguna cosa. Una resposta sense aquest camp s'ha escrit sense resultats de cerca.

Com es compten les cerques

Cada pla inclou un nombre de cerques per dia:

• Una sol·licitud la cerca de la qual ha trobat alguna cosa gasta una cerca de la quota del dia. Una cerca que no ha trobat res no en gasta cap.
• El xat i l'API comparteixen la quota del compte propietari de la clau.
• El recompte torna a començar cada dia a les 00:00 UTC.
• Els resultats de la cerca són tokens d'entrada de la sol·licitud i es faturen juntament amb la resta del prompt.

Compara els plans

Quan s'han gastat les cerques del dia

Una sol·licitud que envia web_search: true després de l'última cerca del dia no es refusa. Es respon sense cerca: l'estat és 200 i la resposta no té sources.

La cerca com a eina pròpia

web_search: true és l'únic interruptor de la cerca descrita aquí. Una funció que defineixes a tools i anomenes web_search és una de les teves pròpies eines: el model retorna una crida, i el teu codi executa la cerca i en torna el resultat.

Els tipus d'eina de cerca d'altres plataformes, com web_search_20250305 a /v1/messages o {"type": "web_search"} a /v1/responses, no inicien cap cerca aquí.

Errors

La cerca web no afegeix cap codi d'estat ni cap tipus d'error. Una cerca que no troba res, o un dia sense cerques disponibles, dona una resposta normal sense resultats de cerca. Tots els altres errors són els mateixos que per a una sol·licitud sense cerca. Gestió d’errors