O que são tokens no Claude e custos de uso

O que são tokens no Claude?

Um token é a unidade de texto que o Claude lê e escreve: um fragmento de palavra, aproximadamente 3.5 caracteres em inglês. Esse valor vem do glossário da Anthropic. O total supera um token por palavra quando espaços e pontuações são contados; portanto, mil palavras de prosa resultam em mais de 1.300 tokens. O código consome mais tokens por linha: chaves, operadores, underscores e indentação dividem-se em mais tokens por caractere do que o inglês. Um arquivo de código-fonte com algumas centenas de linhas costuma pesar vários milhares de tokens. Se o agente decidir ler um arquivo de 2.000 linhas, o custo será de cinco dígitos em tokens antes mesmo de qualquer linha de código novo ser escrita.

Dois pontos sobre tokenizadores confundem os usuários. Primeiro, eles são específicos de cada modelo. Em julho de 2026, o Opus 4.7 e versões posteriores, o Sonnet 5 e o Fable 5 utilizam um tokenizador mais recente que produz cerca de 30% mais tokens para o mesmo texto do que os modelos Claude anteriores (o aumento exato varia conforme o conteúdo). Isso altera o orçamento de tokens, embora os preços por token não tenham subido junto. Segundo, o tiktoken, a biblioteca usada em quase todos os posts de blogs, é o tokenizador da OpenAI e subestima a contagem do Claude em cerca de 15–20% em textos comuns, e ainda mais em código. A única contagem confiável é o endpoint count_tokens, detalhado abaixo.

Por que sua sessão de codificação custa o que custa

Cada fatura do Claude, seja uma nota fiscal de API ou um limite de assinatura, depende de uma única métrica: tokens de entrada e tokens de saída. A página de preços parece simples: determinado valor em dólares por milhão de tokens de entrada e outro valor por milhão de saída. O que ela não informa é que, em uma sessão de codificação com agentes, o consumo de entrada é muito maior do que o intuitivo, pois toda a conversa é reenviada em cada turno. Eu vendo infraestrutura tarifada há quinze anos, e os tokens são a primeira métrica que vejo onde a maioria dos clientes realmente não sabe o que está elevando o custo. Esta é a lição sobre leitura de métricas: o que conta como entrada e saída em uma sessão de agente, por que o loop de reenvio é tão caro, por que o prompt caching altera o cálculo e quais variáveis realmente alteram o valor final.

Tudo é input: o que o medidor realmente conta

As pessoas assumem que pagam pelo código que o Claude escreve. Em uma sessão de agente, esse é apenas um pequeno item na fatura. Os tokens de input — que possuem a tarifa mais barata, mas um volume muito maior — incluem:

• O system prompt. As instruções de harness do próprio Claude Code, além dos seus arquivos CLAUDE.md e de memória, carregados no início da sessão e presentes em cada requisição subsequente.
• Definições de ferramentas (tool definitions). Cada schema de ferramenta que o agente pode chamar. Cada MCP server que você conecta adiciona a esse overhead fixo — embora o Claude Code agora adie as definições completas de ferramentas MCP por padrão, mantendo apenas os nomes das ferramentas no contexto até que uma ferramenta seja usada pela primeira vez, o que reduz, mas não elimina, o custo.
• Cada arquivo que o agente lê. Um Read de um arquivo de código fonte coloca o arquivo inteiro no contexto, e ele permanece lá.
• Cada resultado de ferramenta. Execuções de testes, saída do grep, logs do terminal, logs de build — tudo retorna como tokens de input. Uma suíte de testes que falha e imprime 8.000 linhas acaba de cobrar o equivalente a um livro pequeno.
• Toda a conversa até o momento, reenviada em cada turno. Este item merece sua própria seção.

O custo crescente do reenvio de dados

A Claude API é stateless. Ela não armazena o estado da sua sessão entre as requisições — nada é armazenado. Assim, no turno 2, o cliente envia o turno 1, a resposta anterior e sua nova mensagem. No turno 50, o cliente reenvia os turnos 1 até 49 — cada leitura de arquivo, cada resultado de tool e cada diff — além do turno 50. O modelo relê todo o histórico a cada requisição, e cada um desses tokens relidos é cobrado como input.

