max_completion_tokens e orçamento de tokens
Nesta página
Lição reescrita a 3 de novembro de 2026 com base na referência da API da xAI (Chat Completions e Responses), no guia Reasoning e nas melhores práticas da xAI:
max_completion_tokensemax_output_tokenslimitam apenas a resposta visível — os tokens de raciocínio e os tokens de chamada de função não contam para este limite — e o valor padrão é 128.000. A versão anterior afirmava o oposto e dimensionava o limite com base no raciocínio; definia também um esforço paragrok-4.20-0309-reasoning, que não o aceita. Fontes: Chat Completions · Responses · Reasoning.
O que o limite realmente restringe
Num modelo de raciocínio, pode pensar que o limite de saída partilha o seu orçamento entre o pensamento e a resposta. Não é esse o caso na xAI. A referência da API é explícita: max_completion_tokens (Chat Completions) e max_output_tokens (Responses API) aplicam-se apenas aos tokens de saída visíveis; os tokens de raciocínio e os tokens de chamada de função não são contabilizados.
max_completion_tokens → apenas resposta visível
tokens de raciocínio → fora do limite, definidos pelo esforço
Sem um valor definido, este limite assume por padrão 128.000 tokens. Quanto ao antigo max_tokens, está obsoleto em favor de max_completion_tokens.
Orientar o raciocínio: esforço, não o limite
Uma vez que o limite não afeta o raciocínio, é o esforço que regula a quantidade. Em grok-4.7, grok-4.6 e grok-4.5, o parâmetro é reasoning_effort no Chat Completions e reasoning.effort na Responses API; o valor padrão é high, aceita low e medium, e xhigh a partir do Grok 4.6. O raciocínio não pode ser desativado.
grok-4.20-0309-reasoning não aceita este parâmetro: raciocina sempre, e a sua variante grok-4.20-0309-non-reasoning responde sem raciocínio. Finalmente, em grok-4.20-multi-agent, o esforço não define a profundidade do raciocínio, mas sim o número de agentes mobilizados (4 ou 16).
response = client.chat.completions.create(
model="grok-4.7",
reasoning_effort="low", # tarefa simples: pouco raciocínio
messages=[{"role": "user", "content": "Classify this ticket: billing, access, or bug?"}],
)
print(response.usage.completion_tokens_details.reasoning_tokens)
O número de tokens de raciocínio aparece no uso da resposta: usage.completion_tokens_details.reasoning_tokens no Chat Completions, usage.output_tokens_details.reasoning_tokens na Responses API. Estes tokens fazem parte dos tokens faturados: portanto, é o esforço, e não o limite de saída, que pesa nesta rubrica.
Dimensionar o limite de saída
O limite serve apenas para restringir o comprimento da própria resposta. As melhores práticas da xAI dão uma regra simples: defina-o acima da resposta mais longa que espera, ou deixe o seu valor padrão de 128.000 tokens. Um limite demasiado apertado corta a resposta visível, independentemente do esforço de raciocínio.
| Resposta esperada | Limite de saída razoável |
|---|---|
| Um rótulo, um número | algumas dezenas de tokens |
| Um parágrafo | 500 a 1.000 tokens |
| Um relatório estruturado | vários milhares de tokens |
| Sem ideia precisa | o valor padrão |
Detetar truncagem
Quando a resposta visível atinge o limite, o Chat Completions devolve "length" em finish_reason em vez de "stop", e a Responses API devolve um estado incomplete. Pode detetar esta situação e tentar novamente com um limite mais elevado:
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":
# A resposta visível foi cortada: tentar novamente com um limite mais elevado
response = client.chat.completions.create(
model="grok-4.7",
messages=[{"role": "user", "content": question}],
max_completion_tokens=8000,
)
Não confundir com o limite de contexto
O limite de saída é independente da janela de contexto do modelo — 500.000 tokens para grok-4.7, 1 milhão para grok-4.20-0309-reasoning — que limita toda a conversa. E um pedido de raciocínio profundo pode levar vários minutos: a xAI recomenda permitir pelo menos 900 segundos por pedido e preferir o streaming.
Pontos-chave
max_completion_tokensemax_output_tokenslimitam apenas a resposta visível: o raciocínio não conta para este limite- Sem um valor, o limite de saída assume por padrão 128.000 tokens;
max_tokensestá obsoleto - A quantidade de raciocínio é definida pelo esforço (
reasoning_effortoureasoning.effort) no grok-4.5 ao 4.7;grok-4.20-0309-reasoningnão possui isto - Os tokens de raciocínio aparecem no uso e fazem parte da faturação
- Uma resposta cortada é detetada por
finish_reason: "length"ou pelo estadoincomplete