Como reduzir sua conta da API do Claude: um guia prático de custos de tokens

O modelo mental do orçamento de tokens

Toda solicitação tem dois fatores de custo:

• Tokens de entrada: prompt de sistema, mensagem do usuário, histórico da conversa, definições de ferramentas, documentos recuperados e qualquer prefixo em cache que ainda seja contabilizado quando não estiver em cache.
• Tokens de saída: a resposta do modelo, incluindo verbosidade acidental e novas tentativas.

Uma fórmula mental útil é:

request_cost ≈ input_tokens × input_rate + output_tokens × output_rate

Isso parece óbvio, mas muda a forma como você investiga os gastos. Se a solicitação média é “barata” na saída, mas cara na entrada, reduzir 400 tokens do prompt de sistema pode ser mais importante do que pedir ao modelo para ser mais sucinto.

Comece pela escolha do modelo

Nem toda tarefa exige o modelo mais capaz. Em sistemas reais, a seleção do modelo costuma ser a otimização mais barata.

Uma armadilha comum é “adotar o modelo superior como padrão”. As equipes costumam enviar todos os prompts ao modelo de ponta porque isso parece mais seguro. Na prática, essa é uma garantia cara para tarefas que não se beneficiam dela. Uma camada de roteamento geralmente vale o esforço:

• Haiku para classificação rápida, extração de JSON, rotulagem de logs e triagem inicial.
• Sonnet para a maioria das cargas de trabalho de agentes ou ferramentas de desenvolvimento.
• Opus somente quando a tarefa realmente precisar de raciocínio mais robusto, síntese com nuances ou quando você tiver medido o custo de uma falha.

Uma política simples que funciona bem é:

1. Experimente o Haiku para tarefas estruturadas de baixo custo.
2. Passe para o Sonnet se a confiança for baixa ou a saída estiver malformada.
3. Passe para o Opus apenas nos casos realmente difíceis.

Esse tipo de cadeia de alternativas costuma ser mais barato do que pagar as tarifas do Opus em todas as solicitações.

Enxugue o prompt de sistema sem concessões

O prompt de sistema é onde o desperdício de tokens se esconde à vista de todos. Ele tende a crescer como dívida técnica: uma linha de política aqui, uma regra de estilo ali, cinco exemplos que ninguém removeu.

O que remover

• Instruções duplicadas que a aplicação já aplica.
• Textos longos sobre “ser prestativo” que não alteram o comportamento.
• Exemplos antigos de casos extremos que já não importam.
• Texto de políticas repetido em todas as solicitações.
• Descrições prolixas de ferramentas quando um esquema compacto é suficiente.

O que manter

• Restrições de comportamento inegociáveis.
• Regras de formato da saída.
• Instruções críticas para a segurança.
• Exemplos mínimos que melhorem significativamente a confiabilidade.

Na prática, já vi equipes cortarem centenas ou milhares de tokens do prefixo repetido sem alterar a qualidade do modelo. O segredo é tratar o prompt de sistema como código de produção: excluir texto sem função, eliminar regras duplicadas e manter apenas o que influencia o comportamento.

Uma abordagem melhor é codificar a estrutura em vez de usar prosa:

{
  "style": "concise",
  "output": "json",
  "must_include": ["root_cause", "next_steps"],
  "must_avoid": ["speculation", "apologies"]
}

Isso é mais fácil de analisar do que três parágrafos de instruções narrativas.

Use cache de prompts para prefixos estáveis

Se sua stack oferecer suporte a cache de prompts, use-o para tudo que se repete entre solicitações: prompts de sistema, esquemas de ferramentas, exemplos few-shot e blocos longos de políticas.

A ideia central não é que “o cache é gratuito”. Ele não é. O ganho é deixar de pagar o preço integral pelo mesmo prefixo a cada chamada.

Bons candidatos para cache

• Prompts de sistema usados em todo o produto
• Definições extensas de funções e ferramentas
• Instruções de recuperação de informações reutilizadas
• Exemplos estáticos de formatação ou estilo
• Estrutura de suporte do agente que raramente muda

Maus candidatos para cache

• Contexto do usuário específico de cada solicitação
• Documentos recém-recuperados
• Instruções que mudam rapidamente
• Conteúdo de rascunho específico da sessão

O erro comum é colocar conteúdo muito variável no prefixo e depois se perguntar por que a taxa de acertos do cache é baixa. Para obter valor, mantenha o segmento em cache estável e coloque os dados específicos da solicitação depois dele.

