Ir al contenido principal
Español— Elegir un idioma
Menú

API de Responses frente a Chat Completions: por qué migrar

Lección 2 de 22 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. API de Responses frente a Chat Completions
  2. Cambios fundamentales
  3. Gestión de sesiones en el servidor
  4. JSON garantizado, no JSON con esperanza
  5. Llamadas a funciones y streaming
  6. Guía rápida de migración
  7. ¿Debes migrar de inmediato?
  8. Puntos clave

API de Responses frente a Chat Completions

La API de Chat Completions fue el estándar durante años y gran parte del código que encontrarás en línea sigue utilizándola. Sin embargo, desde 2025, OpenAI la ha marcado como obsoleta (legacy) y recomienda la API de Responses para todos los proyectos nuevos. Esta lección compara ambas interfaces, centrándose en las diferencias que impactan realmente en tu código.

Cambios fundamentales

Con Chat Completions, construías una lista de mensajes y enviabas la lista completa en cada llamada. El estado de la conversación residía en tu aplicación, nunca en el servidor:

from openai import OpenAI
client = OpenAI()

# Modelo antiguo — Chat Completions (obsoleto)
response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"},
    ]
)
print(response.choices[0].message.content)
# Resultado: "The capital of France is Paris."

La API de Responses reduce esta misma llamada a dos parámetros y ofrece acceso directo al texto generado. El mensaje de sistema se convierte en el parámetro instructions, y extraer el contenido ya no requiere navegar por choices[0].message.content:

from openai import OpenAI
client = OpenAI()

# Modelo nuevo — API de Responses
response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the capital of France?"
)
print(response.output_text)
# Resultado: "The capital of France is Paris."

Gestión de sesiones en el servidor

Esta es la ventaja más inmediata. La API mantiene el estado de la conversación, por lo que solo necesitas hacer referencia a la respuesta anterior mediante su ID. Imagina un asistente de soporte: en el décimo turno, el enfoque de Chat Completions te obligaba a reenviar los nueve intercambios anteriores, lo que significaba pagar de nuevo por esos tokens. Aquí, basta un único campo:

# Primera pregunta
response = client.responses.create(
    model="gpt-5.6-terra",
    input="My name is Marie."
)

# Segunda pregunta — el contexto se conserva automáticamente
followup = client.responses.create(
    model="gpt-5.6-terra",
    input="What is my name?",
    previous_response_id=response.id
)
print(followup.output_text)
# Resultado: "Your name is Marie."

JSON garantizado, no JSON con esperanza

La segunda gran mejora concerne a la salida estructurada. Describes el formato esperado y la API de Responses garantiza que la respuesta se ajuste a tu esquema JSON, lo que te permite deserializar sin redes de seguridad. Un formulario de registro que extrae información de texto libre ya no se rompe simplemente porque el modelo decida añadir una frase introductoria antes de su JSON:

from pydantic import BaseModel

class City(BaseModel):
    name: str
    country: str
    population: int

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Give me information about Paris.",
    text={"format": {"type": "json_schema", "json_schema": {
        "name": "city",
        "strict": True,
        "schema": City.model_json_schema()
    }}}
)
print(response.output_text)
# Resultado: {"name": "Paris", "country": "France", "population": 2161000}

Llamadas a funciones y streaming

La declaración de herramientas sigue la misma lógica de simplificación: el descriptor de la función se declara de forma plana en tools, y la llamada solicitada por el modelo aparece directamente en response.output, sin niveles de anidamiento adicionales.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the weather like in Lyon?",
    tools=[{
        "type": "function",
        "name": "get_meteo",
        "description": "Get the weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "Name of the city"}
            },
            "required": ["city"]
        }
    }]
)

# La API devuelve directamente la llamada a la función que hay que ejecutar
for item in response.output:
    if item.type == "function_call":
        print(f"Function: {item.name}, Arguments: {item.arguments}")
# Resultado: Function: get_meteo, Arguments: {"city": "Lyon"}

El streaming ya no devuelve un flujo de fragmentos indiferenciados, sino eventos tipados. Filtras por event.type y sabes exactamente qué estás gestionando: un fragmento de texto, un argumento de función o el final de la generación:

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="Tell a short story.",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Guía rápida de migración

Chat CompletionsAPI de Responses
client.chat.completions.create()client.responses.create()
messages=[...]input="..." o input=[...]
response.choices[0].message.contentresponse.output_text
Historial manualprevious_response_id
response_formattext={"format": {...}}
tools + tool_choicetools (simplificado)

¿Debes migrar de inmediato?

La API de Chat Completions sigue funcionando y no se va a eliminar. El código existente que funciona, no requiere cambios y depende de una tubería de pruebas construida alrededor del formato antiguo no obtiene ningún beneficio de una reescritura urgente. Del mismo modo, si dependes de una biblioteca de terceros que aún no admite la API de Responses, espera a su actualización. Sin embargo, para cualquier proyecto nuevo, la respuesta es clara: la API de Responses es el punto de partida, y el resto de este curso parte de esa premisa.

Puntos clave

  • La API de Responses sustituye a Chat Completions con una interfaz más sencilla
  • La gestión de sesiones en el servidor elimina la necesidad de reenviar el historial
  • La salida estructurada y las llamadas a funciones están integradas de forma nativa
  • La migración es sencilla: los conceptos permanecen iguales, solo cambia la sintaxis