Основы

Чтобы отправить первый запрос в Responses API, вызовите POST https://route.smartaipack.ru/v1/responses, передайте API-ключ в Bearer-заголовке, а в JSON-теле укажите как минимум model и input. Точное значение model копируйте из поля request_model_id в каталоге моделей у варианта, для которого указан путь /v1/responses.

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

Что понадобится

• учётная запись AI Gateway и API-ключ, созданный после регистрации или входа;
• точный request_model_id из раздела Модели;
• у выбранного варианта модели должен быть указан путь /v1/responses;
• API-ключ должен храниться на сервере или в защищённой переменной окружения, а не в браузерном коде и не в репозитории.

Простой строковый ввод

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

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": "Объясни простыми словами, чем резервная копия отличается от архива."
  }'

Вместо заполнителя используйте значение без сокращений и ручного изменения префикса. Наличие названия модели в другом сервисе или общем списке ещё не подтверждает совместимость с /v1/responses в AI Gateway.

Структурированный ввод

Некоторые поставщики принимают в input массив сообщений и частей содержимого. Это удобно, когда нужно отдельно передать роль, текст или несколько элементов ввода. Распространённый вариант выглядит так:

{
  "model": "<REQUEST_MODEL_ID_ИЗ_КАТАЛОГА>",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Составь три пункта плана проверки резервной копии."
        }
      ]
    }
  ]
}

Этот пример показывает возможную форму запроса, но не является единым контрактом AI Gateway для всех поставщиков. До использования массива проверьте документацию выбранного поставщика и испытайте формат на совместимой модели из каталога. Если формат не подтверждён, используйте строковый input.

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

При обычном запросе дождитесь завершения и разберите тело как JSON. Не привязывайте приложение к одному неизменному пути вроде output[0].content[0].text: набор объектов, их типы, поля состояния, счётчики токенов и сведения об ошибках могут различаться у поставщиков и моделей.

Безопасная первичная проверка на JavaScript:

const response = await fetch("https://route.smartaipack.ru/v1/responses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AI_GATEWAY_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "<REQUEST_MODEL_ID_ИЗ_КАТАЛОГА>",
    input: "Назови два способа проверить целостность архива."
  })
});

const contentType = response.headers.get("content-type") ?? "";
const body = contentType.includes("application/json")
  ? await response.json()
  : await response.text();

if (!response.ok) {
  console.error("Ошибка API", response.status, body);
} else {
  console.log(body);
}

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

Потоковые ответы

Маршрут /v1/responses сохраняет потоковую передачу: ответ не буферизуется на прокси. Если выбранная модель и поставщик поддерживают поток на этом пути, добавьте "stream": true и используйте клиент, который читает данные по мере поступления:

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

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

Пример потокового ответа

При передаче через SSE клиент получает последовательность строк data: с пустой строкой между событиями. Условно поток выглядит так:

data: {"type":"<СОБЫТИЕ_ПОСТАВЩИКА>","...":"..."}

data: {"type":"<СЛЕДУЮЩЕЕ_СОБЫТИЕ>","...":"..."}

Это иллюстрация обрамления SSE, а не обещание конкретных type, завершающего маркера или структуры JSON. Клиент должен:

1. накапливать неполную строку между сетевыми фрагментами;
2. разбирать только завершённые события;
3. учитывать служебные события без текста;
4. завершать обработку по признаку, который определён контрактом выбранного поставщика;
5. сохранять уже показанный текст отдельно от состояния соединения.

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

Основные параметры

На уровне маршрута обязательны model и input. Остальные поля передаются дальше, но их одинаковая поддержка не гарантируется.

Шлюз не объявляет max_output_tokens, temperature и top_p универсальными параметрами AI Gateway. Если поставщик отклоняет поле, удалите его или приведите запрос к документированному для выбранной модели формату.

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

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

Базовый лимит нового ключа — 120 запросов в минуту. Все процессы, использующие один ключ, расходуют общий лимит. Подробные рекомендации есть в материалах про ошибки API и лимиты API.

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

Многошаговые диалоги

Не рассчитывайте, что AI Gateway хранит историю диалога между запросами. Контекстом управляет клиентское приложение: оно сохраняет нужные реплики и при следующем вызове формирует новый input в формате, который поддерживают выбранные модель и поставщик.

Не используйте previous_response_id, store или другие поля сохранения состояния без отдельного подтверждённого контракта поставщика. AI Gateway не заявляет для этого маршрута собственное серверное хранилище истории. Также базовый путь не следует считать обещанием встроенного веб-поиска, MCP или фоновых задач.

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

Следующие шаги

После первого успешного вызова:

1. Проверьте расход в журнале использования и аналитике.
2. Сверьте стоимость выбранного варианта на странице Тарифы.
3. Прочитайте обзор Responses API.
4. Перед сложными сценариями изучите отдельные материалы про рассуждение, вызов инструментов и обработку ошибок Responses API.
5. Для рабочей нагрузки добавьте ограничение параллелизма, безопасные повторы и наблюдение за расходом.

Главный принцип — считать каталог текущим источником маршрута и идентификатора модели, а контракт конкретного поставщика — источником структуры расширенного запроса и ответа.