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

Chat Completions frente a Responses API: comparación

Lección 11 de 12 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Dos puntos finales, dos filosofías
  2. Gestión del estado: la diferencia fundamental
  3. Herramientas y funcionalidades exclusivas
  4. ¿Cuándo usar Chat Completions?
  5. ¿Cuándo usar la API Responses?
  6. Puntos clave

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 real
  • x_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