max_completion_tokens et budget de tokens

Leçon réécrite le 3 novembre 2026 d’après la référence de l’API xAI (Chat Completions et Responses), le guide Reasoning et les bonnes pratiques de xAI : max_completion_tokens et max_output_tokens ne plafonnent que la réponse visible — les tokens de raisonnement et d’appels de fonction n’y comptent pas —, et valent 128 000 par défaut. L’ancienne version affirmait l’inverse et dimensionnait le plafond en fonction du raisonnement ; elle réglait aussi un effort sur grok-4.20-0309-reasoning, qui n’en accepte pas. Sources : Chat Completions · Responses · Reasoning.

Ce que le plafond limite vraiment

Sur un modèle de raisonnement, on pourrait croire que le plafond de sortie partage son budget entre la réflexion et la réponse. Ce n’est pas le cas chez xAI. La référence de l’API est explicite : max_completion_tokens (Chat Completions) et max_output_tokens (Responses API) ne s’appliquent qu’aux tokens de sortie visibles ; les tokens de raisonnement et ceux des appels de fonction n’y sont pas comptés.

max_completion_tokens → réponse visible uniquement
tokens de raisonnement → hors plafond, réglés par l'effort

Sans valeur, ce plafond vaut 128 000 tokens. Quant à l’ancien max_tokens, il est déprécié au profit de max_completion_tokens.

Piloter le raisonnement : l’effort, pas le plafond

Puisque le plafond ne touche pas la réflexion, c’est l’effort qui en règle la quantité. Sur grok-4.7, grok-4.6 et grok-4.5, le paramètre s’appelle reasoning_effort en Chat Completions et reasoning.effort dans la Responses API ; il vaut high par défaut, accepte low et medium, et xhigh à partir de Grok 4.6. Le raisonnement ne se désactive pas.

grok-4.20-0309-reasoning, lui, ne prend pas ce paramètre : il raisonne toujours, et c’est sa variante grok-4.20-0309-non-reasoning qui répond sans réfléchir. Sur grok-4.20-multi-agent, enfin, l’effort ne règle pas la profondeur de réflexion mais le nombre d’agents mobilisés (4 ou 16).

response = client.chat.completions.create(
    model="grok-4.7",
    reasoning_effort="low",  # tâche simple : peu de réflexion
    messages=[{"role": "user", "content": "Classe ce ticket : facturation, accès ou bug ?"}],
)
print(response.usage.completion_tokens_details.reasoning_tokens)

Le nombre de tokens de raisonnement se lit dans l’usage de la réponse : usage.completion_tokens_details.reasoning_tokens en Chat Completions, usage.output_tokens_details.reasoning_tokens dans la Responses API. Ils font partie des tokens facturés : c’est donc l’effort, et non le plafond de sortie, qui pèse sur ce poste de la facture.

Dimensionner le plafond de sortie

Le plafond ne sert qu’à borner la longueur de la réponse elle-même. Les bonnes pratiques de xAI donnent une règle simple : fixez-le au-dessus de la plus longue réponse que vous attendez, ou laissez sa valeur par défaut de 128 000 tokens. Un plafond trop serré coupe la réponse visible, quel que soit l’effort de raisonnement.

Détection de troncature

Quand la réponse visible atteint le plafond, Chat Completions renvoie "length" dans finish_reason au lieu de "stop", et la Responses API un statut incomplete. Vous pouvez détecter cette situation et relancer avec un plafond plus haut :

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 réponse visible a été coupée : relancer avec un plafond plus élevé
    response = client.chat.completions.create(
        model="grok-4.7",
        messages=[{"role": "user", "content": question}],
        max_completion_tokens=8000,
    )

Ne pas confondre avec la limite de contexte

Le plafond de sortie est indépendant de la fenêtre de contexte du modèle — 500 000 tokens pour grok-4.7, 1 million pour grok-4.20-0309-reasoning —, qui borne l’ensemble de la conversation. Et une requête de raisonnement profond peut prendre plusieurs minutes : xAI conseille de laisser au moins 900 secondes à chaque requête et de préférer le streaming.

Points clés à retenir

• max_completion_tokens et max_output_tokens ne plafonnent que la réponse visible : le raisonnement n’y compte pas
• Sans valeur, le plafond de sortie vaut 128 000 tokens ; max_tokens est déprécié
• La quantité de raisonnement se règle par l’effort (reasoning_effort ou reasoning.effort) sur grok-4.5 à 4.7 ; grok-4.20-0309-reasoning n’en a pas
• Les tokens de raisonnement se lisent dans l’usage et font partie de la facture
• Une réponse coupée se détecte par finish_reason: "length" ou le statut incomplete