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

max_completion_tokens y presupuesto de tokens

Lección 10 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Qué limita realmente el tope
  2. Dirigir el razonamiento: esfuerzo, no el tope
  3. Dimensionamiento del tope de salida
  4. Detección del truncamiento
  5. No confundir con el límite de contexto
  6. Puntos clave

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_tokens y max_output_tokens limitan ú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 en grok-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 esperadaTope de salida razonable
Una etiqueta, un númerounas pocas decenas de tokens
Un párrafode 500 a 1.000 tokens
Un informe estructuradovarios miles de tokens
Sin idea precisael 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_tokens y max_output_tokens limitan 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_tokens está obsoleto
  • La cantidad de razonamiento se define mediante el esfuerzo (reasoning_effort o reasoning.effort) en grok-4.5 a 4.7; grok-4.20-0309-reasoning no 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 estado incomplete