Migración gradual a la API de Responses
En esta página
Actualizado el 3 de noviembre de 2026: El mapeo de parámetros indicaba anteriormente que
max_tokensmantenía su nombre en la API de Responses; la tabla de xAI lo cambia amax_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:
messagescon rolsystem→instructions(parámetro dedicado)messagescon roluser→input(cadena simple)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, según la tabla de mapeo de xAI;temperaturemantiene su nombreresponse.usage.prompt_tokensycompletion_tokens→input_tokensyoutput_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:
- Identifica las llamadas a Chat Completions en tu código
- Clasifícalas por complejidad (básico → streaming → llamada a funciones)
- Migra primero los nuevos endpoints o funciones (greenfield)
- Migra después las llamadas existentes más sencillas
- 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).