Chat Completions vs Responses API: cuál usar y cuándo migrar

Si empiezas un proyecto con la API de OpenAI, usa Responses API. Si ya tienes una integración estable con Chat Completions que genera texto o salida estructurada, puedes dejarla como está: a 25 de septiembre de 2026, OpenAI la mantiene soportada y no ha anunciado fecha de retirada para /v1/chat/completions. Lo que sí la vuelve insuficiente es la combinación de herramientas con razonamiento: desde GPT-5.4, Chat Completions solo admite llamadas a herramientas con reasoning_effort en none, y con GPT-6 Astra no admite function calling en absoluto.

Resumido en una regla: si tu flujo llama a funciones y quieres que el modelo razone, o si necesitas las herramientas alojadas por OpenAI (búsqueda web, búsqueda en archivos, intérprete de código, MCP remoto), tu destino es Responses. Para lo demás, migrar es una mejora recomendada que puedes hacer flujo a flujo, no una urgencia.

Qué API te toca según tu modelo y lo que usas

La guía de migración de OpenAI resume la postura oficial en dos frases: Chat Completions «sigue soportada» y Responses se recomienda para todos los proyectos nuevos. Las condiciones concretas que inclinan la balanza dependen del modelo y de las funciones que tengas activas:

Las restricciones por modelo están en la guía de razonamiento y en la de function calling, que indica literalmente que «GPT-6 Astra requires the Responses API for tool calling». La página de GPT-6 Astra lista los niveles de razonamiento que acepta (low, medium, high, xhigh, max) y precisa que sus herramientas alojadas están disponibles «when using the Responses API».

Hay una consecuencia práctica que no aparece escrita así en la documentación, pero se deduce de ella: GPT-5.6 Sol (alias gpt-5.6) razona en medium por defecto. Para enviarle herramientas por Chat Completions tendrías que bajar reasoning_effort a none, es decir, renunciar al razonamiento en esas peticiones. En Responses mantienes las dos cosas. Lo mismo aplica a GPT-6 Sol y GPT-6 Luna, que aceptan de none a max y también parten de medium.

Si todavía no has elegido modelo, empieza por ahí: la comparativa de modelos de texto de OpenAI en 2026 resume IDs y usos, y GPT-6 Luna vs Sol calcula el coste por tarea de esos dos modelos, que funcionan en ambas APIs.

¿Chat Completions está obsoleta?

No. La página de deprecaciones no incluye ninguna entrada que retire /v1/chat/completions, y la guía de migración sigue describiéndola como soportada. OpenAI recomienda migrar «all flows to the Responses API over time» y, precisamente porque Chat Completions sigue en pie, propone hacerlo de un flujo de usuario en uno.

Tres cosas que se confunden con esa supuesta retirada:

• Assistants API sí desapareció: se apagó el 26 de agosto de 2026 y su sustituto oficial es Responses junto con la Conversations API. Si todavía tienes código de Assistants, esa migración ya no es opcional.
• Completions (legacy), el endpoint /v1/completions de texto sin roles, es otra API más antigua. La etiqueta «legacy» es suya, no de Chat Completions.
• La CLI de Codex dejó de aceptar wire_api = "chat" en febrero de 2026, según el anuncio en GitHub. Es un cliente que abandona el protocolo, no la API que cierra. Si configuras Codex con un proveedor propio, el artículo sobre conectar Codex a una API de modelos externa explica cómo hacerlo con Responses.

Qué cambia de verdad al pasar a Responses

El cambio de URL (POST /v1/chat/completions → POST /v1/responses) es lo de menos. Chat Completions trabaja con mensajes: entran como messages y salen dentro de choices[].message, con la llamada a herramientas pegada al mensaje del asistente. Responses trabaja con Items, elementos tipados e independientes: un mensaje es un tipo de Item, y también lo son reasoning, function_call y function_call_output. De ahí salen casi todas las diferencias:

Para una llamada de texto de un solo turno, el cambio es pequeño:

from openai import OpenAI

client = OpenAI()

