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

A resposta é um chat completion comum com dois acréscimos. A resposta aponta para os resultados da busca com números entre colchetes, sources diz o que cada número representa, e annotations marca onde cada um é citado:

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

Ativando a busca

A busca é um campo da requisição, desativado por padrão. Nada é pesquisado, a menos que uma requisição o envie.

Em /v1/messages, o campo fica no nível superior do corpo, ao lado de model e messages:

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

O que uma requisição com busca faz

• A API pesquisa na web a última mensagem do usuário. Os turnos anteriores da conversa dão contexto à busca.
• A busca é executada em toda requisição que envia web_search: true. O modelo não escolhe se vai pesquisar.
• Os resultados são colocados diante do modelo como fontes numeradas, e o modelo escreve a sua resposta a partir deles.
• A resposta começa quando a busca termina. Uma requisição com stream não envia nada, nem cabeçalhos nem eventos, até lá, então conte com uma espera maior antes do primeiro chunk.

O que a resposta contém

• A resposta tem o formato usual do seu endpoint. A resposta está em choices[0].message.content (um bloco text em /v1/messages).
• O texto pode trazer marcadores como [1] e [2] depois das afirmações que eles sustentam. Cada número representa um dos resultados que o modelo leu.
• sources nomeia esses resultados: uma entrada para cada resultado entregue ao modelo, com index, title e url. O marcador [1] é a entrada com index 1. Resultados que a resposta não cita também estão na lista.
• Em /v1/chat/completions, a mensagem também tem annotations, no formato da OpenAI: um url_citation para cada fonte que um marcador nomeia, com url, title, e start_index e end_index, a posição do marcador em content contada em caracteres (o fim não é incluído).
• Em um stream, sources vem com o último chunk e, em /v1/messages, com o evento message_delta. As annotations vêm em um chunk logo antes do último, como delta.annotations.
• sources só existe quando a busca desta requisição encontrou algo. Uma resposta sem ele foi escrita sem resultados de busca.

Como as buscas são contadas

Todo plano inclui um número de buscas por dia:

• Uma requisição cuja busca encontrou algo usa uma busca da cota do dia. Uma busca que não encontrou nada não usa nenhuma.
• O chat e a API compartilham a cota da conta dona da chave.
• A contagem recomeça todos os dias às 00:00 UTC.
• Os resultados da busca são tokens de entrada da requisição e são faturados junto com o restante do prompt.

Compare os planos

Quando as buscas do dia se esgotam

Uma requisição que envia web_search: true depois da última busca do dia não é recusada. Ela é respondida sem busca: o status é 200 e a resposta não tem sources.

A busca como uma ferramenta sua

web_search: true é o único interruptor da busca descrita aqui. Uma função que você define em tools e chama de web_search é uma ferramenta sua: o modelo retorna uma chamada, e o seu código executa a busca e envia o resultado de volta.

Tipos de ferramenta de busca de outras plataformas, como web_search_20250305 em /v1/messages ou {"type": "web_search"} em /v1/responses, não iniciam uma busca aqui.

Erros

A busca na web não acrescenta nenhum código de status nem tipo de erro. Uma busca que não encontra nada, ou um dia sem buscas restantes, dá uma resposta normal sem resultados de busca. Todos os outros erros são iguais aos de uma requisição sem busca. Tratamento de erros