Contagem de Tokens de Raciocínio
Nesta página
Lição reescrita em 3 de novembro de 2026 com base na referência da API xAI (Chat Completions e Responses), no guia Reasoning e no exemplo Reasoning Effort Evals do cookbook: na xAI,
completion_tokens(ououtput_tokens) conta apenas a resposta visível, o raciocínio é contado separadamente e o total soma os três; o limite de saída não limita o raciocínio. A versão anterior afirmava o oposto, utilizava campos de Chat Completions numa resposta da API Responses, definia o esforço emgrok-4.20-0309-reasoning(que não o aceita) e apresentava uma captura de ecrã que não correspondia à API; estes elementos foram corrigidos ou removidos. Fontes: Chat Completions · Responses · Reasoning Effort Evals.
Compreenda os tokens de raciocínio
Os modelos de raciocínio produzem dois tipos de tokens: os destinados à resposta visível e os relativos ao processo de pensamento interno do modelo. Compreender como a xAI os conta é essencial para dominar os seus custos e ler corretamente os seus painéis de controlo.
O objeto usage em Chat Completions
Cada resposta inclui um objeto usage que detalha o consumo. Eis o exemplo da referência da API Chat Completions da xAI:
{
"usage": {
"prompt_tokens": 32,
"completion_tokens": 9,
"total_tokens": 135,
"completion_tokens_details": {
"reasoning_tokens": 94
}
}
}
Neste exemplo:
- prompt_tokens (32): tokens na mensagem de entrada
- completion_tokens (9): tokens na resposta visível
- reasoning_tokens (94): tokens dedicados ao raciocínio interno
- total_tokens (135): a soma dos três, 32 + 9 + 94
O raciocínio não está, portanto, incluído em completion_tokens: é somado a este. Tenha cuidado se vier de outra API onde a convenção difere, ou se o seu painel calcular a resposta visível por subtração.
Aceder aos tokens de raciocínio no código
Na API Responses, a mesma informação possui nomes diferentes: input_tokens, output_tokens para a resposta visível e output_tokens_details.reasoning_tokens para o raciocínio.
response = client.responses.create(
model="grok-4.7",
input="Solve the integral of x^2 * e^x dx.",
reasoning={"effort": "high"},
)
visible_response = response.usage.output_tokens
reasoning = response.usage.output_tokens_details.reasoning_tokens
billed_output = visible_response + reasoning
print(f"Reasoning tokens: {reasoning}")
print(f"Response tokens: {visible_response}")
print(f"Reasoning share: {reasoning / billed_output * 100:.0f}%")
Define o esforço em grok-4.7, grok-4.6 e grok-4.5; o grok-4.20-0309-reasoning raciocina sempre, sem parâmetro de esforço.
Faturação à tarifa de saída
Os tokens de raciocínio são faturados à tarifa de tokens de saída, como lembra o exemplo Reasoning Effort Evals no cookbook da xAI. Para o grok-4.7 a 6 USD por milhão de tokens de saída (prompt inferior a 200.000 tokens), cada token de raciocínio custa o mesmo que um token de resposta.
O esforço pesa, portanto, na fatura, mas nem sempre tanto quanto possa imaginar. Neste mesmo exemplo, em trinta tickets de suporte curtos tratados pelo grok-4.7, os esforços medium, high e xhigh consumiram aproximadamente a mesma quantidade de raciocínio — cerca de 600 tokens por resposta —, enquanto o low consumiu cerca de 140 e custou metade, com pontuações todas entre 87% e 93%. Meça nos seus próprios dados antes de escolher.
Exemplo de cálculo de custos
# grok-4.7: $6.00/M output tokens (prompt < 200k)
cost_per_token = 6.00 / 1_000_000
reasoning = 600
visible_response = 350
billed_output = reasoning + visible_response # 950
cost = billed_output * cost_per_token
print(f"Output cost: ${cost:.4f}") # $0.0057
O papel de max_completion_tokens
O limite de saída — max_completion_tokens em Chat Completions, max_output_tokens na API Responses — aplica-se apenas à resposta visível: segundo a referência da API, os tokens de raciocínio e as chamadas de função não contam para este limite. Sem um valor definido, o padrão é 128.000 tokens. Para limitar o raciocínio, precisa de definir o esforço (lição 10).
{
"model": "grok-4.7",
"messages": [
{"role": "user", "content": "Explain special relativity."}
],
"reasoning_effort": "medium",
"max_completion_tokens": 2000
}
Preços verificados em 3 de novembro de 2026 — os preços alteram-se regularmente: antes de qualquer cálculo orçamental, consulte a tabela de preços atual na página oficial de modelos e preços da xAI.
Pontos-chave
- Os tokens de raciocínio encontram-se em
usage.completion_tokens_details.reasoning_tokens(Chat Completions) ouusage.output_tokens_details.reasoning_tokens(Responses) - Na xAI,
completion_tokenseoutput_tokenscontam apenas a resposta visível; o total soma a entrada, a resposta e o raciocínio - Os tokens de raciocínio são faturados à tarifa de saída
- O limite de saída restringe apenas a resposta visível; o esforço controla o raciocínio
- A diferença de custo entre esforços depende da tarefa: meça-a nos seus próprios dados