Exemplo de estrutura de solicitação:

{
  "system": "Stable application prompt + tool definitions + output contract",
  "messages": [
    { "role": "user", "content": "New ticket text here" }
  ]
}

Se você mantiver a parte estável sem alterações, dará ao cache a chance de fazer um trabalho efetivo. Se o prefixo mudar a cada solicitação, você estará apenas pagando o custo adicional de gerenciamento do cache sem nenhum benefício.

Defina max_tokens Com firmeza

Um dos custos silenciosos mais fáceis de gerar é um limite de geração excessivo. Se você definir max_tokens como um valor enorme “por precaução”, estará incentivando respostas longas, especialmente quando o modelo estiver incerto ou prolixo.

Use o menor limite que ainda atenda à tarefa.

Faixas práticas

• Extração / classificação: 32–128 tokens
• Resumos curtos: 128–256 tokens
• Diffs de código / explicações: 256–800 tokens
• Geração aberta: apenas o necessário

Se a tarefa for “retorne um único objeto JSON”, defina um limite rígido. Se a tarefa for “explique esta arquitetura”, não dê ao modelo espaço para escrever um romance, a menos que você queira um.

Muitas equipes também se esquecem de limitar os ciclos de novas tentativas. Se a análise falhar e você pedir automaticamente ao modelo que tente novamente com o mesmo limite generoso de saída, poderá duplicar ou triplicar os gastos com saída em uma única ação do usuário.

Agrupe pequenas tarefas em lotes

O processamento em lote ajuda quando você tem muitas tarefas pequenas e independentes com uma sobrecarga de instruções semelhante.

Em vez disto:

• 50 solicitações separadas de classificação
• 50 prompts de sistema repetidos
• 50 definições de ferramentas repetidas

Faça isto:

• Uma solicitação contendo 50 itens
• Um bloco compartilhado de instruções
• Um esquema de saída compacto

Exemplo de padrão de prompt:

Classify each item into one of: bug, feature, question, billing.

Items:
1. "App crashes after login"
2. "Can you add dark mode?"
3. "How do I reset my password?"

E o contrato de resposta:

[
  {"id": 1, "label": "bug"},
  {"id": 2, "label": "feature"},
  {"id": 3, "label": "question"}
]

Isso reduz a sobrecarga repetida e costuma melhorar a capacidade de processamento. A contrapartida é o alcance das falhas: se um item violar o formato, o lote inteiro poderá precisar de recuperação. Para fluxos de alto valor ou voltados ao usuário e sensíveis à latência, lotes menores ainda podem ser melhores.

O streaming melhora a capacidade de resposta, mas não o custo dos tokens

O streaming é ótimo para a experiência do usuário e, às vezes, para o controle de custos, mas ele não não reduz magicamente os tokens faturados por si só. Você ainda paga por tudo o que o modelo gera.

O streaming ajuda de fato na interrupção antecipada:

• O usuário vê o progresso mais cedo.
• Sua aplicação pode cancelar assim que tiver conteúdo suficiente.
• Você pode interromper uma resposta que se prolonga demais antes que ela atinja o limite configurado.

Esse último ponto é importante. Se você estiver gerando uma resposta para um analisador em uma etapa posterior e os primeiros 120 tokens já contiverem o JSON necessário, não continue coletando mais 800 tokens de explicação.

Na prática, o streaming vale a pena quando sua aplicação consegue reagir durante a geração. Se você apenas transmitir a saída para um log e esperar pela resposta inteira de qualquer forma, terá o benefício para a experiência do usuário, mas pouca redução de custos.

Meça o custo por solicitação, não apenas por mês

Os gastos mensais mostram que você tem um problema. As métricas por solicitação mostram onde ele está.

Acompanhe pelo menos:

• input_tokens
• output_tokens
• cache_hit_tokens se disponível
• nome do modelo
• endpoint / fluxo da funcionalidade
• latência
• número de novas tentativas
• taxa de truncamento ou falha de análise

Um payload simples de registro em log poderia ser assim:

usage = response["usage"]

record = {
    "model": response["model"],
    "input_tokens": usage["input_tokens"],
    "output_tokens": usage["output_tokens"],
    "latency_ms": latency_ms,
    "cache_hit_tokens": usage.get("cache_read_input_tokens", 0),
    "request_type": "ticket_summary",
}
print(record)

