Utilização de tokens e reasoning_tokens
Nesta página
Atualizado a 3 de novembro de 2026. Com base na referência da API Chat Completions da xAI:
max_tokensestá obsoleto em favor demax_completion_tokens, que limita apenas a resposta visível. Fonte: Chat Completions.
Compreenda a faturação de tokens
Cada pedido à API Chat Completions é faturado com base no número de tokens consumidos. O objeto usage na resposta fornece uma contagem exata, essencial para monitorizar custos, otimizar prompts e dimensionar os seus orçamentos de API.
O objeto usage padrão
Eis a estrutura do objeto usage devolvido com cada resposta:
{
"usage": {
"prompt_tokens": 127,
"completion_tokens": 342,
"total_tokens": 469
}
}
Os três contadores básicos
prompt_tokens: número de tokens no seu pedido (mensagem de sistema + histórico + nova mensagem). Este é o lado de «entrada» da faturação.completion_tokens: número de tokens gerados pelo modelo na sua resposta. Este é o lado de «saída».total_tokens: soma dos dois anteriores. Este é o total faturado para este pedido.
Impacto do histórico nos custos
Como o endpoint é stateless (sem estado), o histórico é enviado com cada pedido. Isto significa que prompt_tokens aumenta a cada troca:
Troca 1 : prompt_tokens = 50 (sistema + 1 mensagem de utilizador)
Troca 2 : prompt_tokens = 150 (sistema + 2 utilizador + 1 assistente)
Troca 3 : prompt_tokens = 300 (sistema + 3 utilizador + 2 assistente)
Troca 10: prompt_tokens = 1500 (sistema + 10 utilizador + 9 assistente)
Em conversas longas, o custo do histórico pode rapidamente exceder o custo da própria resposta.
reasoning_tokens: específico de modelos de raciocínio
Os modelos Grok com capacidades de raciocínio (como grok-4.20-0309-reasoning) adicionam um campo extra ao objeto usage:
{
"usage": {
"prompt_tokens": 127,
"completion_tokens": 892,
"total_tokens": 1019,
"completion_tokens_details": {
"reasoning_tokens": 550
}
}
}
O que são reasoning_tokens?
reasoning_tokens representam os tokens utilizados pelo modelo para o seu raciocínio interno — o «pensamento» que ocorre antes de produzir a resposta final. Estes tokens são gerados, mas não são visíveis no campo content da resposta.
No exemplo acima:
- O modelo gerou 892 tokens no total (
completion_tokens) - Incluindo 550 tokens de raciocínio interno (
reasoning_tokens) - Restando 342 tokens de resposta visível (892 - 550)
Porque é que isto importa
Os tokens de raciocínio são faturados como tokens de conclusão normais. Para um modelo de raciocínio, a resposta visível pode representar apenas uma fração do custo total:
usage = response.usage
visible_tokens = usage.completion_tokens - usage.completion_tokens_details.reasoning_tokens
reasoning_tokens = usage.completion_tokens_details.reasoning_tokens
print(f"Visible tokens: {visible_tokens}")
print(f"Reasoning tokens: {reasoning_tokens}")
print(f"Reasoning ratio: {reasoning_tokens / usage.completion_tokens * 100:.0f}%")
Não é incomum que os tokens de raciocínio representem 50 a 80% dos tokens de conclusão em perguntas complexas.
Estratégias de otimização de custos
Reduzir prompt_tokens
- Resuma o histórico: em vez de enviar toda a conversa, resuma as trocas mais antigas
- Limite a mensagem de sistema: um prompt de sistema de 500 tokens raramente é necessário — aponte para 100–200 tokens
- Filtre mensagens: envie apenas as trocas relevantes para a pergunta atual
Controlar completion_tokens
- Use
max_completion_tokens(max_tokensestá obsoleto): limita a resposta visível, não o raciocínio - Especifique o formato: «Responda em 3 frases» custa menos do que «Explique em detalhe»
- Escolha o modelo certo: um modelo sem raciocínio é menos dispendioso se a tarefa não exigir pensamento complexo
Monitorizar custos em produção
import json
def log_usage(response, requete_id: str):
usage = response.usage
log = {
"id": requete_id,
"prompt": usage.prompt_tokens,
"completion": usage.completion_tokens,
"total": usage.total_tokens,
}
if hasattr(usage, "completion_tokens_details") and usage.completion_tokens_details:
log["reasoning"] = usage.completion_tokens_details.reasoning_tokens
print(json.dumps(log))
Pontos-chave
- O objeto
usagecontémprompt_tokens,completion_tokensetotal_tokens prompt_tokensaumenta a cada troca devido ao histórico enviado- Modelos de raciocínio adicionam
reasoning_tokensemcompletion_tokens_details - Tokens de raciocínio são faturados à taxa de saída, mas são invisíveis na resposta — a sua quota-parte do custo depende da tarefa e do esforço, por isso meça-a
- Otimize resumindo o histórico, ajustando o esforço de raciocínio, limitando
max_completion_tokense escolhendo o modelo adequado