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

A resposta é unha chat completion normal con dous engadidos. A resposta apunta aos resultados da busca con números entre corchetes, sources indica o que representa cada número e annotations marca onde se cita cada un:

{
  "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 a busca

A busca é un campo da solicitude, desactivado por defecto. Non se busca nada a menos que unha solicitude o envíe.

En /v1/messages o campo está no nivel superior do corpo, xunto a model e messages:

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

O que fai unha solicitude con busca

• A API busca na web a última mensaxe do usuario. Os turnos anteriores da conversa dan contexto á busca.
• A busca execútase en todas as solicitudes que envían web_search: true. O modelo non escolle se busca.
• Os resultados presentanse ao modelo como fontes numeradas, e o modelo escribe a súa resposta a partir deles.
• A resposta comeza cando remata a busca. Unha solicitude con stream non envía nada, nin cabeceiras nin eventos, ata entón, así que conta cunha espera máis longa antes do primeiro chunk.

O que contén a resposta

• A resposta ten a forma habitual do seu endpoint. A resposta está en choices[0].message.content (un bloque text en /v1/messages).
• O texto pode levar marcadores como [1] e [2] despois das afirmacións que apoian. Cada número representa un dos resultados que leu o modelo.
• sources nomea eses resultados: unha entrada por cada resultado que recibiu o modelo, con index, title e url. O marcador [1] é a entrada con index 1. Tamén se listan os resultados que a resposta non cita.
• En /v1/chat/completions a mensaxe tamén ten annotations, coa forma de OpenAI: un url_citation por cada fonte que nomea un marcador, con url, title, e start_index e end_index, a posición do marcador en content contada en caracteres (o final non se inclúe).
• Nun stream sources chega co último chunk, e en /v1/messages co evento message_delta. As anotacións chegan nun chunk xusto antes do último, como delta.annotations.
• sources só está presente se a busca desta solicitude atopou algo. Unha resposta sen el escribiuse sen resultados de busca.

Como se contan as buscas

Todos os plans inclúen un número de buscas por día:

• Unha solicitude cuxa busca atopou algo usa unha busca da cota do día. Unha busca que non atopou nada non usa ningunha.
• O chat e a API comparten a cota da conta á que pertence a clave.
• O reconto comeza de novo cada día ás 00:00 UTC.
• Os resultados da busca son tokens de entrada da solicitude e factúranse co resto do prompt.

Comparar os plans

Cando se esgotan as buscas do día

Unha solicitude que envía web_search: true despois da última busca do día non se rexeita. Respóndese sen busca: o estado é 200 e a resposta non ten sources.

A busca como ferramenta propia

web_search: true é o único interruptor da busca descrita aquí. Unha función que defines en tools e chamas web_search é unha das túas propias ferramentas: o modelo devolve unha chamada, e o teu código executa a busca e devolve o resultado.

Os tipos de ferramenta de busca doutras plataformas, como web_search_20250305 en /v1/messages ou {"type": "web_search"} en /v1/responses, non inician unha busca aquí.

Erros

A busca web non engade ningún código de estado nin tipo de erro. Unha busca que non atopa nada, ou un día sen buscas restantes, dá unha resposta normal sen resultados de busca. Todos os demais erros son os mesmos que para unha solicitude sen busca. Xestión de erros