A consequência: o custo por turno cresce de forma aproximadamente linear conforme o tamanho da sessão, e o custo total da sessão cresce de forma aproximadamente quadrática. Uma mensagem que custou meio centavo no turno 3 pode custar vinte vezes esse valor no turno 60, para a mesma pergunta de uma linha, porque ela carrega o peso de sessenta turnos. Este é o principal motivo de chamados sobre "por que minha fatura foi tão alta", e não é uma característica específica da Claude — todo produto de LLM que parece stateful é, na verdade, uma API stateless com um loop de reenvio por baixo.

Output: o que você vê, mais o processamento interno

Tokens de output são os mais caros — cinco vezes a taxa de input na linha atual ($5/$25 no Opus 4.8, $3/$15 no Sonnet 5, $1/$5 no Haiku 4.5, em julho de 2026). O output inclui o texto e o código gerados pelo Claude, além dos thinking tokens: o raciocínio interno que o modelo realiza antes de responder. Dois fatos são importantes aqui. O "thinking" é cobrado pelas taxas de output e conta para o max_tokens — uma resposta de API que termina com stop_reason: "max_tokens" e uma resposta truncada geralmente significam que o processamento consumiu o orçamento antes da resposta. E nos modelos atuais o resumo do raciocínio pode não ser exibido — Opus 4.8, Sonnet 5 e Fable 5 o omitem por padrão — mas o processamento ocorreu e será cobrado. O que é invisível não é de graça.

O Claude Code habilita o "extended thinking" por padrão porque ele melhora comprovadamente trabalhos de múltiplas etapas, e o orçamento padrão pode chegar a dezenas de milhares de tokens por requisição. Em tarefas mais simples você pode reduzir esse valor: diminua o nível de esforço com /effort ou em /model, ou ajuste as configurações de "thinking" em /config. Esta é uma alavanca de custo real, não uma superstição.

O prompt caching altera os cálculos

O prompt caching evita que o loop de reenvio gere custos excessivos. A API pode armazenar em cache um prefixo estável do seu prompt — system prompt, definições de ferramentas, histórico da conversa — e entregá-lo na próxima requisição por uma fração do preço. A partir de julho de 2026, os multiplicadores são: um write de cache custa 1.25× a taxa base de input (2× para a variante de 1 hora), e um read de cache custa 0.1×. Escritas são premium; leituras possuem 90% de desconto. Um único read já compensa o custo adicional do write de 5 minutos.

O Claude Code gerencia o cache para você e, em uma sessão estável, quase todo o reenvio de dados é servido pelo cache. Porém, o cache padrão expira após cinco minutos do último uso. Se você se afastar por um tempo maior, o cache expirará e todo o prefixo acumulado será reescrito a 1.25× em vez de lido a 0.1×. Em uma sessão de 150K-tokens, uma única execução a frio custa mais que uma dúzia de execuções a quente. Este é o resultado contraintuitivo que você deve memorizar: um ritmo de pausa e retomada pode custar mais que o trabalho contínuo, pois cada intervalo após o TTL converte sua próxima interação de um read barato em um re-write caro. Trabalhe em blocos; não envie mensagens de uma sessão enorme a cada dez minutos.

Se você estiver chamando a API a partir de sua própria aplicação em um VPS, você não recebe esses benefícios automaticamente — o erro clássico é interpolar um timestamp ou request ID no system prompt, o que altera os bytes do prefixo em cada requisição e desativa o cache silenciosamente. O sinal de que isso ocorre é o usage.cache_read_input_tokens permanecendo em zero em chamadas visualmente idênticas.

A fórmula, com um exemplo prático

Ignore qualquer afirmação de que "uma sessão custa $X". O custo das sessões varia em duas ordens de magnitude. O que é constante é a fórmula:

turn cost = (uncached input      x base input price)
          + (cache writes        x 1.25 x base input price)
          + (cache reads         x 0.10 x base input price)
          + (output incl. thinking x output price)

session cost = sum over all turns

Exemplo prático no Claude Opus 4.8, que em julho de 2026 custa $5 por milhão de tokens de input e $25 por milhão de output. Um turno de meio de sessão com 80.000 tokens de contexto acumulado: 75.000 lidos do cache, 3.000 novos escritos, 2.000 de input novo não em cache, 1.500 tokens de output incluindo thinking.

