Вбудований веб‑пошук

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

Відповідь — звичайне завершення чату з двома доповненнями. Відповідь посилається на результати пошуку числами у квадратних дужках, 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 надходить з останнім chunk, а на /v1/messages — з подією message_delta. Анотації надходять в одному chunk перед останнім, як 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, тут пошуку не запускають.

Помилки

Веб-пошук не додає ні коду статусу, ні типу помилки. Пошук, що нічого не знайшов, або день без пошуків, що лишилися, дає звичайну відповідь без результатів пошуку. Кожна інша помилка така сама, як для запиту без пошуку. Обробка помилок