Веб-поиск

Веб-поиск даёт модели актуальные данные из интернета: модель сама решает, когда искать, получает результаты и отвечает со ссылками на источники.

Рабочий пример

Chat Completions:

{
  "model": "openai/gpt-5-mini",
  "messages": [{"role": "user", "content": "Какие новости о выходе Next.js были на этой неделе?"}],
  "max_tokens": 2048,
  "tools": [
    {
      "type": "gorouter:web_search",
      "parameters": {"engine": "exa", "max_results": 5, "max_uses": 3, "max_total_results": 10}
    }
  ]
}

Responses:

{
  "model": "openai/gpt-5-mini",
  "input": "Какие новости о выходе Next.js были на этой неделе?",
  "max_output_tokens": 2048,
  "tools": [
    {
      "type": "gorouter:web_search",
      "parameters": {"engine": "exa", "max_results": 5, "max_uses": 3, "max_total_results": 10}
    }
  ]
}

Отправляйте объекты на /api/v1/chat/completions и /api/v1/responses соответственно. Инструмент можно сочетать с обычными function tools в том же массиве tools.

Поиск работает только с моделями, у которых опубликован тариф «за поиск». Он показан на странице модели в каталоге.

Важные параметры

Поля объекта parameters:

• max_total_results — обязательный предел числа результатов за весь запрос.
• max_results — число результатов за один поиск. По умолчанию 5, максимум 10.
• max_uses — сколько поисков модель может выполнить. Максимум 30. Если не указан, берётся top-level max_tool_calls (по умолчанию 30, максимум 30). Чем меньше значение, тем меньше резерв.
• engine — поисковый движок: auto (по умолчанию), native, exa, firecrawl, parallel, perplexity. При auto и native используется встроенный поиск провайдера, если endpoint его поддерживает, иначе Exa. Ограничения для встроенного поиска описаны в разделе «Стоимость».
• search_context_size — объём контекста из результатов: low, medium, high.
• max_characters — предел символов в каждом результате, не больше 100000. Учитывается движками exa, parallel и perplexity; встроенный поиск провайдера (auto, native) его игнорирует.
• allowed_domains, excluded_domains — массивы строк с доменами, которыми нужно ограничить или исключить поиск.
• user_location — объект с примерным местоположением пользователя для локальных результатов.

Другие ключи в parameters и в самом объекте инструмента отклоняются.

Альтернатива: web_search_options

Модели с параметром web_search_options в supported_parameters принимают упрощённый формат:

{
  "model": "openai/gpt-4o-search-preview",
  "messages": [{"role": "user", "content": "Курс биткоина сегодня"}],
  "web_search_options": {"search_context_size": "low"}
}

search_context_size обязателен: low, medium или high. Другие ключи не принимаются. Такой запрос считается одной операцией поиска.

Ответ

• Источники приходят в аннотациях типа url_citation: в message.annotations для Chat Completions и в annotations текстовой части ответа для Responses. Каждая аннотация содержит url, title и позицию цитаты в тексте.
• usage.server_tool_use_details.web_search_requests — сколько поисков фактически выполнено.
• usage.cost — итоговая цена запроса в ₽, включая поиски и все раунды модели.

Число поисков и их стоимость по каждому запросу видны в логах аккаунта: значок поиска в строке запроса и строка «Из них веб-поиск» в деталях.

Стоимость

Каждый поиск оплачивается по тарифу «за поиск» выбранной модели, а токены — по обычным тарифам модели. После каждого результата поиска модель может вызываться снова, поэтому на старте резерв рассчитывается по максимуму:

• число поисков (max_uses или max_tool_calls, плюс одна операция для web_search_options) × тариф «за поиск»;
• до N+1 раундов модели, где N — максимальное число поисков; в каждом раунде резервируется вход и лимит ответа.

Число поисков ограничивается так:

• exa, firecrawl, parallel, perplexity, а также auto и native на endpoint без встроенного поиска (тогда поиск идёт через Exa): берётся меньшее из max_uses и max_tool_calls.
• auto и native на endpoint со встроенным поиском провайдера. OpenRouter передаёт max_uses только Anthropic, остальные провайдеры (OpenAI, Google, xAI, Perplexity) его игнорируют и не публикуют предел числа поисков. Поэтому такой endpoint принимается только для Anthropic и только с явным max_uses. Для остальных провайдеров запрос на этот endpoint отклоняется с billing_unbounded. Если у модели есть endpoint без встроенного поиска, запрос уходит туда.

Чтобы поиск работал с любой моделью, укажите engine: "exa" (или другой движок OpenRouter) и max_uses.

Объём входа в раунде зависит от движка. Для exa, parallel и perplexity с указанным max_characters он считается по реальному пределу: исходный запрос, ответы предыдущих раундов и все результаты поиска (max_total_results × max_characters). Тариф поиска для этих движков берётся не ниже опубликованной цены OpenRouter за запрос. Для встроенного поиска провайдера объём результатов ничем не ограничен, поэтому каждый раунд резервируется с полным контекстом модели. У моделей с контекстом около 1 млн токенов это сотни рублей даже для одного поиска.

Резерв может заметно превышать итоговую цену. Списывается фактическая стоимость из usage.cost, остаток резерва освобождается. Чтобы уменьшить резерв, используйте engine: "exa" с max_characters, небольшие max_uses и max_total_results и явный лимит ответа.

{
  "type": "gorouter:web_search",
  "parameters": {"engine": "exa", "max_results": 3, "max_uses": 2, "max_total_results": 6, "max_characters": 1500}
}

Такие же параметры использует веб-чат GoRouter; число поисков за ответ (от 1 до 5) настраивается в меню поиска, там же показан резерв до отправки.

Ошибки и ограничения

Неподдерживаемые варианты отклоняются до отправки провайдеру с кодом billing_unbounded. Сообщение начинается с «Нельзя безопасно ограничить стоимость запроса по данным поставщика» и содержит причину. Так отклоняются:

• устаревший плагин plugins: [{"id": "web"}] — используйте gorouter:web_search;
• суффикс модели :online;
• parameters.x_search и другие ключи, не перечисленные выше;
• другие server tools, кроме gorouter:web_search, в том числе в tool_choice;
• max_results больше 10, max_uses или max_tool_calls больше 30, max_characters больше 100000;
• endpoint модели без опубликованного тарифа web_search;
• engine auto или native (в том числе без engine), если подходящие endpoint модели используют встроенный поиск провайдера, кроме Anthropic с явным max_uses, или не публикуют список встроенных инструментов.

Веб-поиск нельзя совмещать с audio output. Виртуальная модель gorouter/free веб-поиск не поддерживает. Если модель не поддерживает web_search_options, запрос вернёт unsupported_parameter.