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

Migración gradual a la API de Responses

Lección 12 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Por qué y cuándo migrar
  2. Paso 1: Identifica las funciones que utilizas
  3. Paso 2: Migra las llamadas básicas
  4. Paso 3: Migra conversaciones de varios turnos
  5. Paso 4: Aprovecha las nuevas funciones
  6. Estrategia de migración recomendada
  7. Puntos clave
  8. Pon a prueba tus conocimientos

Actualizado el 3 de noviembre de 2026: El mapeo de parámetros indicaba anteriormente que max_tokens mantenía su nombre en la API de Responses; la tabla de xAI lo cambia a max_output_tokens, y los contadores de uso también cambian de nombre. Fuente: Comparación con Chat Completions.

Por qué y cuándo migrar

El endpoint de Chat Completions está marcado como heredado (legacy). Seguirá funcionando, pero no se añadirán nuevas funcionalidades. Si tu aplicación necesita herramientas del lado del servidor (búsqueda web, ejecución de código), almacenamiento de conversaciones o razonamiento cifrado, la migración a la API de Responses se vuelve necesaria.

La buena noticia: esta migración puede realizarse de forma gradual. No necesitas reescribir todo de una vez.

Paso 1: Identifica las funciones que utilizas

Antes de migrar, haz un inventario de lo que tu aplicación usa con Chat Completions:

# Auditoría de tu código existente
# Busca estos patrones:

# 1. Llamadas básicas (texto simple)
client.chat.completions.create(model=..., messages=...)

# 2. Streaming
client.chat.completions.create(..., stream=True)

# 3. Llamada a funciones
client.chat.completions.create(..., tools=[...])

# 4. Visión (imágenes)
# mensajes con contenido como array [text, image_url]

# 5. Parámetros de generación
# temperature, max_tokens, top_p, stop, seed

Las llamadas básicas y el streaming son lo más sencillo de migrar. La llamada a funciones requiere adaptar el formato. La visión funciona de manera similar.

Paso 2: Migra las llamadas básicas

Migrar una llamada sencilla sigue este patrón:

# ANTES — Chat Completions
response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)
texte = response.choices[0].message.content

# DESPUÉS — API de Responses
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    instructions="You are a helpful assistant.",
    input="Hello!"
)
texte = response.output_text

Mapeo de campos

Los cambios principales son:

  • messages con rol system → instructions (parámetro dedicado)
  • messages con rol user → input (cadena simple)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens, según la tabla de mapeo de xAI; temperature mantiene su nombre
  • response.usage.prompt_tokens y completion_tokens → input_tokens y output_tokens (detalles: input_tokens_details.cached_tokens, output_tokens_details.reasoning_tokens)

Paso 3: Migra conversaciones de varios turnos

Aquí es donde la API de Responses simplifica las cosas. En lugar de reconstruir el historial en cada petición, las encadenas por ID:

# ANTES — Chat Completions (gestiona el historial tú mismo)
historique = [
    {"role": "system", "content": "You are a helpful assistant."}
]

def envoyer_message(texte: str) -> str:
    historique.append({"role": "user", "content": texte})
    response = client.chat.completions.create(
        model="grok-4.20-0309-reasoning",
        messages=historique
    )
    reponse = response.choices[0].message.content
    historique.append({"role": "assistant", "content": reponse})
    return reponse

# DESPUÉS — API de Responses (el servidor gestiona el historial)
dernier_id = None

def envoyer_message(texte: str) -> str:
    response = client.responses.create(
        model="grok-4.20-0309-reasoning",
        instructions="You are a helpful assistant.",
        input=texte,
        previous_response_id=dernier_id
    )
    dernier_id = response.id
    return response.output_text

El código es más sencillo y ya no tienes que gestionar manualmente el array de mensajes.

Paso 4: Aprovecha las nuevas funciones

Una vez migrado, puedes utilizar funciones exclusivas de la API de Responses:

Búsqueda web integrada

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest developments in generative AI?",
    tools=[{"type": "web_search"}]
)
# La respuesta incluye citas con URLs de origen

Almacenamiento de respuestas

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Analyze this document...",
    store=True  # Se conserva durante 30 días
)

# Recuperar más tarde
stored = client.responses.retrieve(response.id)

Razonamiento cifrado

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Solve this complex problem...",
    include=["reasoning.encrypted_content"]
)
# El razonamiento cifrado puede reutilizarse en peticiones posteriores

Estrategia de migración recomendada

En lugar de migrar todo de golpe, procede por pasos:

  1. Identifica las llamadas a Chat Completions en tu código
  2. Clasifícalas por complejidad (básico → streaming → llamada a funciones)
  3. Migra primero los nuevos endpoints o funciones (greenfield)
  4. Migra después las llamadas existentes más sencillas
  5. Mantén Chat Completions para integraciones de terceros que lo requieran (LangChain, etc.)

Coexistencia temporal

Es perfectamente aceptable ejecutar ambos endpoints simultáneamente durante la transición:

# Wrapper que abstrae el endpoint utilizado
class GrokClient:
    def __init__(self, use_responses: bool = False):
        self.use_responses = use_responses
        self.client = OpenAI(
            api_key=os.getenv("XAI_API_KEY"),
            base_url="https://api.x.ai/v1"
        )

    def generate(self, system: str, user_message: str) -> str:
        if self.use_responses:
            response = self.client.responses.create(
                model="grok-4.20-0309-reasoning",
                instructions=system,
                input=user_message
            )
            return response.output_text
        else:
            response = self.client.chat.completions.create(
                model="grok-4.20-0309-reasoning",
                messages=[
                    {"role": "system", "content": system},
                    {"role": "user", "content": user_message}
                ]
            )
            return response.choices[0].message.content

Este enfoque te permite cambiar gradualmente probando cada migración individualmente.

Puntos clave

  • La migración puede ser gradual: no hace falta reescribir todo de una vez
  • Cambios principales: messages → input/instructions, choices[0].message.content → output_text
  • Las conversaciones de varios turnos pasan de un array de mensajes a un simple previous_response_id
  • La API de Responses da acceso a funciones exclusivas (web_search, almacenamiento, razonamiento cifrado)
  • Ejecuta ambos endpoints simultáneamente durante la transición y migra por orden de complejidad

Pon a prueba tus conocimientos

La API heredada comprendida y la migración preparada.

1. ¿Qué significa el estado heredado y sin estado de Chat Completions?

Respuesta: El endpoint sigue siendo compatible pero ya no evoluciona: al ser sin estado, requiere reenviar todo el historial en cada llamada; la API de Responses es la vía moderna.

2. ¿Qué roles estructuran los mensajes?

Respuesta: system (y developer), user, assistant: el marco, las peticiones, las respuestas; todo el historial se reinicia en cada petición.

3. ¿Cómo utilizas código OpenAI existente con Grok?

Respuesta: Cambiando base_url a https://api.x.ai/v1 y la clave de API; la compatibilidad de formato se encarga del resto, incluidos los SDK de OpenAI y Vercel AI.

4. ¿Qué lees en la respuesta y el uso?

Respuesta: choices transporta las respuestas con finish_reason; usage detalla los tokens, incluidos reasoning_tokens para modelos de razonamiento: la base para el seguimiento de costes.

5. ¿Cómo migras limpiamente a la API de Responses?

Respuesta: Gradualmente: nuevos desarrollos en Responses, endpoints existentes convertidos uno a uno con nuevas pruebas de prompt; comparar los dos formatos guía la conversión.

Comprende lo heredado, construye para lo moderno: el plan de migración gradual del curso es tu hoja de ruta, sin grandes explosiones (big bang).