max_completion_tokens y presupuesto de tokens
En esta página
Lección reescrita el 3 de noviembre de 2026 basándose en la referencia de la API de xAI (Chat Completions y Responses), la guía de Reasoning y las mejores prácticas de xAI:
max_completion_tokensymax_output_tokenslimitan únicamente la respuesta visible; los tokens de razonamiento y los de llamadas a funciones no cuentan para este límite, y el valor por defecto es de 128.000. La versión anterior afirmaba lo contrario y dimensionaba el límite en función del razonamiento; también establecía un esfuerzo engrok-4.20-0309-reasoning, modelo que no lo acepta. Fuentes: Chat Completions · Responses · Reasoning.
Qué limita realmente el tope
En un modelo de razonamiento, podrías pensar que el tope de salida comparte su presupuesto entre el pensamiento y la respuesta. No es así en xAI. La referencia de la API es explícita: max_completion_tokens (Chat Completions) y max_output_tokens (Responses API) se aplican solo a los tokens de salida visibles; los tokens de razonamiento y los de llamadas a funciones no se cuentan.
max_completion_tokens → solo respuesta visible
tokens de razonamiento → fuera del tope, definidos por el esfuerzo
Sin un valor especificado, este tope tiene un valor por defecto de 128.000 tokens. En cuanto al antiguo max_tokens, está obsoleto en favor de max_completion_tokens.
Dirigir el razonamiento: esfuerzo, no el tope
Dado que el tope no afecta al razonamiento, es el esfuerzo el que regula la cantidad. En grok-4.7, grok-4.6 y grok-4.5, el parámetro es reasoning_effort en Chat Completions y reasoning.effort en la Responses API; su valor por defecto es high, acepta low y medium, y xhigh a partir de Grok 4.6. El razonamiento no se puede desactivar.
grok-4.20-0309-reasoning no acepta este parámetro: siempre razona, y su variante grok-4.20-0309-non-reasoning responde sin razonamiento. Por último, en grok-4.20-multi-agent, el esfuerzo no establece la profundidad del razonamiento, sino el número de agentes movilizados (4 o 16).
response = client.chat.completions.create(
model="grok-4.7",
reasoning_effort="low", # tarea simple: poco razonamiento
messages=[{"role": "user", "content": "Clasifica este ticket: facturación, acceso o error?"}],
)
print(response.usage.completion_tokens_details.reasoning_tokens)
El número de tokens de razonamiento aparece en el uso de la respuesta: usage.completion_tokens_details.reasoning_tokens en Chat Completions, usage.output_tokens_details.reasoning_tokens en la Responses API. Forman parte de los tokens facturados: por tanto, es el esfuerzo, no el tope de salida, el que influye en esta partida.
Dimensionamiento del tope de salida
El tope sirve únicamente para acotar la longitud de la respuesta en sí misma. Las mejores prácticas de xAI ofrecen una regla sencilla: fíjalo por encima de la respuesta más larga que esperes, o deja su valor por defecto de 128.000 tokens. Un tope demasiado ajustado cortará la respuesta visible, independientemente del esfuerzo de razonamiento.
| Respuesta esperada | Tope de salida razonable |
|---|---|
| Una etiqueta, un número | unas pocas decenas de tokens |
| Un párrafo | de 500 a 1.000 tokens |
| Un informe estructurado | varios miles de tokens |
| Sin idea precisa | el valor por defecto |
Detección del truncamiento
Cuando la respuesta visible alcanza el tope, Chat Completions devuelve "length" en finish_reason en lugar de "stop", y la Responses API devuelve un estado incomplete. Puedes detectar esta situación y reintentar con un tope mayor:
response = client.chat.completions.create(
model="grok-4.7",
messages=[{"role": "user", "content": question}],
max_completion_tokens=2000,
)
if response.choices[0].finish_reason == "length":
# La respuesta visible se ha cortado: reintentar con un tope mayor
response = client.chat.completions.create(
model="grok-4.7",
messages=[{"role": "user", "content": question}],
max_completion_tokens=8000,
)
No confundir con el límite de contexto
El tope de salida es independiente de la ventana de contexto del modelo —500.000 tokens para grok-4.7, 1 millón para grok-4.20-0309-reasoning—, que acota toda la conversación. Además, una solicitud de razonamiento profundo puede tardar varios minutos: xAI recomienda permitir al menos 900 segundos por solicitud y preferir el streaming.
Puntos clave
max_completion_tokensymax_output_tokenslimitan solo la respuesta visible: el razonamiento no cuenta para este límite- Sin un valor, el tope de salida tiene un valor por defecto de 128.000 tokens;
max_tokensestá obsoleto - La cantidad de razonamiento se define mediante el esfuerzo (
reasoning_effortoreasoning.effort) en grok-4.5 a 4.7;grok-4.20-0309-reasoningno lo tiene - Los tokens de razonamiento aparecen en el uso y forman parte de la facturación
- Una respuesta cortada se detecta mediante
finish_reason: "length"o el estadoincomplete