Встроенный веб‑поиск

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

Ответ — это обычный chat completion с двумя дополнениями. Ответ ссылается на результаты поиска числами в квадратных скобках, sources сообщает, что обозначает каждое число, а annotations отмечает, где цитируется каждый из них:

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

Включение поиска

Поиск — это поле запроса, по умолчанию выключенное. Ничего не ищется, пока запрос его не отправит.

На /v1/messages поле находится на верхнем уровне тела, рядом с model и messages:

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

Что делает запрос с поиском

• API ищет в вебе по последнему сообщению пользователя. Контекст поиску дают предыдущие ходы разговора.
• Поиск выполняется при каждом запросе, который отправляет web_search: true. Модель не решает, искать или нет.
• Результаты передаются модели как пронумерованные источники, и модель пишет ответ на их основе.
• Ответ начинается, когда поиск закончен. До этого момента запрос со стримингом ничего не отправляет, ни заголовков, ни событий, поэтому учитывайте более долгое ожидание первого чанка.

Что содержит ответ

• Ответ имеет обычную структуру своего эндпоинта. Ответ находится в choices[0].message.content (блок text на /v1/messages).
• В тексте могут быть маркеры вроде [1] и [2] после утверждений, которые они подтверждают. Каждое число обозначает один из результатов, прочитанных моделью.
• sources называет эти результаты: по одной записи на каждый результат, переданный модели, с index, title и url. Маркер [1] — это запись с index 1. Результаты, которые ответ не цитирует, тоже перечислены.
• На /v1/chat/completions у сообщения есть также annotations в формате OpenAI: по одному url_citation на каждый источник, который называет маркер, с url, title, а также start_index и end_index — позицией маркера в content, посчитанной в символах (конец не включается).
• В потоке sources приходит с последним чанком, а на /v1/messages — с событием message_delta. Аннотации приходят в одном чанке прямо перед последним, как delta.annotations.
• sources есть только тогда, когда поиск этого запроса что-то нашел. Ответ без него написан без результатов поиска.

Как считаются поиски

Каждый план включает определенное число поисков в день:

• Запрос, в котором поиск что-то нашел, расходует один поиск из дневного лимита. Поиск, который ничего не нашел, не расходует ничего.
• Чат и API делят лимит аккаунта, которому принадлежит ключ.
• Отсчет начинается заново каждый день в 00:00 UTC.
• Результаты поиска — это входные токены запроса, и они тарифицируются вместе с остальным промптом.

Сравнить планы

Когда поиски за день исчерпаны

Запрос, который отправляет web_search: true после последнего поиска за день, не отклоняется. Он получает ответ без поиска: статус 200, а в ответе нет sources.

Поиск как собственный инструмент

web_search: true — единственный переключатель описанного здесь поиска. Функция, которую вы определяете в tools и называете web_search, — это ваш собственный инструмент: модель возвращает вызов, а ваш код выполняет поиск и отправляет результат обратно.

Типы инструментов поиска других платформ, например web_search_20250305 на /v1/messages или {"type": "web_search"} на /v1/responses, здесь поиск не запускают.

Ошибки

Веб-поиск не добавляет ни кода статуса, ни типа ошибки. Если поиск ничего не нашел или в этот день поисков не осталось, приходит обычный ответ без результатов поиска. Все остальные ошибки такие же, как для запроса без поиска. Обработка ошибок