Web Search

Добавьте актуальную информацию из интернета к ответам любой LLM-модели. Достаточно добавить суффикс :online к имени модели — ZvenoAI автоматически выполнит поиск и передаст результаты в контекст.

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

Самый простой способ включить web search — добавить суффикс :online к имени модели в запросе:

openai/gpt-4o:online
anthropic/claude-sonnet-4:online
google/gemini-2.5-pro:online
x-ai/grok-4-fast:online

Это эквивалентно передаче параметра plugins: [{"id": "web"}] в теле запроса. Суффикс :online — это удобное сокращение, не требующее изменений в структуре запроса.

Примеры кода

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZVENOAI_API_KEY,
  baseURL: "https://api.zveno.ai/v1",
});

// Просто добавьте :online к имени модели
const response = await client.chat.completions.create({
  model: "openai/gpt-4o:online",
  messages: [
    { role: "user", content: "Какие новости в мире AI сегодня?" }
  ],
});

console.log(response.choices[0].message.content);

// Аннотации с ссылками на источники (если поддерживается провайдером)
const annotations = response.choices[0].message.annotations;
if (annotations) {
  for (const ann of annotations) {
    if (ann.type === "url_citation") {
      console.log(`Источник: ${ann.url_citation.title} — ${ann.url_citation.url}`);
    }
  }
}

from openai import OpenAI

client = OpenAI(
    api_key="ваш_ключ_zvenoai",
    base_url="https://api.zveno.ai/v1",
)

# Просто добавьте :online к имени модели
response = client.chat.completions.create(
    model="openai/gpt-4o:online",
    messages=[
        {"role": "user", "content": "Какие новости в мире AI сегодня?"}
    ],
)

print(response.choices[0].message.content)

# Аннотации с ссылками на источники (если поддерживается провайдером)
annotations = getattr(response.choices[0].message, "annotations", None)
if annotations:
    for ann in annotations:
        if ann.type == "url_citation":
            print(f"Источник: {ann.url_citation.title} — {ann.url_citation.url}")

curl https://api.zveno.ai/v1/chat/completions \
  -H "Authorization: Bearer $ZVENOAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o:online",
    "messages": [
      {"role": "user", "content": "Какие новости в мире AI сегодня?"}
    ]
  }'

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

При получении запроса с :online ZvenoAI:

1. Удаляет суффикс :online из имени модели для корректного поиска в каталоге
2. Конвертирует суффикс в параметр plugins: [{"id": "web"}]
3. Передаёт запрос провайдеру, который выполняет поиск и включает результаты в контекст модели
4. Модель генерирует ответ с учётом актуальной информации из интернета

Суффиксы моделей

Суффикс :online — единственный виртуальный суффикс, который модифицирует поведение запроса. Остальные суффиксы являются частью имени модели:

// :free и :online можно комбинировать
const response = await client.chat.completions.create({
  // :free — бесплатная версия модели, :online — web search
  model: 'openai/gpt-4o:free:online',
  messages: [{ role: 'user', content: 'Погода в Москве сейчас' }],
})

Альтернативный синтаксис: plugins

Вместо суффикса :online можно явно передать параметр plugins в теле запроса. Это даёт больше контроля над поведением поиска.

// Альтернативный способ: явное указание plugins
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: 'Курс доллара к рублю сегодня' }],
  plugins: [{ id: 'web' }],
})

Настройка параметров поиска

При использовании синтаксиса plugins можно настроить параметры поиска:

// Настройка параметров web search
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: 'Последние исследования по квантовым компьютерам' }],
  plugins: [
    {
      id: 'web',
      max_results: 10, // количество результатов поиска (по умолчанию 5)
      search_prompt: 'научные статьи 2025-2026', // подсказка для поисковика
    },
  ],
})

max_results (number) — Количество результатов поиска, которые будут переданы в контекст модели. По умолчанию 5. Увеличение улучшает качество ответа, но повышает стоимость и latency.

search_prompt (string) — Дополнительная инструкция для поискового движка. Позволяет уточнить область поиска, например: "научные статьи", "новости за последнюю неделю".

Стоимость

Стоимость запроса с web search складывается из двух частей: стандартная оплата за токены модели + фиксированная плата за каждый поисковый запрос через сервис ZvenoAI.

Как формируется стоимость:

• Токены модели — стандартная цена за prompt и completion токены. Результаты поиска добавляются в контекст как дополнительные prompt-токены.
• Web search — фиксированная стоимость 1.8 руб. за запрос. Списывается, если модель не использует встроенный поиск провайдера (native search), а поиск выполняется через сервис ZvenoAI.

Когда взимается плата за web search:

• Anthropic, OpenAI, Perplexity, xAI — используют собственный встроенный поиск провайдера. Отдельная плата за web search не взимается, стоимость поиска уже включена в цену токенов.
• Все остальные модели — поиск выполняется через сервис ZvenoAI (Exa). За каждый такой запрос взимается фиксированная плата 1.8 руб.

Где посмотреть цены: Актуальные цены за 1M токенов (input/output) для каждой модели указаны на странице модели в каталоге и через GET /v1/models. Стоимость web search через сервис ZvenoAI отображается в разделе web_search_count в детализации использования.

Формат ответа

Ответ возвращается в стандартном формате Chat Completions. Результаты поиска включаются как аннотации с типом url_citation:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Согласно последним данным...",
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "url": "https://example.com/article",
              "title": "Название статьи",
              "content": "Фрагмент текста из источника...",
              "start_index": 0,
              "end_index": 42
            }
          }
        ]
      }
    }
  ]
}

Аннотации содержат URL, заголовок и фрагмент текста источника, а также позиции в тексте ответа, к которым относится цитата. Формат совместим с OpenAI Chat Completions.

Когда использовать