Responses API или Chat Completions: что выбрать

Сравните форматы запросов, потоковую передачу, инструменты и совместимость с провайдерами, прежде чем выбрать Responses API или Chat Completions для ИИ-приложения.

Responses API или Chat Completions: что выбрать

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

Самое короткое правило выбора:

  • Используйте Responses API для агента для программирования или приложения, которое уже ожидает элементы Responses, события инструментов и жизненный цикл потоковой передачи Responses.
  • Используйте Chat Completions для широко совместимых чат-клиентов и семейств провайдеров, которые предоставляют свои модели в стиле OpenAI через прямую передачу (raw pass-through) Chat Completions.

Всегда проверяйте поддерживаемый формат API выбранной модели в разделе Модели и цены.

Сравнение протоколов

Вопрос Responses API Chat Completions
Основная форма ввода input и типизированные элементы ввода Массив messages
Модель вывода Типизированные элементы вывода и события Варианты сообщений ассистента и дельты
Потоковая передача Поток событий Responses Поток фрагментов (chunks) Chat Completions
Работа инструментов Типизированные элементы вызовов инструментов и их результатов Вызовы инструментов в сообщениях ассистента
Лучше всего подходит Агентам, инструментам для программирования и приложениям, изначально построенным на Responses Чат-клиентам и широко поддерживаемым провайдерам, совместимым с OpenAI
Переносимость моделей Только модели, проверенные для Responses Только модели, проверенные для Chat Completions

Таблица описывает сетевой контракт. Она не означает, что Modelflare преобразует любую функцию провайдера из одного формата в другой.

Когда лучше подходит Responses API

Выбирайте /v1/responses, если клиент уже воспринимает работу модели как последовательность типизированных элементов, а не как одно сообщение ассистента. Это типично для агентов для программирования, которым нужно различать видимый текст, сводки рассуждений, аргументы функций, ввод собственных (custom) инструментов и другие события.

Минимальный запрос выглядит так:

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "List the three checks to make before an API migration.",
    "stream": true
  }'

Потоковую передачу Responses нужно проверять от начала до конца. Клиент, который понимает фрагменты Chat Completions, но не события Responses, может успешно подключиться и всё равно не показать полезного вывода.

Когда безопаснее выбрать Chat Completions

Выбирайте /v1/chat/completions, если приложение построено вокруг сообщений system, user, assistant и tool или если для выбранного семейства провайдеров задокументирован эндпоинт Chat Completions, совместимый с OpenAI.

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "system", "content": "Answer concisely."},
      {"role": "user", "content": "What should an API health check verify?"}
    ],
    "stream": true
  }'

Для семейств провайдеров, отличных от OpenAI, Modelflare может предоставлять прямую передачу Chat Completions, чтобы приватные поля запроса — например, специфичные для провайдера настройки рассуждений или поиска — доходили до поставщика без изменений. Это намеренно более узкое обещание, чем заявление о полной совместимости с Responses.

Не выбирайте только по названию модели

Нужны три отдельные проверки:

  1. У API-ключа есть доступ к модели. Доступ зависит от ключа и доступных групп моделей.
  2. Модель поддерживает эндпоинт. Если модель есть в /v1/models, это ещё не значит, что она принимает оба формата запросов.
  3. Клиент понимает поток. События Responses и фрагменты Chat Completions — это разные контракты для клиента.

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

Перенос инструментов и структурированного вывода

Прежде чем переносить существующую интеграцию:

  • сравните схему определения инструментов, которую использует клиент;
  • проверьте, как возвращаются ID вызовов инструментов и их результаты;
  • сохраняйте явно заданные необязательные значения, а не отбрасывайте 0 или false;
  • выясните, требует ли провайдер приватных полей, которые должны передаваться без изменений;
  • протестируйте ответы только из вызовов инструментов, в которых может не быть видимой текстовой дельты;
  • уточните, как клиент определяет завершение ответа и данные об использовании.

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

Практический порядок выбора

  1. Откройте раздел Модели и цены и выберите модель и группу.
  2. Убедитесь, что нужный формат API поддерживается.
  3. Если для вашего клиента есть отдельное руководство в документации Modelflare, следуйте ему.
  4. Отправьте один запрос без потоковой передачи.
  5. Отправьте один потоковый запрос.
  6. Проверьте инструменты или структурированный вывод.
  7. Найдите запрос в журнале использования и проверьте статус, время, расход токенов и стоимость.

Responses API — не универсальная замена Chat Completions, а Chat Completions не устарел. Правильный формат — тот, который одновременно поддерживают клиент, выбранная модель и контракт поставщика.

Выбрав формат, используйте руководство по потоковой передаче в ИИ-API, чтобы реализовать парсер событий, метрики времени, отмену и политику тайм-аутов.