Noções Básicas de Economia de Tokens
9 exemplos para você começar com a economia de tokens - 6 básicos e 3 intermediários.
Pré-requisitos
- Instale o SDK:
pip install anthropic - Defina sua chave de API no ambiente:
export ANTHROPIC_API_KEY=sk-ant-... - Todos os exemplos abaixo usam
anthropic.Anthropic(), que lê essa variável de ambiente automaticamente.
Exemplos Básicos
1. Conte Tokens Antes de Enviar uma Solicitação
Obtenha uma contagem exata de tokens para uma solicitação sem pagar por uma conclusão.
import anthropic
client = anthropic.Anthropic()
count = client.messages.count_tokens(
model="claude-sonnet-5",
messages=[{"role": "user", "content": "Resuma o relatório do terceiro trimestre em três pontos."}],
)
print(count.input_tokens)count_tokensespelha a assinatura demessages.create, portanto, você passa os mesmossystem,toolsemessagesque enviaria de verdade.- Ele retorna apenas
input_tokens, pois o comprimento da saída não é conhecido até que a geração ocorra. - Esta chamada em si é gratuita, não executa o modelo nem gera uma conclusão.
- Use-a como um teste sem execução antes de qualquer solicitação cujo tamanho seja imprevisível, como documentos fornecidos pelo usuário.
Relacionado: Como Funciona o Preço de Tokens do Claude - por que entrada e saída são precificadas de forma diferente.
2. Estime o Custo a Partir de uma Contagem de Tokens
Transforme uma contagem de tokens em uma estimativa em dólares usando a taxa publicada de um modelo.
SONNET_INPUT_PER_MTOK = 2.00 # preço introdutório, até 2026-08-31
count = client.messages.count_tokens(
model="claude-sonnet-5",
messages=[{"role": "user", "content": "Resuma o relatório do terceiro trimestre em três pontos."}],
)
estimated_input_cost = (count.input_tokens / 1_000_000) * SONNET_INPUT_PER_MTOK
print(f"${estimated_input_cost:.6f}")- Dividir por
1_000_000converte uma contagem bruta de tokens em milhões de tokens, correspondendo a como o preço por milhão de tokens é cotado. - Isso estima apenas o lado da entrada; o custo da saída é desconhecido até que o modelo realmente responda.
- Mantenha a taxa constante em um só lugar, não espalhada inline, para que uma atualização de preço seja uma alteração de uma linha.
- Para um limite superior aproximado, multiplique
max_tokenspela taxa de saída e adicione a esta estimativa.
3. Leia o Uso Real de uma Resposta Concluída
Obtenha contagens exatas de tokens faturados após uma chamada real.
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=300,
messages=[{"role": "user", "content": "Resuma o relatório do terceiro trimestre em três pontos."}],
)
print(response.usage.input_tokens, response.usage.output_tokens)response.usageé a fonte da verdade, reflete o que você está realmente sendo faturado.count_tokensantes da chamada eusageapós a chamada devem relatar os mesmosinput_tokenspara uma solicitação idêntica.output_tokensestá disponível apenas aqui, nunca em uma estimativa pré-chamada.- Registre isso em todas as chamadas se você estiver construindo qualquer tipo de painel de custos.
4. Calcule o Custo Real em Dólares de uma Resposta
Combine o uso de entrada e saída com as taxas por modelo para um custo exato.
RATES = {
"claude-sonnet-5": {"input": 2.00, "output": 10.00},
"claude-haiku-4-5": {"input": 1.00, "output": 5.00},
}
def cost_of(response, model: str) -> float:
rate = RATES[model]
usage = response.usage
return (
(usage.input_tokens / 1_000_000) * rate["input"]
+ (usage.output_tokens / 1_000_000) * rate["output"]
)
print(f"${cost_of(response, 'claude-sonnet-5'):.6f}")- Manter as taxas em um dicionário indexado pelo nome do modelo torna trivial adicionar Opus ou Fable mais tarde.
- Esta função é o bloco de construção para qualquer registro de custo por solicitação que você adicionar downstream.
- Ela ignora os tokens de cache por enquanto; veja o exemplo 6 para a versão ciente de cache.
- Arredonde para exibição, mas armazene o float não arredondado se você estiver agregando custos de muitas chamadas.
Relacionado: Construindo um Calculador de Custo Pré-Solicitação com a API de Contagem de Tokens - integrando isso a um portão de pipeline.
5. Conte Tokens para uma Solicitação que Inclui Ferramentas
Confirme que as definições de ferramentas contam para o total de entrada.
tools = [
{
"name": "get_weather",
"description": "Obtém o clima atual para uma cidade.",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}
]
count = client.messages.count_tokens(
model="claude-sonnet-5",
tools=tools,
messages=[{"role": "user", "content": "Qual é o clima em Austin?"}],
)
print(count.input_tokens)- Esquemas de ferramentas fazem parte do prefixo de entrada e são cobrados como quaisquer outros tokens de entrada.
- Um grande catálogo de ferramentas com muitas ferramentas e descrições longas pode dominar a contagem de tokens de uma pequena mensagem do usuário.
- Comparar esta contagem com a do exemplo 1 mostra exatamente quantos tokens as definições de ferramentas adicionam.
- Este é o número que importa ao decidir se um catálogo de ferramentas vale a pena ser cacheado.
6. Conte Tokens para uma Conversa Multi-Turno
Veja como a contagem de tokens cresce à medida que o histórico da conversa se acumula.
conversation = [
{"role": "user", "content": "Qual é a nossa política de reembolso?"},
{"role": "assistant", "content": "Reembolsos são aceitos em até 30 dias após a compra."},
{"role": "user", "content": "Isso se aplica a itens abertos?"},
]
count = client.messages.count_tokens(
model="claude-sonnet-5",
messages=conversation,
)
print(count.input_tokens)- Cada turno anterior, tanto do usuário quanto do assistente, é reenviado como entrada em cada nova chamada, é assim que o modelo tem memória.
- A contagem de tokens para uma conversa cresce aproximadamente linearmente com o número de turnos, é por isso que chats de longa duração se tornam progressivamente mais caros por turno.
- Este é o mecanismo exato que o cache de prompt foi projetado para compensar para as partes estáveis de uma conversa.
- Verificar essa contagem periodicamente em um chat longo ajuda a capturar o crescimento descontrolado do contexto antes que ele se torne uma surpresa de custo.
Exemplos Intermediários
7. Crie um Portão de Custo Pré-Envio
Recuse-se a enviar uma solicitação se o custo estimado exceder um orçamento.
def send_if_affordable(client, max_cost_usd: float, **kwargs):
count = client.messages.count_tokens(
model=kwargs["model"],
messages=kwargs["messages"],
system=kwargs.get("system"),
tools=kwargs.get("tools"),
)
rate = RATES[kwargs["model"]]
input_cost = (count.input_tokens / 1_000_000) * rate["input"]
# Pior caso: assuma que todo o orçamento de max_tokens é usado como saída.
worst_case_output_cost = (kwargs.get("max_tokens", 0) / 1_000_000) * rate["output"]
if input_cost + worst_case_output_cost > max_cost_usd:
raise ValueError(
f"Custo estimado ${input_cost + worst_case_output_cost:.4f} excede o orçamento ${max_cost_usd}"
)
return client.messages.create(**kwargs)
response = send_if_affordable(
client,
max_cost_usd=0.05,
model="claude-sonnet-5",
max_tokens=300,
messages=[{"role": "user", "content": "Resuma o relatório do terceiro trimestre em três pontos."}],
)- A estimativa de pior caso para a saída usa
max_tokenscomo um limite superior, pois o comprimento real da saída é desconhecido antes da chamada. - Este padrão é a semente de um guarda de orçamento por inquilino ou por recurso em um aplicativo multiusuário.
- Levantar uma exceção antes da chamada significa que você nunca paga por uma solicitação que teria rejeitado de qualquer maneira.
- Ajuste a suposição do pior caso se suas conclusões típicas rodarem bem abaixo de
max_tokens; um limite fixo pode ser muito conservador.
8. Rastreie os Gastos em Execução em um Lote de Chamadas
Acumule custos em muitas solicitações em um loop.
def process_documents(client, documents: list[str], model: str) -> float:
total_cost = 0.0
for doc in documents:
response = client.messages.create(
model=model,
max_tokens=200,
messages=[{"role": "user", "content": f"Extraia as entidades chave de:\n{doc}"}],
)
total_cost += cost_of(response, model)
return total_cost
total = process_documents(client, ["texto do doc um...", "texto do doc dois..."], "claude-haiku-4-5")
print(f"Custo total da execução: ${total:.4f}")- Acumular
cost_of(...)por chamada transforma um trabalho em lote em um trabalho com um custo total conhecido e auditável. - Executar isso primeiro com Haiku para uma verificação de sanidade barata antes de mudar para um modelo mais forte é um padrão comum.
- Este mesmo loop é o que você instrumentaria com logging ou um emissor de métricas em produção.
- Compare a média por documento com seu orçamento por documento, não apenas o total do lote, para capturar outliers de custo.
Relacionado: Tiering de Modelos: Roteando Tarefas Simples para Haiku, Tarefas Difíceis para Opus - escolhendo o modelo que este loop chama.
9. Compare o Custo Estimado vs. Real para Capturar Desvios
Verifique se sua estimativa pré-chamada corresponde ao que foi realmente faturado.
count = client.messages.count_tokens(
model="claude-sonnet-5",
messages=[{"role": "user", "content": "Resuma o relatório do terceiro trimestre em três pontos."}],
)
estimated_input_tokens = count.input_tokens
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=300,
messages=[{"role": "user", "content": "Resuma o relatório do terceiro trimestre em três pontos."}],
)
actual_input_tokens = response.usage.input_tokens
assert estimated_input_tokens == actual_input_tokens, "Estimativa e uso real divergiram"- Para uma solicitação idêntica,
count_tokensde entrada eusage.input_tokensdevem sempre corresponder exatamente. - Uma divergência geralmente significa que a solicitação mudou entre a estimativa e a chamada real, não um bug de precificação.
- Integrar esta asserção a um conjunto de testes captura desvios acidentais de prompt entre um estimador de custo e o caminho de código ativo.
- Esta verificação não tem relação com os tokens de saída, que só existem após a geração.
Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial
anthropicpara Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.