# Chat Completions
completion = client.chat.completions.create(
    model="gpt-5.6",
    messages=[
        {"role": "system", "content": "Clasifica tickets de soporte en una palabra."},
        {"role": "user", "content": "No puedo iniciar sesión desde ayer."},
    ],
)
print(completion.choices[0].message.content)

# Responses API
response = client.responses.create(
    model="gpt-5.6",
    instructions="Clasifica tickets de soporte en una palabra.",
    input="No puedo iniciar sesión desde ayer.",
)
print(response.output_text)

Si no usas funciones ni entradas multimodales, también puedes pasar tu lista de mensajes role/content tal cual como input. Eso sirve para una primera prueba, pero no convierte en compatible el código que lee la respuesta: con un modelo de razonamiento, el primer elemento de output suele ser un Item reasoning, no el mensaje. Si lees output[0] esperando texto, te encontrarás con un Item sin el texto de la respuesta. Usa output_text para el texto final y recorre output por tipo cuando haya herramientas o razonamiento de por medio.

Llamadas a herramientas: donde más código se rompe

En Chat Completions, el modelo devuelve un mensaje del asistente con tool_calls, tú ejecutas la función y respondes con un mensaje role: "tool" que lleva tool_call_id. En Responses, la llamada y su resultado son dos Items separados que se enlazan por call_id. Tres detalles provocan la mayoría de fallos:

• arguments llega como string JSON, no como objeto: hay que parsearlo con json.loads.
• El output que devuelves en function_call_output debe ser normalmente un string (JSON, un código de error o texto plano). Para imágenes o archivos puedes pasar una lista de objetos de imagen o de archivo. Si tu función no devuelve nada, devuelve algo como "success".
• Con modelos de razonamiento, los Items reasoning que acompañan a las llamadas tienen que volver en la siguiente petición junto con los resultados. La forma más segura es reenviar todo response.output.

Este ejemplo completo sigue el patrón de la guía de function calling; consultar_pedido es una función de ejemplo que sustituirías por la tuya:

import json
from openai import OpenAI

client = OpenAI()

tools = [{
    "type": "function",
    "name": "consultar_pedido",
    "description": "Devuelve el estado de un pedido a partir de su ID.",
    "parameters": {
        "type": "object",
        "properties": {"pedido_id": {"type": "string"}},
        "required": ["pedido_id"],
        "additionalProperties": False,
    },
}]

def consultar_pedido(pedido_id: str) -> dict:
    return {"pedido_id": pedido_id, "estado": "enviado"}

entrada = [{"role": "user", "content": "¿En qué estado está el pedido A-1042?"}]
response = client.responses.create(model="gpt-5.6", input=entrada, tools=tools)

entrada += response.output  # conserva reasoning y function_call
for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)  # arguments es un string JSON
        resultado = consultar_pedido(**args)
        entrada.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps(resultado),
        })

final = client.responses.create(model="gpt-5.6", input=entrada, tools=tools)
print(final.output_text)

El bucle recorre todos los Items porque el modelo puede pedir varias funciones en el mismo turno; si quieres como máximo una, pon parallel_tool_calls=False. El esquema lleva additionalProperties: False y todos los campos en required porque, al omitir strict, Responses intenta el modo estricto. Si el esquema no encaja, vuelve a un modo no estricto y la herramienta resuelta aparece con strict: false. Para conservar a propósito el comportamiento que tenías en Chat Completions, declara "strict": False.

Estado de la conversación, store y lo que pagas

Chat Completions no guarda la conversación por ti: reenvías el historial en cada petición. Responses ofrece tres caminos, descritos en la guía de estado de conversación:

1. Historial manual: reenvías los Items anteriores tú mismo. Es lo más parecido a lo que ya haces y te deja recortar el contexto.
2. previous_response_id: encadenas con el ID de la respuesta anterior y OpenAI recupera el contexto.
3. Conversations API: un objeto de conversación persistente que sobrevive entre sesiones, dispositivos o trabajos.

previous_response_id tiene dos trampas. La primera: no hereda las instructions de la respuesta anterior, así que debes reenviarlas en cada turno.