• Cache reads: 75.000 × $0.50/M = $0.0375
• Cache writes: 3.000 × $6.25/M = $0.019
• Uncached input: 2.000 × $5/M = $0.010
• Output: 1.500 × $25/M = $0.0375

Cerca de $0.10 por turno; cinquenta turnos iguais custariam cerca de $5. Agora, o mesmo turno após o cache expirar: os 80.000 tokens totais reescritos a $6.25/M resultam em $0.50 antes do output — aproximadamente cinco vezes o valor do turno com cache para o mesmo trabalho. Essa diferença resume o conceito de caching em um único número.

Para calibração, não para previsão: os valores publicados pela Anthropic para implementações enterprise do Claude Code, em julho de 2026, apresentam uma média de $13 por desenvolvedor por dia ativo — $150–250 por mês — com 90% dos usuários gastando menos de $30 por dia. O seu custo depende da escolha do modelo, da higiene da sessão e do tamanho do codebase, que é exatamente o motivo pelo qual os controles abaixo são importantes.

Visualizando seu uso

No Claude Code, o comando é /usage (/cost ainda funciona — é um alias). O bloco Session no topo mostra estatísticas de tokens e uma estimativa de custo calculada localmente para a sessão atual; em planos de assinatura, a mesma tela exibe as barras de limite do seu plano e o detalhamento de uso recente por skills, subagents, plugins e servidores MCP individuais. Para faturamento oficial em contas de API, a página de uso no Claude Console é a fonte de verdade — o valor no CLI é apenas uma estimativa. O comando /context gera uma grade colorida de o que está ocupando a janela de contexto — system prompt, tools, definições de MCP, arquivos e histórico — e é a forma mais rápida de identificar um CLAUDE.md sobrecarregado ou um servidor MCP com excesso de mensagens; use all para expandir o detalhamento completo por item.

Via API, cada resposta informa exatamente o que ocorreu:

response = client.messages.create(model="claude-sonnet-5", max_tokens=2048,
                                  messages=messages)
u = response.usage
total_prompt = u.input_tokens + u.cache_creation_input_tokens + u.cache_read_input_tokens
print(f"uncached={u.input_tokens} written={u.cache_creation_input_tokens} "
      f"read={u.cache_read_input_tokens} output={u.output_tokens}")

Note que input_tokens representa apenas o restante sem cache — o tamanho real do prompt é a soma de todos os três campos de entrada. Um agente que rodou por uma hora mostrando input_tokens: 4000 não é barato; os outros 200.000 tokens foram servidos via cache. Para estimar antes de enviar, use o endpoint de contagem de tokens — a chamada é gratuita, possui seu próprio rate limit e conta usando o tokenizer do modelo que você especificar (considere o resultado como uma estimativa próxima; o faturamento reflete a requisição real):

count = client.messages.count_tokens(model="claude-sonnet-5",
                                     messages=[{"role": "user", "content": big_file}])
print(count.input_tokens)

Nunca use tiktoken, pelo motivo acima.

Planos de assinatura versus pay-as-you-go

A mecânica descrita neste guia é idêntica em todos os casos; apenas o faturamento muda. Com uma API key, a Anthropic cobra no modelo pay-as-you-go, por token, conforme as taxas publicadas — todos os valores acima representam dinheiro real. Em uma assinatura do Claude (Pro, Max, Team, Enterprise), o uso do Claude Code consome a cota incluída no seu plano: a partir de julho de 2026, trata-se de uma janela de sessão rotativa de cinco horas mais uma janela semanal, compartilhada entre os modelos e com o chat do claude.ai; o valor de /usage dólares é apenas informativo e não uma fatura. Se esgotar uma janela, você verá as mensagens "You've hit your session limit" ou "You've hit your weekly limit" com um horário de reset — alternar modelos com /model não restaurará o acesso, pois as janelas são compartilhadas entre os modelos. Os planos podem habilitar opcionalmente créditos de uso, gerenciados via /usage-credits, para comprar uso além do limite. Eu não listarei as cotas dos planos: elas são os números mais voláteis deste tópico, portanto, verifique claude.com/pricing e suas próprias barras de /usage. A mecânica de tokens ainda é relevante em uma assinatura — uma sessão ineficiente consome sua janela da mesma forma que consumiria dólares. Para detalhes sobre assinaturas, veja qual plano do Claude se adequa ao seu uso.

