Controle de custos do Claude Code/API: orçamento de tokens, alertas e limites

Claude Code fica muito mais fácil de adotar quando o custo pode ser explicado antes da fatura. O gasto não depende só do modelo. Ele muda com o tamanho do contexto, os arquivos lidos, a extensão da resposta, os acertos de prompt caching e o tipo de autenticação: assinatura Claude ou cobrança direta pela API da Anthropic.

Este guia foi conferido em 2026-06-03 com fontes oficiais: Anthropic API pricing, Claude Code cost management, Prompt caching, Token counting e Usage and Cost API. Preços mudam; confirme a página oficial antes de comprar, vender treinamento ou estimar custo para cliente.

Modelo mental simples

Termo	Significado	Impacto no custo
Tokens	Unidades que Claude lê e escreve	Arquivos, logs, prompts e código longos aumentam consumo
Contexto	Histórico, arquivos lidos, CLAUDE.md e definições de ferramentas	Contexto antigo continua sendo enviado e cobrado
Prompt cache	Reuso de um prefixo igual do prompt	Entradas repetidas ficam muito mais baratas
Limite	Orçamento por tarefa, dia, pessoa ou workspace	Evita gasto aberto e difícil de explicar

custo estimado = tokens de entrada * preço de entrada
               + tokens escritos no cache * preço de escrita
               + tokens lidos do cache * preço de leitura
               + tokens de saída * preço de saída

Em 2026-06-03, a tabela oficial lista Sonnet 4.6 a $3/MTok de entrada e $15/MTok de saída. Haiku 4.5 aparece a $1 e $5. Opus 4.8/4.7/4.6 aparece a $5 e $25. Leituras de cache custam 10% do preço base de entrada; escritas de cache de 5 minutos custam 1.25x.

O custo que mais escapa costuma ser a saída. Troque “explique tudo em detalhes” por “liste no máximo 5 problemas, por severidade, com duas linhas cada”.

Fluxo de controle

flowchart LR
  A["Definir tarefa"] --> B["Reduzir entrada"]
  B --> C["Escolher modelo"]
  C --> D["Estimar tokens"]
  D --> E{"Dentro do orçamento?"}
  E -- "Sim" --> F["Executar Claude"]
  E -- "Não" --> B
  F --> G["Registrar usage"]
  G --> H{"Passou do limite?"}
  H -- "Sim" --> I["Parar, alertar ou trocar modelo"]
  H -- "Não" --> A

No Claude Code, comece com /usage e /context. Use /clear ao trocar de tarefa e /compact quando quiser preservar decisões sem carregar todo o histórico. O valor de /usage é estimativa local; a referência final de cobrança está no Console e, para organizações, nos relatórios de Usage and Cost.

Exemplo 1: estimador mensal

Este script não chama a API. Ele transforma uso diário em MTok em custo mensal.

// claude-cost-estimator.mjs
const RATES = {
  opus48: { input: 5, output: 25, cacheRead: 0.5 },
  sonnet46: { input: 3, output: 15, cacheRead: 0.3 },
  haiku45: { input: 1, output: 5, cacheRead: 0.1 },
};

const [model = "sonnet46", days = "22", input = "0.25", output = "0.06", cacheRead = "0.20"] =
  process.argv.slice(2);

if (!RATES[model]) {
  throw new Error(`Unknown model: ${model}`);
}

const rate = RATES[model];
const dailyUsd =
  Number(input) * rate.input +
  Number(output) * rate.output +
  Number(cacheRead) * rate.cacheRead;

console.log({
  model,
  workDays: Number(days),
  dailyUsd: Number(dailyUsd.toFixed(4)),
  monthlyUsd: Number((dailyUsd * Number(days)).toFixed(2)),
});

node claude-cost-estimator.mjs sonnet46 22 0.25 0.06 0.20
node claude-cost-estimator.mjs haiku45 22 0.25 0.06 0.20

O objetivo é chegar à ordem de grandeza: esse fluxo custa perto de $15, $50 ou $500 por mês? Some 20-30% de folga para ferramentas, tentativas repetidas, cache writes e respostas maiores.

Exemplo 2: chamada API com limite diário

Este exemplo conta tokens antes de enviar, registra o usage real em JSONL e bloqueia a chamada quando o orçamento diário seria excedido.

npm init -y
npm i @anthropic-ai/sdk

// budgeted-message.mjs
import Anthropic from "@anthropic-ai/sdk";
import fs from "node:fs";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const model = process.env.CLAUDE_MODEL ?? "claude-sonnet-4-6";
const maxTokens = Number(process.env.MAX_TOKENS ?? 700);
const dailyBudgetUsd = Number(process.env.DAILY_BUDGET_USD ?? 5);

