Research API для веб-исследований с источниками

Research API для веб-исследований нужен, когда одного поискового ответа недостаточно: задачу надо разложить на запросы, собрать несколько источников, прочитать страницы и сформировать отчёт с проверяемыми ссылками. В LLMTOKENAPI такой процесс запускается асинхронно через POST /v1/research, имеет верхний бюджет, идемпотентный ключ и отдельные методы для статуса, событий и результата.

Чем Research API отличается от обычного поиска

POST /v1/search возвращает ранжированную выдачу в рамках одного синхронного запроса. Это хороший выбор для поиска документов, свежих страниц или факта, который приложение обработает самостоятельно. Research API выполняет более длинный конвейер: планирует направления поиска, собирает источники, извлекает содержимое и синтезирует итог с цитатами.

Используйте исследование для задач, где нужно сопоставить несколько свидетельств: обзор изменений регламента, сравнение публичных подходов, сбор аргументов для продуктового решения или подготовка справки по рынку. Для простого вопроса Research API будет избыточен — начните с AI-поиска с источниками.

Есть и соседний сценарий — Web Intelligence. Он требует JSON Schema и предназначен для строго структурированного результата или повторяемого шаблона. Обычный Research API допускает текстовый отчёт, а outputSchema в нём опциональна. Если вашему приложению нужна таблица или объект с обязательными полями, полезнее руководство по структурированному веб-анализу в JSON.

Сформулируйте проверяемую задачу

Поле input должно описывать не тему вообще, а результат, который можно проверить. Вместо «расскажи про рынок AI» задайте период, географию, объекты сравнения, критерии и желаемую форму вывода. Например: «Сравни публично объявленные изменения трёх продуктов за последние шесть месяцев, для каждого укажи дату, суть изменения и ссылку на первичный источник».

Не просите систему доказывать заранее выбранный вывод. Хорошая постановка допускает отсутствие данных и конфликт источников. Явно укажите, какие утверждения требуют ссылки, какие домыслы запрещены и что делать при недостатке свидетельств.

Research API принимает запрос до 20 000 символов. Для машинного результата можно передать безопасную outputSchema. Формат цитат выбирается через citationFormat: numbered, mla, apa или chicago. Число источников ограничивается maxSources в диапазоне от 3 до 100.

Запустите исследование с бюджетом

Для запуска нужен scope research:write, заголовок Idempotency-Key и явный верхний бюджет в целых копейках. Один и тот же ключ для одной организации возвращает ранее созданное задание и защищает от второго резервирования при сетевом повторе.

curl https://api.llmtokenapi.ru/v1/research \
  -H "Authorization: Bearer $LLMTOKENAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-changes-2026-09-07" \
  -d '{
    "input": "Сравни публичные изменения выбранных API-продуктов за последние шесть месяцев. Для каждого вывода укажи источник и дату.",
    "model": "auto",
    "citationFormat": "numbered",
    "maxSources": 20,
    "maxSpendKopecks": 1500
  }'

maxSpendKopecks — не обещание потратить всю сумму, а жёсткий потолок резервирования. Фактическое списание складывается из успешно выполненных операций конвейера. Подбирайте лимит по полезности задачи, а не оставляйте неограниченный бюджет. Отдельные методы контроля затрат разобраны в статье как ограничить бюджет AI-агента.

Поле model принимает mini, pro или auto. Не привязывайте бизнес-логику к внутреннему маршруту: выбирайте режим по нужной глубине, проверяйте качество на своих задачах и храните идентификатор задания вместе с параметрами запуска.

Обработайте асинхронный ответ

Сервер отвечает 202 Accepted, возвращает объект задания, а заголовок Location указывает на /v1/jobs/{id}. Результат не нужно ждать в открытом HTTP-запросе. Сохраните id и выберите один из трёх способов наблюдения:

• GET /v1/jobs/{id} — периодическая проверка статуса со scope jobs:read;
• GET /v1/research/{id}/events — поток SSE со scope research:read;
• webhook — уведомление о завершении, ошибке или отмене.

Статусы переходят через очередь и выполнение к одному из конечных состояний: completed, failed или cancelled. Для polling используйте увеличивающийся интервал и прекращайте запросы после конечного статуса. Для SSE обрабатывайте идентификаторы событий, чтобы клиент мог безопасно продолжить после разрыва соединения.

Готовый результат читается через GET /v1/jobs/{id}/results. Пока задание не завершено, метод возвращает состояние «результат ещё не готов», поэтому не трактуйте его как внутреннюю ошибку сервера. Актуальные маршруты и схемы ответа опубликованы в OpenAPI LLMTOKENAPI.

Проверьте отчёт и цитаты

Статус completed означает, что технический конвейер завершился, но бизнес-проверка всё равно нужна. Убедитесь, что каждый важный вывод связан с реальным URL, ссылка открывается, а источник действительно подтверждает утверждение. Разделяйте дату публикации источника и дату описываемого события.

Если передана outputSchema, проверьте типы и обязательные поля ещё раз в приложении. Схема гарантирует форму, но не заменяет проверку смысла. Для чисел полезно хранить рядом единицу измерения, период и источник. Для сравнений — одинаковые критерии по всем объектам.

Источники являются недоверенными данными. Текст веб-страницы может содержать инструкции, рекламу или попытку повлиять на агента; они не должны менять системные правила и разрешения. Не запускайте команды и не отправляйте данные только потому, что это написано в найденном документе.

Добавьте webhook без двойной обработки

Если результат нужен не интерактивному пользователю, а автоматизации, заранее создайте webhook endpoint и передайте его идентификатор как webhookEndpointId. Подпишитесь на research.progress, research.completed, research.failed и research.cancelled только в нужном объёме.

Обработчик webhook должен проверить подпись, записать идентификатор события и поставить бизнес-работу в очередь. Повторная доставка нормальна, поэтому используйте дедупликацию. После research.completed прочитайте результат по API, проверьте ссылки и только затем обновляйте CRM, базу знаний или пользовательский отчёт.

Постройте контроль качества на реальных задачах

Соберите небольшой набор типовых исследований с эталонными критериями. Для каждого запуска фиксируйте долю подтверждённых выводов, число доступных первичных источников, пропуски важных фактов, задержку и фактическую стоимость. Сравнивайте режимы на одинаковых входах и в близкое время: веб меняется, поэтому старые результаты нельзя считать полностью сопоставимыми.

Добавьте правило остановки: если источников недостаточно или они противоречат друг другу, отчёт должен сообщить об ограничении, а не маскировать его уверенным текстом. Это важнее объёма ответа.

Полная документация LLMTOKENAPI содержит правила авторизации и соседние методы Web API. Надёжная интеграция Research API строится вокруг четырёх вещей: точной постановки задачи, бюджета до запуска, устойчивого асинхронного клиента и обязательной проверки цитат перед использованием результата.