Responses API vs. Chat Completions: ¿qué formato usar?

Compara formatos de solicitud, streaming, herramientas y compatibilidad con proveedores antes de elegir Responses API o Chat Completions para tu aplicación de IA.

Responses API vs. Chat Completions: ¿qué formato usar?

Responses API y Chat Completions envían prompts a modelos de lenguaje, pero organizan de forma distinta la entrada, la salida, las herramientas y el streaming. La elección debe partir del contrato entre el cliente y el modelo, no de suponer que un endpoint más reciente funciona automáticamente con cualquier proveedor.

La regla de decisión más corta es:

  • Usa Responses API para un agente de programación o una aplicación que ya espera elementos de Responses, eventos de herramientas y el ciclo de streaming de Responses.
  • Usa Chat Completions para clientes de chat con amplia compatibilidad y para familias de proveedores que exponen sus modelos con formato de OpenAI mediante un reenvío directo de Chat Completions sin transformar.

Verifica siempre el formato de API que admite el modelo elegido en Modelos y precios.

Comparación de protocolos

Pregunta Responses API Chat Completions
Estructura principal de entrada input y elementos de entrada tipados Un arreglo messages
Modelo de salida Elementos y eventos de salida tipados Opciones de mensajes del asistente y deltas
Streaming Flujo de eventos de Responses Flujo de fragmentos de Chat Completions
Actividad de herramientas Elementos tipados de llamada y resultado de herramienta Llamadas a herramientas asociadas a los mensajes del asistente
Mejor uso Agentes, herramientas de programación y aplicaciones nativas de Responses Clientes de chat y proveedores compatibles con OpenAI de amplio soporte
Portabilidad del modelo Solo modelos verificados para Responses Solo modelos verificados para Chat Completions

La tabla describe el contrato de comunicación. No implica que Modelflare convierta todas las funciones de un proveedor entre los dos formatos.

Cuándo conviene más Responses API

Elige /v1/responses cuando el cliente ya trate cada ejecución del modelo como una secuencia de elementos tipados y no como un único mensaje del asistente. Es habitual en agentes de programación que necesitan distinguir el texto visible, los resúmenes de razonamiento, los argumentos de funciones, la entrada de herramientas personalizadas y otros eventos.

Una solicitud mínima se ve así:

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
  }'

Valida el streaming de Responses de extremo a extremo. Un cliente que entiende los fragmentos de Chat Completions pero no los eventos de Responses puede conectarse correctamente y aun así no mostrar ninguna salida útil.

Cuándo Chat Completions es la opción más segura

Elige /v1/chat/completions cuando la aplicación esté construida en torno a mensajes system, user, assistant y tool, o cuando la familia de proveedores elegida documente un endpoint de Chat Completions compatible con 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
  }'

Para familias de proveedores distintas de OpenAI, Modelflare puede ofrecer un reenvío directo de Chat Completions sin transformar, de modo que los campos privados de la solicitud, como los controles de razonamiento o de búsqueda específicos del proveedor, lleguen sin cambios al proveedor. Este comportamiento es deliberadamente más acotado que afirmar una compatibilidad total con Responses.

No elijas solo por el nombre del modelo

Se necesitan tres verificaciones independientes:

  1. La clave de API puede acceder al modelo. El acceso depende de la clave y de los grupos de modelos disponibles.
  2. El modelo admite el endpoint. Que un modelo aparezca en /v1/models no lo hace válido automáticamente para ambos formatos de solicitud.
  3. El cliente entiende el flujo. Los eventos de Responses y los fragmentos de Chat Completions son contratos de cliente diferentes.

Si alguna de estas verificaciones falla, cambiar solo la ruta del endpoint puede convertir un error de compatibilidad claro en una respuesta vacía o mostrada solo en parte.

Migración de herramientas y salida estructurada

Antes de mover una integración existente:

  • compara el esquema de definición de herramientas que usa el cliente;
  • verifica cómo se devuelven los ID de llamada a herramientas y sus resultados;
  • conserva los valores opcionales explícitos en lugar de descartar 0 o false;
  • revisa si el proveedor requiere campos privados que deban pasar sin cambios;
  • prueba respuestas formadas solo por herramientas, que pueden no contener ningún delta de texto visible;
  • confirma cómo detecta el cliente la finalización y el uso.

Que el mismo prompt produzca un texto parecido no es una prueba de protocolo suficiente. Una prueba real debe incluir las funciones de las que depende la aplicación.

Un flujo práctico de selección

  1. Abre Modelos y precios y elige el modelo y el grupo.
  2. Confirma el formato de API admitido.
  3. Sigue una guía específica para tu cliente en la documentación de Modelflare, si existe.
  4. Envía una solicitud sin streaming.
  5. Envía una solicitud con streaming.
  6. Prueba las herramientas o la salida estructurada.
  7. Revisa la solicitud en los registros de uso: estado, tiempos, uso de tokens y costo.

Responses API no es un reemplazo universal de Chat Completions, y Chat Completions no está obsoleto. El formato correcto es el que admiten a la vez el cliente, el modelo elegido y el contrato del proveedor.

Una vez elegido el formato, usa la guía de streaming de API de IA para implementar su analizador de eventos, las métricas de tiempos, la cancelación y la política de tiempos de espera.