const RATES = {
  "claude-opus-4-8": { input: 5, output: 25, cacheWrite5m: 6.25, cacheRead: 0.5 },
  "claude-sonnet-4-6": { input: 3, output: 15, cacheWrite5m: 3.75, cacheRead: 0.3 },
  "claude-haiku-4-5": { input: 1, output: 5, cacheWrite5m: 1.25, cacheRead: 0.1 },
};

function usdFromUsage(usage, rate) {
  return (
    (usage.input_tokens ?? 0) * rate.input +
    (usage.output_tokens ?? 0) * rate.output +
    (usage.cache_creation_input_tokens ?? 0) * rate.cacheWrite5m +
    (usage.cache_read_input_tokens ?? 0) * rate.cacheRead
  ) / 1_000_000;
}

function todayTotalUsd(path) {
  if (!fs.existsSync(path)) return 0;
  const today = new Date().toISOString().slice(0, 10);
  return fs.readFileSync(path, "utf8")
    .trim()
    .split("\n")
    .filter(Boolean)
    .map((line) => JSON.parse(line))
    .filter((row) => row.date === today)
    .reduce((sum, row) => sum + row.usd, 0);
}

const messages = [
  { role: "user", content: "List only the top three bug risks in this TypeScript function." },
];

const rate = RATES[model];
if (!rate) throw new Error(`No rate table for ${model}`);

const counted = await anthropic.messages.countTokens({ model, messages });
const worstCaseUsd = (counted.input_tokens * rate.input + maxTokens * rate.output) / 1_000_000;
const logPath = "claude-usage.jsonl";

if (todayTotalUsd(logPath) + worstCaseUsd > dailyBudgetUsd) {
  throw new Error(`Budget stop: projected daily spend exceeds $${dailyBudgetUsd}`);
}

const response = await anthropic.messages.create({
  model,
  max_tokens: maxTokens,
  cache_control: { type: "ephemeral" },
  system: "You are a concise senior code reviewer. Return only actionable findings.",
  messages,
});

const usd = usdFromUsage(response.usage, rate);
fs.appendFileSync(logPath, JSON.stringify({
  date: new Date().toISOString().slice(0, 10),
  model,
  usd: Number(usd.toFixed(6)),
  usage: response.usage,
}) + "\n");

console.log({ id: response.id, usd: Number(usd.toFixed(6)), usage: response.usage });

ANTHROPIC_API_KEY=sk-ant-...
DAILY_BUDGET_USD=5 node budgeted-message.mjs

Para iniciantes, explique assim: pesar a solicitação antes, guardar o recibo depois e parar antes de estourar o dia.

Exemplo 3: relatório de equipe

Organizações podem usar a Admin Usage and Cost API. Ela exige uma Admin API key e não está disponível para contas individuais.

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-06-01T00:00:00Z&\
ending_at=2026-06-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Sinal	Risco	Ação
Participação de Opus	Tarefas simples usam modelo premium	Direcionar resumo, tradução e formatação para Sonnet/Haiku
Tokens de saída	Respostas longas demais	Limitar itens, linhas e max_tokens
Leituras de cache	cache_read_input_tokens perto de zero	Tirar timestamps e valores aleatórios do prefixo cacheado

Três casos de uso

Desenvolvedor solo: use Sonnet como padrão, reserve Opus para arquitetura e depuração difícil, e limpe o contexto quando a tarefa mudar.

Conteúdo e localização: coloque guia de estilo e glossário em um prefixo estável cacheado. Troque apenas o corpo do artigo. Para volume assíncrono, avalie o desconto de 50% da Batch API.

Treinamento e adoção em equipe: dias de treinamento concentram requisições. Defina orçamento diário, alertas e regras de prompt antes da aula. Para programas estruturados, veja /training/.

Armadilhas comuns

Uma API key muda a cobrança. A ajuda oficial explica que ANTHROPIC_API_KEY pode ter prioridade sobre a assinatura logada no Claude Code. Verifique com /status.

Cache não é medido. Prompt cache depende de prefixo estável. Timestamp, UUID ou lista dinâmica no system prompt podem derrubar o hit rate.

Saída fica aberta. Review precisa de limite de achados; resumo precisa de limite de tamanho; geração de código precisa de escopo.

Preços antigos são copiados. Modelos e preços mudam. Revise a página oficial antes de publicar calculadoras ou propostas.

Proxy barato sem auditoria. Se modelo, logs e credenciais não são claros, o desconto pode ser risco escondido.

Leituras relacionadas

• Claude Code token optimization
• Claude Code pricing guide
• Claude Code context management
• Claude Code permission budget loop

Planilhas, templates de prompt e checklists de custo estão em /products/.

Resultado prático

Nos fluxos da ClaudeCodeLab, o maior ganho veio de controles simples: cachear instruções comuns, mandar tradução e formatação para Haiku/Sonnet, reservar Opus para decisões difíceis e gravar cada usage em JSONL. Comece com alerta em 80%, bloqueio em 100% e limpeza de contexto quando a tarefa mudar.