Búsqueda web integrada

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 respuesta es una chat completion normal con dos añadidos. La respuesta remite a los resultados de búsqueda con números entre corchetes, sources indica qué representa cada número y annotations marca dónde se cita cada uno:

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

Activar la búsqueda

La búsqueda es un campo de la solicitud, desactivado por defecto. No se busca nada a menos que una solicitud lo envíe.

En /v1/messages el campo va en el nivel superior del cuerpo, junto a model y messages:

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

Qué hace una solicitud con búsqueda

• La API busca en la web el último mensaje del usuario. Los turnos anteriores de la conversación dan contexto a la búsqueda.
• La búsqueda se ejecuta en cada solicitud que envía web_search: true. El modelo no elige si busca o no.
• Los resultados se ponen delante del modelo como fuentes numeradas, y el modelo escribe su respuesta a partir de ellos.
• La respuesta empieza cuando termina la búsqueda. Una solicitud con stream no envía nada, ni headers ni eventos, hasta entonces, así que cuenta con una espera más larga antes del primer fragmento.

Qué contiene la respuesta

• La respuesta tiene la forma habitual de su endpoint. La respuesta está en choices[0].message.content (un bloque text en /v1/messages).
• El texto puede llevar marcadores como [1] y [2] después de las afirmaciones que respaldan. Cada número representa uno de los resultados que leyó el modelo.
• sources nombra esos resultados: una entrada por cada resultado que recibió el modelo, con index, title y url. El marcador [1] es la entrada con index 1. También se listan los resultados que la respuesta no cita.
• En /v1/chat/completions el mensaje también tiene annotations, con la forma de OpenAI: un url_citation por cada fuente que nombra un marcador, con url, title, y start_index y end_index, la posición del marcador en content contada en caracteres (el final no se incluye).
• En un stream sources llega con el último fragmento, y en /v1/messages con el evento message_delta. Las anotaciones llegan en un fragmento justo antes del último, como delta.annotations.
• sources solo está presente si la búsqueda de esta solicitud encontró algo. Una respuesta sin él se escribió sin resultados de búsqueda.

Cómo se cuentan las búsquedas

Cada plan incluye un número de búsquedas por día:

• Una solicitud cuya búsqueda encontró algo usa una búsqueda de la cuota del día. Una búsqueda que no encontró nada no usa ninguna.
• El chat y la API comparten la cuota de la cuenta propietaria de la clave.
• El conteo empieza de nuevo cada día a las 00:00 UTC.
• Los resultados de búsqueda son tokens de entrada de la solicitud y se facturan junto con el resto del prompt.

Comparar los planes

Cuando se agotan las búsquedas del día

Una solicitud que envía web_search: true después de la última búsqueda del día no se rechaza. Se responde sin búsqueda: el estado es 200 y la respuesta no tiene sources.

La búsqueda como herramienta propia

web_search: true es el único interruptor de la búsqueda descrita aquí. Una función que defines en tools y llamas web_search es una de tus propias herramientas: el modelo devuelve una llamada, y tu código ejecuta la búsqueda y envía el resultado de vuelta.

Los tipos de herramienta de búsqueda de otras plataformas, como web_search_20250305 en /v1/messages o {"type": "web_search"} en /v1/responses, no inician una búsqueda aquí.

Errores

La búsqueda web no añade ningún código de estado ni tipo de error. Una búsqueda que no encuentra nada, o un día sin búsquedas restantes, da una respuesta normal sin resultados de búsqueda. Cualquier otro error es igual que en una solicitud sin búsqueda. Manejo de errores