Depois, calcule o custo de forma centralizada:

def estimate_cost(input_tokens, output_tokens, input_rate, output_rate):
    return (input_tokens * input_rate) + (output_tokens * output_rate)

As tarifas exatas dependem do seu provedor e modelo, mas o fluxo de trabalho permanece o mesmo. Quando você consegue ordenar as solicitações por custo, os responsáveis geralmente ficam evidentes:

• Um prompt “pequeno” com um prefixo oculto enorme
• Uma chamada de ferramenta que reenvia documentos completos a cada turno
• Um limite de geração que é 10x o que a tarefa precisa
• Um ciclo de novas tentativas que duplica silenciosamente o uso
• Uma rota que deveria usar Haiku, mas sempre usa Opus

Evite o desperdício silencioso

A maior parte do desperdício de tokens é banal, e é por isso que passa pela revisão de código.

Causas comuns

• Reenviar o mesmo histórico longo de conversa a cada turno
• Incluir arquivos-fonte completos quando apenas um diff é necessário
• Pedir texto em prosa quando um JSON estruturado bastaria
• Retornar explicações extensas para sistemas consumidores
• Enviar esquemas de ferramentas maiores que a tarefa em si
• Permitir que novas tentativas automáticas executem novamente o mesmo prompt caro
• Manter logs ou notas internas no contexto do modelo

Uma armadilha particularmente problemática é a “expansão de contexto para ajudar”. Os sistemas de recuperação costumam buscar conteúdo demais porque alguém quis se precaver. Se o modelo só precisa dos três parágrafos mais relevantes, não forneça o documento inteiro só porque a camada de divisão em trechos facilitou isso.

Outra: se você envolver o modelo com um segundo prompt que diz “seja conciso”, talvez tenha acabado de adicionar tokens para resolver um problema de verbosidade que deveria ter sido resolvido com um esquema de saída mais restrito.

Um design prático de solicitação

Aqui está um padrão que funciona bem para muitas tarefas em produção:

request = {
    "model": "claude-sonnet-4.6",
    "max_tokens": 180,
    "system": "Extract the root cause and next action. Return strict JSON.",
    "messages": [
        {
            "role": "user",
            "content": "Investigate this incident summary: ... "
        }
    ]
}

Por que essa estrutura funciona:

• O modelo escolhido tem capacidade suficiente para raciocínio moderado.
• O limite de saída impede a verbosidade excessiva.
• O prompt de sistema é curto e específico.
• O formato de saída é adequado ao processamento por máquinas.
• O payload do usuário contém apenas a entrada necessária para a tarefa.

Se precisar de mais contexto, adicione-o de forma intencional. Não deixe o contexto se acumular por acidente.

O que realmente afeta a conta

Se eu tivesse que ordenar os maiores ganhos, seria assim:

1. Escolha um modelo mais barato para tarefas fáceis
2. Elimine o excesso nos prompts
3. Limite max_tokens de forma rigorosa
4. Use o cache de prompts para prefixos estáveis
5. Agrupe pequenas tarefas independentes em lotes
6. Meça o uso por solicitação
7. Impeça que ciclos de novas tentativas dupliquem os gastos

Essa ordem importa. As equipes costumam começar com otimizações sofisticadas antes de corrigir o óbvio: estão simplesmente pedindo demais, com frequência demais, ao modelo mais caro e com contexto demais.

Recomendações Práticas

• Use Haiku para extração e roteamento simples, Sonnet para a maior parte do trabalho de produto, e Opus apenas quando a tarefa justificar.
• Trate a prompt de sistema como um centro de custos; exclua o texto repetido e mantenha apenas as instruções que alteram o comportamento.
• Ative o cache de prompts para prefixos estáveis, como políticas, esquemas de ferramentas e exemplos few-shot.
• Defina max_tokens ao menor limite útil e reavalie-o para cada tarefa.
• Agrupe em lotes pequenas tarefas independentes quando a sobrecarga de instruções predominar.
• Acompanhe tokens de entrada, tokens de saída, acertos de cache, novas tentativas e latência por solicitação.
• Fique atento ao desperdício silencioso: histórico repetido, recuperação excessiva de conteúdo, saídas extensas e ciclos de novas tentativas automáticas.

Se quiser, posso transformar isso em uma publicação complementar com um exemplo concreto de painel de custos e algumas regras de roteamento para Haiku/Sonnet/Opus.