Responses API o Chat Completions: comparativa

Responses API y Chat Completions envían instrucciones 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 que comparten el cliente y el modelo, no de la idea de que el endpoint más reciente funciona automáticamente con cualquier proveedor.

La regla práctica es sencilla:

• Usa Responses API si el agente de programación o la aplicación ya espera elementos tipados, eventos de herramientas y el ciclo de streaming de Responses.
• Usa Chat Completions para clientes de chat con compatibilidad amplia y para familias de proveedores que exponen su formato OpenAI mediante passthrough de Chat Completions.

Confirma siempre el formato admitido por el modelo en Modelos y precios.

Comparación de protocolos

Pregunta	Responses API	Chat Completions
Entrada principal	input y elementos tipados	Un array messages
Modelo de salida	Elementos y eventos tipados	Opciones de mensajes del asistente y deltas
Streaming	Flujo de eventos de Responses	Flujo de fragmentos de Chat Completions
Herramientas	Llamadas y resultados como elementos tipados	Llamadas asociadas a mensajes del asistente
Mejor encaje	Agentes, herramientas de código y aplicaciones nativas de Responses	Clientes de chat y proveedores ampliamente compatibles con OpenAI
Portabilidad	Solo modelos verificados para Responses	Solo modelos verificados para Chat Completions

La tabla describe el contrato en la red. No significa que Modelflare convierta todas las funciones de un proveedor de un formato al otro.

Cuándo conviene Responses API

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

Petición mínima:

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": "Enumera las tres comprobaciones previas a una migración de API.",
    "stream": true
  }'

Valida el streaming de extremo a extremo. Un cliente capaz de abrir la conexión pero que solo entiende fragmentos de Chat Completions puede no mostrar nada útil ante los eventos de Responses.

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

Elige /v1/chat/completions si la aplicación gira en torno a mensajes system, user, assistant y tool, o si la familia del proveedor documenta específicamente un endpoint 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": "Responde de forma concisa."},
      {"role": "user", "content": "¿Qué debe comprobar una prueba de estado de la API?"}
    ],
    "stream": true
  }'

Para familias ajenas a OpenAI, Modelflare puede ofrecer passthrough de Chat Completions para que campos privados —por ejemplo, controles de razonamiento o búsqueda— lleguen intactos al proveedor. Es una garantía más precisa que afirmar una compatibilidad universal con Responses.

No decidir solo por el nombre del modelo

Hay que comprobar tres aspectos distintos:

1. La clave puede acceder al modelo. El acceso depende de la clave y de los grupos disponibles.
2. El modelo admite el endpoint. Aparecer en /v1/models no implica funcionar en ambos formatos.
3. El cliente entiende el flujo. Los eventos de Responses y los fragmentos de Chat Completions son contratos diferentes.

Si falla cualquiera de ellos, cambiar únicamente la ruta puede convertir un error de compatibilidad claro en una respuesta vacía o incompleta.

Migrar herramientas y salida estructurada

Antes de mover una integración real:

• compara el esquema de definición de herramientas;
• comprueba cómo vuelven los identificadores de llamada y sus resultados;
• no descartes valores opcionales explícitos como 0 o false;
• identifica campos privados que deban atravesar la pasarela sin cambios;
• prueba respuestas formadas solo por llamadas de herramienta, sin texto visible;
• confirma cómo detecta el cliente el final y el uso facturado.

Obtener un texto parecido con el mismo prompt no es una prueba de protocolo suficiente. La prueba debe ejercer las funciones de las que depende la aplicación.

Flujo de selección recomendado

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

Responses API no sustituye de forma universal a 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.