Chat Completions frente a Responses API: comparación
En esta página
Dos puntos finales, dos filosofías
xAI ofrece dos puntos finales para interactuar con los modelos Grok: Chat Completions (/v1/chat/completions) y la API Responses (/v1/responses). Comprender sus diferencias es esencial para elegir el punto final adecuado para tu proyecto y planificar cualquier migración potencial.
| Aspecto | Chat Completions | API Responses |
|---|---|---|
| Estado | Legado | Principal (recomendado) |
| Gestión del estado | Sin estado (enviar historial) | Con estado (previous_response_id) |
| Almacenamiento en servidor | No | Sí (30 días con store: true) |
| Conversación | Array de mensajes | Encadenada por ID |
| Herramientas del servidor | Solo llamada a funciones | web_search, x_search, code_interpreter, functions |
| Razonamiento cifrado | No | Sí (encrypted_content) |
| Nuevas funcionalidades | No prioritarias | Prioritarias |
| Compatibilidad con OpenAI | Total | Parcial |
Gestión del estado: la diferencia fundamental
Chat Completions: tú gestionas el historial
Con cada solicitud, debes reenviar toda la conversación:
# Chat Completions — reenviar todo cada vez
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "Eres un asistente útil."},
{"role": "user", "content": "Hola, me llamo Alice."},
{"role": "assistant", "content": "¡Hola Alice! ¿En qué puedo ayudarte?"},
{"role": "user", "content": "¿Cuál es mi nombre de pila?"}
]
)
API Responses: el servidor gestiona el historial
Con la API Responses, basta un identificador sencillo para continuar una conversación:
# API Responses — solo el ID de la respuesta anterior
response1 = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Hola, me llamo Alice."
)
response2 = client.responses.create(
model="grok-4.20-0309-reasoning",
input="¿Cuál es mi nombre de pila?",
previous_response_id=response1.id
)
El servidor mantiene el contexto y reconstruye el historial automáticamente. No pagas menos tokens (el historial se factura igual), pero simplificas tu código y reduces el tamaño de tus solicitudes.
Herramientas y funcionalidades exclusivas
La API Responses da acceso a herramientas del servidor que Chat Completions no ofrece:
web_search: búsqueda web en tiempo realx_search: búsqueda dentro de publicaciones de X (Twitter)code_interpreter: ejecución de código Python en el servidor
Estas herramientas se integran directamente en la solicitud:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="¿Cuáles son las últimas noticias sobre IA?",
tools=[{"type": "web_search"}]
)
Chat Completions admite la llamada a funciones (herramientas definidas por el desarrollador), pero no estas herramientas del servidor gestionadas por xAI.
¿Cuándo usar Chat Completions?
Chat Completions sigue siendo la opción correcta en varios escenarios:
- Migración desde OpenAI: tu código existente funciona sin grandes modificaciones
- Multi-proveedor: quieres cambiar entre OpenAI, Anthropic y xAI con el mismo código
- Frameworks de terceros: LangChain, LlamaIndex, Haystack y la mayoría de los frameworks usan el formato Chat Completions
- Control total: quieres gestionar el historial tú mismo (resumen, filtrado, modificación)
¿Cuándo usar la API Responses?
La API Responses es preferible para:
- Nuevos proyectos: beneficiarse de las últimas funcionalidades desde el inicio
- Herramientas del servidor: necesidad de búsqueda web, ejecución de código o búsqueda en X
- Conversaciones largas: no hace falta reenviar el historial en cada solicitud
- Razonamiento cifrado: acceso al contenido de razonamiento para la continuidad entre solicitudes
Puntos clave
- Chat Completions es sin estado (tú gestionas el historial); la API Responses es con estado (lo gestiona el servidor)
- La API Responses ofrece herramientas exclusivas del servidor: web_search, x_search, code_interpreter
- Chat Completions tiene compatibilidad total con OpenAI; la API Responses es específica de xAI
- Ambos puntos finales facturan el historial completo de la conversación
- Usa Chat Completions para compatibilidad y la API Responses para nuevas funcionalidades