primera = client.responses.create(
    model="gpt-5.6",
    instructions="Responde como analista de incidentes, en frases cortas.",
    input="Agrupa estas alertas por causa probable: ...",
)

siguiente = client.responses.create(
    model="gpt-5.6",
    previous_response_id=primera.id,
    instructions="Responde como analista de incidentes, en frases cortas.",
    input="Quédate solo con el grupo que hay que escalar ya.",
)

La segunda: no abarata la conversación. Según OpenAI, todos los tokens de entrada de las respuestas anteriores de la cadena se facturan como entrada. Lo que puede reducir el coste es la caché: OpenAI afirma haber medido en pruebas internas entre un 40 % y un 80 % más de aprovechamiento de caché en Responses frente a Chat Completions, y una mejora del 3 % en SWE-bench con modelos de razonamiento y el mismo prompt. Son cifras del propio proveedor; compruébalas con tu tráfico antes de contar con ellas.

El parámetro store no significa lo mismo en las dos APIs, y conviene tenerlo claro si tienes requisitos de privacidad:

• En Responses, store guarda el estado de la aplicación que usa previous_response_id. Según la página de controles de datos, ese estado se conserva 30 días por defecto. Con store: false no se guarda.
• En Chat Completions, la referencia define store como guardar la salida «for use in our model distillation or evals products». No tiene que ver con el estado de la conversación, pero la guía de migración indica que en cuentas nuevas se guarda por defecto.
• Las organizaciones con retención de datos cero (ZDR) tienen store forzado a false. Para mantener el razonamiento entre turnos sin estado en el servidor, reenvía los Items reasoning con su encrypted_content.
• Los objetos de la Conversations API no caducan a los 30 días: se conservan hasta que los borras y no son elegibles para ZDR.

Si no quieres que se almacene nada, pon store: false de forma explícita en cualquiera de las dos APIs y revisa la configuración de tu organización.

Salida estructurada, límites de tokens y streaming

Salida estructurada. El esquema no cambia; cambia dónde va. En Chat Completions iba en response_format con un nivel json_schema; en Responses va en text.format y el nombre sube un nivel:

esquema = {
    "type": "object",
    "properties": {"nombre": {"type": "string"}, "edad": {"type": "integer"}},
    "required": ["nombre", "edad"],
    "additionalProperties": False,
}

response = client.responses.create(
    model="gpt-5.6",
    input="Extrae nombre y edad: Lucía tiene 34 años.",
    text={"format": {"type": "json_schema", "name": "persona", "strict": True, "schema": esquema}},
)
print(response.output_text)  # JSON que cumple el esquema

Límite de salida. max_output_tokens cuenta los tokens visibles y los de razonamiento, con un mínimo de 16, según la referencia de Responses. Si copias el max_tokens que usabas en Chat Completions, un modelo de razonamiento puede agotar el presupuesto antes de escribir la respuesta y devolverte algo vacío o cortado. Microsoft lo recoge como fallo típico en su guía de migración para Azure OpenAI.

Streaming. En Chat Completions concatenabas choices[0].delta.content. Responses envía eventos con tipo y tienes que ramificar por él. La guía de streaming cita para texto response.created, response.output_text.delta, response.completed y error; si hay llamadas a funciones, llegan también response.function_call_arguments.delta y response.function_call_arguments.done.