As alavancas que realmente funcionam

• Limite o escopo de leitura do agente. "Fix the validation bug in auth.py" lê apenas um arquivo; "improve this codebase" lê quarenta. Mantenha o CLAUDE.md enxuto — ele é carregado em todas as sessões, então use apenas o essencial — e mova instruções específicas de workflow para skills que carregam sob demanda.
• Clareza e concisão. /clear entre tarefas não relacionadas — o contexto obsoleto é reenviado e cobrado novamente em cada mensagem subsequente. Dentro de uma única tarefa longa, o /compact Focus on the failing tests and the diff resume o histórico para evitar o crescimento quadrático de tokens.
• Escolha o tamanho correto do modelo. Sonnet para a maioria dos códigos custa $2/$10 por milhão de tokens no preço de introdução em julho de 2026 ($3/$15 padrão, contra Opus a $5/$25), enquanto o Haiku a $1/$5 é a ferramenta ideal para subagentes mecânicos como triagem de logs. O /model alterna durante a sessão.
• Pré-filtre saídas verbosas. Um hook que faz grep em um test run para isolar apenas as falhas antes do Claude processar transforma 20.000 tokens de resultado de ferramenta em 300, e isso ocorre em cada reenvio futuro desse turno.
• Use batch para o que não é interativo. Para seus próprios pipelines de API — classificação, revisão em massa, jobs noturnos — a Batches API executa os mesmos modelos com 50% de desconto em troca de entrega assíncrona.
• Respeite o cache. Trabalhe em períodos contínuos. Uma sessão do Claude Code em tmux em um VPS desconectada não custa nada enquanto ociosa — tokens só são gastos quando um turno é executado — mas o tempo ocioso faz você perder o cache aquecido, e o próximo turno pagará pelo reprocessamento.

FAQ

Quantos tokens uma sessão de codificação no Claude Code utiliza?

Não existe um número fixo — um único turno de meio de sessão geralmente carrega dezenas de milhares de tokens de prompt conforme arquivos e histórico se acumulam. Uma sessão de trabalho chega a milhões de tokens, sendo a maioria servida via cache a um décimo da taxa base. Para calibração, os números publicados pela Anthropic para empresas em julho de 2026 mostram uma média de $13 por desenvolvedor por dia ativo, com 90% dos usuários abaixo de $30. Execute /usage em sua própria sessão; cinco minutos de monitoramento superam qualquer média publicada.

Tokens de raciocínio (thinking tokens) custam dinheiro mesmo quando eu não os vejo?

Sim. Thinking tokens são faturados como tokens de saída — a taxa mais cara — e contam para max_tokens. Os modelos atuais os faturam mesmo quando a interface omite o resumo do raciocínio da exibição. Se uma resposta for truncada com stop_reason: "max_tokens" antes de terminar a resposta visível, o raciocínio provavelmente consumiu o orçamento. No Claude Code, reduza o nível de esforço com /effort para tarefas que não exigem raciocínio profundo.

Por que uma sessão longa do Claude Code fica mais cara por mensagem?

Porque a API é stateless: cada turno reenvia toda a conversa — cada leitura de arquivo, resultado de ferramenta e troca anterior — como input faturável. Assim, o turno 50 carrega os turnos 1 ao 49 como carga. O prompt caching serve o prefixo repetido a cerca de um décimo do preço base de input, mas o prefixo continua crescendo. Qualquer intervalo ocioso além do TTL do cache transforma o próximo turno em uma reescrita de preço total. /compact reduz o histórico; /clear o reseta.

Como verifico meu uso de tokens e custo no Claude?

No Claude Code, /usage exibe estatísticas de tokens da sessão, uma estimativa de custo local e barras de limite de plano em assinaturas (/cost é um alias); /context mostra o que está preenchendo a janela. Para faturamento oficial da API, use a página de usage no Claude Console. Em seu próprio código, leia response.usage — somar input_tokens, cache_creation_input_tokens e cache_read_input_tokens fornece o tamanho real do prompt — e faça estimativas antecipadas com o endpoint count_tokens, nunca com o tiktoken.