Observabilidade de Tokens em Mini-Softwares

Seu mini-software de IA provavelmente já funciona, mas você sabe qual botão dele consome mais dinheiro? Na maioria dos projetos pequenos, a resposta é “não sei”: a fatura da API chega no fim do mês como um número só, e o resumo automático, o chat e o classificador aparecem misturados no mesmo total.

Os artigos anteriores desta série trataram de como gastar menos: cache de prompt, roteamento de modelos, busca por trechos, orçamento. Este aqui trata do passo anterior a todos eles, que é medir. Sem medição, otimizar é chute. Com ela, bastam algumas linhas de código para descobrir onde está o desperdício.

Vamos ver o que a própria API já entrega de graça, como montar um registro de consumo mínimo e como transformar esse registro em decisões dentro de um PWA.

O que a API já te conta (e o que ela estima antes),

Toda resposta da API de mensagens traz um objeto usage com os tokens de entrada e de saída daquela chamada, além dos contadores de cache quando você usa cache de prompt. Esse é o número que vira cobrança, então é o que vale guardar: não precisa estimar nada, a própria resposta já vem com o consumo real.

Para saber o custo antes de chamar, existe o endpoint POST /v1/messages/count_tokens. Segundo a documentação oficial, ele é gratuito, tem limite de requisições por minuto conforme o seu nível de uso e aceita os mesmos campos de uma chamada normal: prompt de sistema, mensagens, ferramentas, imagens e PDFs. O número devolvido é uma estimativa, que pode diferir um pouco do consumo real, e não considera cache.

Um detalhe que pega muita gente: a página avisa que modelos a partir da família 4.7 usam um tokenizador novo, que gera cerca de 30% mais tokens para o mesmo texto. Trocar de modelo, portanto, muda a contagem e não só o preço. Se você compara custos entre versões, compare tokens medidos em cada uma.

Para converter tokens em reais ou dólares, use a tabela oficial de preços. Na consulta de hoje (30/10/2026), o Claude Sonnet 5.5 custa US$ 2 por milhão de tokens de entrada e US$ 10 por milhão de saída. Uma chamada com 1.200 tokens de entrada e 300 de saída sai por cerca de US$ 0,0054; dez mil chamadas iguais, US$ 54. Confira os valores na página antes de fixar qualquer cálculo no código, pois eles mudam.

Um registro de consumo que cabe em uma tabela

O registro mínimo guarda, a cada chamada, quatro coisas: qual funcionalidade chamou, qual modelo respondeu, quantos tokens entraram e saíram e quanto custou. Em um PWA, isso pode ser uma tabela no seu backend ou até uma lista no IndexedDB para uso pessoal. O ponto central é gravar o campo usage logo após a resposta, junto com um rótulo da funcionalidade (por exemplo resumo_ficha ou chat_suporte), nunca depois.

A tabela abaixo é um exemplo hipotético, com custos calculados pelos preços de hoje (Sonnet 5.5: US$ 2 entrada / US$ 10 saída por milhão; Haiku 5.5, para prompts de até 100 mil tokens: US$ 0,10 / US$ 0,50):

O que essa tabela revela é o tipo de informação que a fatura mensal esconde: o classificador custa menos de um centésimo do chat por chamada. Se ele for chamado 50 vezes mais, ainda assim não é o problema. O candidato a investigar é o chat, cuja entrada de 3.000 tokens provavelmente carrega histórico e instruções repetidas, exatamente o caso em que o cache de prompt e o resumo do histórico (temas de artigos anteriores) mais ajudam.

Do registro à decisão

Com o registro pronto, três consultas simples já mudam a forma de operar o app. A primeira é custo por funcionalidade no mês, que mostra onde cortar primeiro. A segunda é custo por usuário ou por tenant, essencial se você pretende cobrar por plano: sem ela, um único cliente pesado pode consumir a margem de dez clientes leves sem que ninguém perceba. A terceira é a média de tokens por chamada ao longo do tempo; se ela sobe devagar, geralmente é um histórico de conversa ou um prompt de sistema que cresceu sem ninguém notar.

Depois vêm os alertas. Um limite diário por funcionalidade, checado no servidor antes de cada chamada, evita o susto de um laço infinito ou de um bot abusando do endpoint. Para chamadas grandes, vale usar o count_tokens como porteiro: se a estimativa passa de um teto que você definiu, o app encurta o contexto ou pede confirmação ao usuário em vez de gastar às cegas.

Um cuidado final: guarde apenas números e rótulos, não o texto dos prompts, a menos que precise dele para depuração. Isso mantém o registro leve e evita acumular dados pessoais dos seus usuários sem necessidade, o que ajuda também na conformidade com a LGPD. E lembre que a chave da API deve ficar no servidor; o registro é gravado ali, nunca no navegador.

Conclusão

Otimizar tokens sem medir é como dieta sem balança: dá sensação de progresso, mas ninguém sabe se funcionou. O campo usage de cada resposta, uma tabela com quatro colunas e dois ou três alertas já colocam seu mini-software em outro patamar, porque cada decisão de cache, de modelo ou de contexto passa a ter um antes e um depois comprováveis. Comece hoje: grave o consumo de uma única funcionalidade por uma semana e veja o que aparece.

Fontes

• Claude Platform Docs: Count tokens in a Message, consultado em 30/10/2026.
• Claude Platform Docs: Pricing, consultado em 30/10/2026 (a página não exibe data de publicação; os preços podem mudar).