Formato de respuesta: id, choices y finish_reason
En esta página
Actualizado el 3 de noviembre de 2026 según la referencia de la API Chat Completions de xAI: solo
stop,lengthy, en modo streaming,end_turnonullestán documentados parafinish_reason; los valorestool_callsycontent_filterde la versión anterior no aparecen listados, y las llamadas a herramientas se detectan mediantemessage.tool_calls.max_tokensestá obsoleto en favor demax_completion_tokens. Fuente: Chat Completions.
Anatomía de una respuesta de Chat Completions
Cada llamada al punto final (endpoint) de Chat Completions devuelve un objeto JSON estructurado con campos estandarizados. Comprender esta estructura es esencial para extraer datos correctamente, gestionar casos límite y depurar tus integraciones.
Estructura completa de la respuesta
Aquí tienes un ejemplo de una respuesta típica devuelta por la API:
{
"id": "chatcmpl-abc123xyz",
"object": "chat.completion",
"created": 1712345678,
"model": "grok-4.20-0309-reasoning",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Deep learning is a branch of machine learning..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 156,
"total_tokens": 198
},
"system_fingerprint": "fp_abc123"
}
Campos de nivel superior
id: Identificador único de la finalización (formatochatcmpl-...). Útil para el seguimiento y la depuración.object: Siempre"chat.completion". Te permite distinguir este tipo de respuesta de otros puntos finales.created: Marca de tiempo Unix del momento en que se creó la respuesta.model: El modelo que generó la respuesta. Puede diferir ligeramente del modelo solicitado si utilizas un alias.choices: Matriz que contiene la respuesta o respuestas generadas.usage: Contadores de tokens para la facturación.system_fingerprint: Huella de la configuración del sistema utilizada.
La matriz choices
El campo choices es una matriz que suele contener un único elemento (índice 0). Cada elemento contiene:
index: Posición en la matriz (comienza en 0)message: Objeto conrole(siempre"assistant") ycontent(el texto generado)finish_reason: La razón por la que se detuvo la generación
Para extraer la respuesta de texto:
# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;
Valores de finish_reason
El campo finish_reason indica por qué el modelo dejó de generar texto:
stop
"finish_reason": "stop"
El modelo finalizó su respuesta de forma natural. Este es el caso más común y deseable: el modelo ha dicho todo lo que tenía que decir.
length
"finish_reason": "length"
La generación se detuvo porque se alcanzó el límite de salida: max_completion_tokens, que sustituye al ahora obsoleto max_tokens, y que cuenta solo la respuesta visible. Por tanto, la respuesta está truncada: aumenta el límite o reinicia una solicitud de continuación.
end_turn o null en streaming
En modo streaming, cada fragmento intermedio lleva "end_turn" o null en finish_reason; solo el fragmento final indica la razón de la parada.
Lo que la referencia no documenta
La referencia de la API de xAI documenta solo estos valores. No menciona ni content_filter ni el valor devuelto durante una llamada a herramienta: para saber si el modelo solicita una herramienta, comprueba la presencia de message.tool_calls en lugar del valor de finish_reason.
Gestión de diferentes casos
En producción, debes comprobar finish_reason para adaptar tu comportamiento:
choice = response.choices[0]
if choice.message.tool_calls:
# El modelo quiere llamar a una o varias herramientas
for tool_call in choice.message.tool_calls:
print(f"Herramienta solicitada: {tool_call.function.name}")
elif choice.finish_reason == "length":
# Respuesta truncada: notifica al usuario o continúa
print(choice.message.content)
print("[Respuesta truncada: aumenta max_completion_tokens]")
else:
# Respuesta completa
print(choice.message.content)
Puntos clave
- La respuesta contiene un
idúnico, una matrizchoicesy un objetousage - El texto generado se encuentra en
choices[0].message.content finish_reasonindica por qué se detuvo la generación: la referencia documentastopylength(yend_turnonullen streaming)- Comprueba
finish_reasonpara detectar respuestas truncadas ymessage.tool_callspara llamadas a herramientas - El
system_fingerprintidentifica la configuración del sistema utilizada para la generación