Responses API

Responses API принимает запросы на генерацию по единому адресу POST https://route.smartaipack.ru/v1/responses. Для минимального запроса нужны два поля: точный идентификатор модели model и входные данные input. Модель обязательно выбирайте в каталоге кабинета: там видны совместимость с /v1/responses, возможности конкретного поставщика и значение request_model_id, которое нужно передать без изменений.

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

Базовый адрес

Полный адрес Responses API:

https://route.smartaipack.ru/v1/responses

Метод — только POST, тело — JSON. Путь /v1/responses опубликован отдельно от других протоколов шлюза. Наличие модели в общем списке ещё не означает, что она работает именно на этом пути: откройте Модели, найдите поставщика и убедитесь, что среди его путей указан /v1/responses.

Для запроса копируйте показанный там request_model_id. Не подставляйте название из памяти и не пытайтесь самостоятельно собрать префикс поставщика: каталог отражает действующую маршрутизацию. Сводка опубликованных путей также есть в справочнике API, а актуальные цены — на странице Тарифы.

Авторизация

Каждый запрос должен содержать ключ организации в Bearer-заголовке:

Authorization: Bearer <ВАШ_API-КЛЮЧ>

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

Подробные правила выпуска, хранения и отзыва ключей собраны в руководстве по авторизации API.

Основные возможности

Responses API даёт один формат обращения к моделям, которые опубликованы на /v1/responses:

• простой текстовый ввод через input;
• явный выбор модели и, когда доступно, конкретного поставщика через request_model_id;
• работа с моделями, у которых в каталоге отмечена поддержка рассуждения;
• сценарии с инструментами для вариантов, у которых отмечена соответствующая возможность;
• учёт запросов и расхода в кабинете организации.

Это перечень возможностей маршрута и каталога, а не обещание их одновременной поддержки любой моделью. Проверяйте признаки Рассуждение, Инструменты и список путей у конкретного поставщика. Если нужного признака или /v1/responses нет, не отправляйте относящиеся к нему поля наугад.

Базовое использование

Сначала сохраните ключ в переменной окружения, не выводя его значение в консоль. Затем скопируйте совместимый request_model_id из каталога моделей и подставьте его вместо заполнителя:

curl https://route.smartaipack.ru/v1/responses \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<REQUEST_MODEL_ID_ИЗ_КАТАЛОГА>",
    "input": "Объясни простыми словами, чем резервная копия отличается от архива."
  }'

Не используйте фиксированную модель из чужого примера: доступность, поставщик и маршруты меняются. Успешный HTTP-ответ означает, что шлюз принял запрос и выбранный поставщик вернул результат. Структуру ответа разбирайте как JSON и не сводите обработку только к одному предполагаемому текстовому полю: она может зависеть от результата и возможностей модели.

Пошаговый разбор продолжится в статье Базовое использование Responses API.

Рассуждение

В каталоге AI Gateway возможность рассуждения отмечается отдельно для модели и поставщика. Она может влиять на доступные параметры, состав результата и стоимость: токены рассуждения учитываются как самостоятельная составляющая тарификации, когда они присутствуют в вызове.

Не добавляйте параметры рассуждения только потому, что они встречаются в документации другого сервиса. Репозиторий AI Gateway подтверждает признак поддержки и учёт таких токенов, но не задаёт один универсальный JSON-формат управления рассуждением для всех поставщиков Responses API. Безопасный порядок такой:

1. Выберите на странице Модели вариант с поддержкой рассуждения и /v1/responses.
2. Скопируйте его request_model_id.
3. Начните с минимального запроса model + input.
4. Перед добавлением необязательных полей проверьте контракт выбранного поставщика и испытайте запрос вне рабочей нагрузки.

Практические варианты будут разобраны отдельно в статье Рассуждение в Responses API.

Вызов инструментов

Поддержка инструментов также относится не ко всему адресу API, а к конкретной модели у конкретного поставщика. Каталог показывает этот признак рядом с вариантом маршрута. Если он не отмечен, нельзя считать, что модель примет описание инструмента или вернёт запрос на его выполнение.

AI Gateway передаёт запрос выбранному маршруту, но инструмент исполняет ваше приложение. Поэтому приложение должно проверить имя и аргументы вызова, разрешить только известные действия, выполнить их с минимальными правами и безопасно передать результат обратно в соответствии с контрактом выбранного поставщика. Не позволяйте модели напрямую выполнять произвольные команды, запросы к базе или действия от имени пользователя.

Универсальный JSON-пример здесь намеренно не приводится: текущий проект подтверждает поддержку инструментов как возможность каталога, но не фиксирует одну схему вызова для всех поставщиков Responses API. Продолжение — в статье Вызов инструментов в Responses API.

Обработка ошибок

Сначала проверяйте HTTP-статус, затем Content-Type и только после этого разбирайте тело. Формат ошибки зависит от слоя, на котором запрос был отклонён, поэтому поле error.code присутствует не во всех ответах поставщиков в одинаковом виде.

Частые случаи:

Не повторяйте без изменений ошибки 400, 401, 402 и 403. Для 429, 502 и 503 используйте ограниченные повторы с увеличивающейся паузой и случайным разбросом. Полная таблица и правила диагностики приведены в статье Ошибки API, а отдельный разбор Responses — в статье Обработка ошибок Responses API.

Если ошибка сохраняется, сопоставьте время, путь и модель с журналом использования и аналитикой. В обращение в поддержку передавайте эти данные и код ошибки, но никогда не отправляйте полный API-ключ.

Ограничения частоты

По умолчанию каждый API-ключ AI Gateway ограничен 120 запросами в минуту. Лимит относится к ключу, поэтому отдельные процессы с одним секретом расходуют общую квоту. При превышении шлюз отвечает 429 Too Many Requests.

Чтобы не создавать всплески:

• ограничьте число одновременных запросов в приложении;
• ставьте задачи в очередь, если нагрузка приходит рывками;
• для 429 используйте ограниченные повторы с увеличивающейся задержкой;
• не запускайте все отложенные повторы одновременно;
• следите за фактическими вызовами в разделе Использование.

Текущий кабинет не позволяет самостоятельно изменить число запросов в минуту; для изменения лимита требуется обратиться в поддержку. Подробнее о квотах, подсчёте и безопасных повторах — в руководстве по лимитам API.

Перед рабочим запуском проверьте четыре вещи: ключ хранится на сервере, request_model_id скопирован из каталога, у выбранного поставщика отмечены /v1/responses и нужные возможности, а приложение ограничивает повторы. После первого вызова найдите его в журнале использования и проверьте стоимость в аналитике.