Web Search (Веб-поиск)

Дайте любой модели доступ к актуальной информации из интернета в реальном времени

Веб-поиск позволяет модели получать свежие данные из интернета в момент ответа. Когда модели нужна актуальная информация, она сама формирует поисковый запрос, получает результаты и строит на их основе ответ с указанием источников.

Базовый URL: https://api.ru-openrouter.ru/v1/chat/completions

Как это работает

1. Вы включаете инструмент { "type": "openrouter:web_search" } в массив tools запроса.
2. Модель, исходя из промпта, решает, нужен ли поиск в интернете, и формирует поисковый запрос.
3. Поиск выполняется через настроенный движок (по умолчанию auto — используется нативный поиск провайдера, если он доступен, иначе — Exa).
4. Результаты поиска (URL, заголовки и фрагменты содержимого) возвращаются модели.
5. Модель синтезирует результаты в ответ. При необходимости она может выполнить несколько поисков в рамках одного запроса.

Быстрый старт

cURL

curl https://api.ru-openrouter.ru/v1/chat/completions \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.2",
    "messages": [
      {
        "role": "user",
        "content": "Какие были главные AI-анонсы на этой неделе?"
      }
    ],
    "tools": [
      { "type": "openrouter:web_search" }
    ]
  }'

Python

import requests

response = requests.post(
    "https://api.ru-openrouter.ru/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk_ваш_api_ключ",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-5.2",
        "messages": [
            {
                "role": "user",
                "content": "Какие были главные AI-анонсы на этой неделе?"
            }
        ],
        "tools": [
            {"type": "openrouter:web_search"}
        ]
    }
)

data = response.json()
print(data["choices"][0]["message"]["content"])

Конфигурация

Инструмент веб-поиска принимает необязательные parameters для настройки поведения поиска:

{
  "type": "openrouter:web_search",
  "parameters": {
    "engine": "exa",
    "max_results": 5,
    "max_total_results": 20,
    "search_context_size": "medium",
    "allowed_domains": ["example.com"],
    "excluded_domains": ["reddit.com"]
  }
}

Геолокация пользователя

Передайте примерное местоположение, чтобы сместить результаты поиска географически:

{
  "type": "openrouter:web_search",
  "parameters": {
    "user_location": {
      "type": "approximate",
      "city": "Москва",
      "region": "Москва",
      "country": "RU",
      "timezone": "Europe/Moscow"
    }
  }
}

Все поля внутри user_location необязательны.

Выбор движка

Инструмент веб-поиска поддерживает несколько движков:

• auto (по умолчанию) — использует нативный поиск, если провайдер его поддерживает, иначе переключается на Exa
• native — предпочитает встроенный веб-поиск провайдера; переключается на Exa, если модель его не поддерживает
• exa — поиск через API Exa, сочетающий ключевые слова и эмбеддинги
• firecrawl — поиск через Firecrawl
• parallel — поиск через Parallel
• perplexity — ранжированные веб-результаты через Perplexity

Нативный поиск провайдеров

При engine: "auto" (по умолчанию) или "native" используется встроенный поиск провайдера для поддерживаемых моделей. Нативный поиск имеют:

• OpenAI — GPT-4.1, GPT-4.1 Mini, GPT-4.1 Nano, GPT-5 и новее, o3, o3 Pro, o4-mini
• Anthropic — Claude 3.5 Haiku, Claude 3.7 Sonnet, Claude 4 и новее (все варианты Opus/Sonnet)
• Google — Gemini 3 Flash, Gemini 3 Pro, Gemini 3.1 Flash/Lite, Gemini 3.5 Flash
• xAI — Grok 4 и новее
• Perplexity — все модели Perplexity

{
  "model": "perplexity/sonar",
  "messages": [
    {
      "role": "user",
      "content": "Последние новости AI"
    }
  ]
}

Более старые модели OpenAI — включая GPT-4o, GPT-4o Mini и GPT-4 Turbo — не поддерживают нативный поиск. При engine: "native" с такими моделями инструмент переключается на Exa. Используйте engine: "auto" (или опустите поле) для эквивалентного поведения.

Для моделей без нативного поиска задайте engine одним из поддерживаемых вариантов (Exa, Firecrawl, Parallel, Perplexity) — или оставьте "auto", чтобы использовалась Exa.

Доменная фильтрация

Ограничьте домены в результатах поиска с помощью allowed_domains и excluded_domains:

{
  "type": "openrouter:web_search",
  "parameters": {
    "allowed_domains": ["arxiv.org", "nature.com"],
    "excluded_domains": ["reddit.com"]
  }
}

Ограничение числа поисков и результатов

Ограничение общего количества результатов

Когда модель ищет несколько раз в одном запросе, используйте max_total_results, чтобы ограничить суммарное число результатов:

{
  "type": "openrouter:web_search",
  "parameters": {
    "max_results": 5,
    "max_total_results": 15
  }
}

При достижении лимита последующие вызовы возвращают сообщение о том, что лимит исчерпан, вместо выполнения поиска. Это удобно для контроля стоимости и размера контекстного окна в агентных циклах.

Ограничение числа поисков

Чтобы жёстко ограничить число поисков модели за один запрос, задайте max_uses в parameters инструмента:

{
  "type": "openrouter:web_search",
  "parameters": {
    "max_uses": 3
  }
}

При достижении лимита последующие вызовы возвращают сообщение об исчерпании лимита вместо выполнения поиска.

Каждый поиск также потребляет один шаг общего бюджета серверных инструментов запроса. Чтобы ограничить этот бюджет, задайте поле max_tool_calls запроса (на том же уровне, что messages и tools):

{
  "model": "openai/gpt-5.2",
  "messages": [...],
  "tools": [{ "type": "openrouter:web_search" }],
  "max_tool_calls": 5
}

Если поле опущено, бюджет по умолчанию составляет 30 шагов (это также максимум).

Работа с Responses API

Инструмент веб-поиска также работает с эндпоинтом /v1/responses:

cURL

curl https://api.ru-openrouter.ru/v1/responses \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.2",
    "input": "Какая сейчас цена биткоина?",
    "tools": [
      { "type": "openrouter:web_search", "parameters": { "max_results": 3 } }
    ]
  }'

Python

import requests

response = requests.post(
    "https://api.ru-openrouter.ru/v1/responses",
    headers={
        "Authorization": "Bearer sk_ваш_api_ключ",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-5.2",
        "input": "Какая сейчас цена биткоина?",
        "tools": [
            {"type": "openrouter:web_search", "parameters": {"max_results": 3}}
        ]
    }
)

print(response.json())

Учёт использования

Использование веб-поиска отражается в объекте usage ответа:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 250,
    "server_tool_use": {
      "web_search_requests": 2
    }
  }
}

Поле web_search_requests содержит суммарное число поисковых запросов, выполненных моделью за время запроса.

Цена

Веб-поиск тарифицируется отдельно от обычных токенов. Стоимость за один поисковый запрос указана для каждой модели в поле web_search объекта pricing эндпоинта /v1/models. Цена за веб-поиск добавляется к стандартной стоимости токенов за обработку содержимого результатов поиска.