Responses API или Chat Completions

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

Краткое правило:

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

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

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

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

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

Когда лучше выбрать Responses API

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

Минимальный запрос:

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": "Перечисли три проверки перед миграцией API.",
    "stream": true
  }'

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

Когда безопаснее Chat Completions

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

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": "Отвечай кратко."},
      {"role": "user", "content": "Что должна проверять диагностика состояния API?"}
    ],
    "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. Отправьте запрос без streaming.
5. Отправьте потоковый запрос.
6. Проверьте инструменты или структурированный вывод.
7. Сверьте статус, время, токены и стоимость в журнале использования.

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