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

Formato de respuesta: id, choices y finish_reason

Lección 8 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Anatomía de una respuesta de Chat Completions
  2. Estructura completa de la respuesta
  3. La matriz choices
  4. Valores de finish_reason
  5. Gestión de diferentes casos
  6. Puntos clave

Actualizado el 3 de noviembre de 2026 según la referencia de la API Chat Completions de xAI: solo stop, length y, en modo streaming, end_turn o null están documentados para finish_reason; los valores tool_calls y content_filter de la versión anterior no aparecen listados, y las llamadas a herramientas se detectan mediante message.tool_calls. max_tokens está obsoleto en favor de max_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.

id
Identificador único
choices
Matriz de respuestas
usage
Contadores de tokens
system_fingerprint
Huella del sistema

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 (formato chatcmpl-...). Ú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 con role (siempre "assistant") y content (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 matriz choices y un objeto usage
  • El texto generado se encuentra en choices[0].message.content
  • finish_reason indica por qué se detuvo la generación: la referencia documenta stop y length (y end_turn o null en streaming)
  • Comprueba finish_reason para detectar respuestas truncadas y message.tool_calls para llamadas a herramientas
  • El system_fingerprint identifica la configuración del sistema utilizada para la generación