stream = client.responses.create(
    model="gpt-5.6",
    input="Resume este ticket en dos frases: ...",
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "error":
        raise RuntimeError(str(event))
    elif event.type == "response.completed":
        break

Envuelve el bucle en un try/except: si un error de cuota, autenticación o filtro de contenido llega a mitad del stream y nadie lo captura, el stream simplemente se detiene sin decir nada.

Parámetros de muestreo. Esa misma guía de Microsoft recomienda quitar seed y comprobar si el modelo de destino acepta temperature y top_p, sobre todo si es de razonamiento. La guía de OpenAI no menciona seed; tómalo como una comprobación más, no como una regla universal.

Cómo migrar un flujo de Chat Completions a Responses sin perder nada

OpenAI propone migrar de un flujo en uno y comparar antes de mover más tráfico. Ordenado para que cada paso se pueda verificar:

1. Aísla el acceso a la API. Si el código de negocio lee choices[0] directamente, crea antes una capa propia que devuelva texto, llamadas a herramientas y uso de tokens. Así la migración toca un solo sitio.
2. Empieza por un flujo de solo texto. Cambia endpoint, cuerpo de la petición y lectura de la respuesta (output_text o recorrido de output).
3. Elige cómo guardas el estado: historial manual, previous_response_id o Conversations API. Si el flujo es sin estado o tu organización usa ZDR, añade store: false y reenvía los Items reasoning cifrados.
4. Migra las funciones: aplana las definiciones, parsea arguments, devuelve function_call_output con el call_id correcto y prueba cada esquema con el modo estricto.
5. Mueve los esquemas de response_format a text.format.
6. Reescribe el consumidor de streaming para eventos tipados, con manejo de error.
7. Sustituye integraciones propias por herramientas alojadas solo donde encajen en el flujo.
8. Compara antes de ampliar: comportamiento, latencia, tokens consumidos y errores con peticiones reales. No busques frases idénticas; busca que el JSON se parsee, que no se pierda ninguna llamada a herramienta y que el stream termine.

No des por hecho que una API es más rápida que la otra: la documentación de OpenAI no incluye una comparación de latencia, y su propia lista de comprobación pide medirla con tu tráfico. Actualiza también los mocks y snapshots de los tests: los que simulan choices o choices[0].delta.content dejan de representar lo que devuelve la API.

Síntomas típicos al enviar un payload con forma de Chat Completions

Estos son los fallos que aparecen cuando parte del código sigue pensando en mensajes. Los mensajes de error literales proceden de la tabla de solución de problemas de Microsoft para Azure OpenAI; en api.openai.com el texto exacto puede variar, pero la causa es la misma.

La lista de errores comunes de la guía de OpenAI incluye dos más que conviene revisar a mano: perder Items reasoning, function_call o function_call_output al reconstruir el contexto y reutilizar el manejador de fragmentos de Chat Completions sin adaptarlo a eventos.

Proveedores «compatibles con OpenAI»

Muchos proveedores y pasarelas que se anuncian como compatibles con OpenAI implementan Chat Completions; el soporte de Responses varía mucho. Algunos exponen una ruta compatible con Responses pero sin estado e ignorando parámetros o herramientas que no soportan. Antes de migrar un flujo que pasa por un tercero, comprueba en su documentación que existe /v1/responses y qué hace con previous_response_id, store, los eventos de streaming y las herramientas alojadas.

En Azure, Microsoft documenta la migración a Responses con el cliente OpenAI apuntando a .../openai/v1/. Y si llamas a un modelo de otro proveedor con el cliente de OpenAI, como en el caso de DeepSeek V4 Pro, la documentación de ese proveedor es la que dice qué endpoint expone y con qué limitaciones.

Preguntas frecuentes

¿Puedo seguir usando Chat Completions en 2026?

Sí. A 25 de septiembre de 2026 está soportada y sin fecha de retirada. El límite real es funcional: no te sirve para combinar herramientas y razonamiento en GPT-5.4 o posterior, ni para function calling con GPT-6 Astra, ni para herramientas alojadas.

¿Responses API es más rápida?

La documentación de OpenAI no incluye una comparación de latencia. Mide con tus propias peticiones antes de sacar conclusiones; las diferencias que publica OpenAI se refieren a calidad con modelos de razonamiento y a aprovechamiento de caché, no a velocidad.

¿previous_response_id reduce el coste de una conversación larga?

No. Todos los tokens de entrada de la cadena se facturan como entrada en cada turno. Te ahorra reenviar el historial, no pagarlo.

¿Tengo que migrar si usaba Assistants API?

Sí, y no es opcional: Assistants API dejó de funcionar el 26 de agosto de 2026. Los sustitutos oficiales son Responses API y la Conversations API.