Por Cache de prompts no Claude: ponto de equilíbrio
Veja por que a gravação custa 1.25x, a leitura 0.1x e o prefixo começa a compensar no segundo uso. Confira a conta e valide tudo pela API.
Custos do cache de prompts antes de começar a gerar economia
O cache de prompts permite que o Claude reutilize o início do prompt, em vez de o ler novamente em cada chamada. Toda a decisão depende de dois multiplicadores aplicados ao preço base de entrada do seu modelo. Em agosto de 2026, uma gravação no cache custa 1.25x o preço base de entrada para a validade de 5 minutos, ou 2x para a validade de 1 hora. Uma leitura do cache custa 0.1x. Esses multiplicadores são iguais em todos os modelos, portanto o ponto de equilíbrio abaixo não muda quando o preço por token muda.
A troca consiste numa sobretaxa imediata em troca de um desconto posterior. Paga mais uma vez para armazenar um prefixo. Cada pedido posterior que começa exatamente com os mesmos bytes paga, por essa parte, um décimo do preço normal de entrada. Se um prefixo nunca for reutilizado durante o seu período de validade, terá pago 25 por cento adicionais sem obter qualquer benefício.
O ponto de equilíbrio, numa linha de álgebra
Chame B ao custo base de entrada do prefixo se o enviasse sem cache. Sem cache, N pedidos custam N vezes B. Com o cache de 5 minutos, o primeiro pedido escreve o prefixo a 1.25B e os restantes N menos 1 pedidos leem-no a 0.1B. Igualando os dois custos, obtém-se 0.9N = 1.15, portanto N = 1.28. O segundo pedido já é mais barato do que não usar cache.
Repita o cálculo com a escrita a 2x do cache de 1 hora e obtém-se 0.9N = 1.9, portanto N = 2.11. O cache de longa duração precisa de duas leituras para atingir o ponto de equilíbrio. É por isso que não é a opção predefinida.
O gráfico abaixo calcula este custo para um prefixo de 20,000 tokens no Claude Opus 5, cuja tarifa base de entrada era de $5 por milhão de tokens em agosto de 2026. Multiplique todos os valores por 0.6 para um modelo de $3 por milhão. O formato da curva não muda.
The data behind this chart
[
{
"requests": 1,
"uncached_usd": "0.10",
"cached_5m_usd": "0.125",
"cached_1h_usd": "0.20"
},
{
"requests": 2,
"uncached_usd": "0.20",
"cached_5m_usd": "0.135",
"cached_1h_usd": "0.21"
},
{
"requests": 3,
"uncached_usd": "0.30",
"cached_5m_usd": "0.145",
"cached_1h_usd": "0.22"
},
{
"requests": 5,
"uncached_usd": "0.50",
"cached_5m_usd": "0.165",
"cached_1h_usd": "0.24"
},
{
"requests": 10,
"uncached_usd": "1.00",
"cached_5m_usd": "0.215",
"cached_1h_usd": "0.29"
},
{
"requests": 20,
"uncached_usd": "2.00",
"cached_5m_usd": "0.315",
"cached_1h_usd": "0.39"
}
]Um único pedido custa $0.10 sem cache e $0.125 com cache. Portanto, colocar em cache um prompt usado uma só vez representa uma perda líquida. No segundo pedido, o cache de 5 minutos fica em $0.135, contra $0.20. O cache de 1 hora ainda fica acima desse valor nesse momento, em $0.21, contra o mesmo $0.20, e só fica abaixo do custo sem cache no terceiro pedido: $0.22, contra $0.30. Com 20 pedidos, a diferença é de $2.00, contra $0.315.
Um acerto do cache também atualiza a entrada. É por isso que a tabela de preços publicada chama essa coluna de acertos e atualizações do cache. Um endpoint com tráfego intenso mantém, portanto, uma entrada de 5 minutos ativa indefinidamente aos preços de leitura. A validade de 1 hora só compensa a escrita a 2x quando o tráfego tem intervalos reais.
O custo de uma taxa de acerto baixa
O tráfego real tem falhas de cache. Uma solicitação que não encontra o prefixo em cache, mas que ainda contém um breakpoint, é cobrada como uma escrita. Por isso, a forma correta de modelar o custo é em função da taxa de acerto. O gráfico abaixo faz isso para 1,000 solicitações, cada uma contendo o mesmo prefixo de 20,000 tokens.
The data behind this chart
[
{
"hit_rate_percent": 0,
"cost_5m_usd": "125.00",
"cost_1h_usd": "200.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 25,
"cost_5m_usd": "96.25",
"cost_1h_usd": "152.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 50,
"cost_5m_usd": "67.50",
"cost_1h_usd": "105.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 75,
"cost_5m_usd": "38.75",
"cost_1h_usd": "57.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 90,
"cost_5m_usd": "21.50",
"cost_1h_usd": "29.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 95,
"cost_5m_usd": "15.75",
"cost_1h_usd": "19.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 99,
"cost_5m_usd": "11.15",
"cost_1h_usd": "11.90",
"uncached_usd": "100.00"
}
]Com uma taxa de acerto de 0 por cento, paga $125.00 em vez de $100.00, e o cache de 1 hora duplica a fatura para $200.00. Resolva 1.25 menos 1.15h igual a 1. O cache de 5 minutos começa a poupar dinheiro com uma taxa de acerto de cerca de 22 por cento. Por isso, 25 por cento já apresenta $96.25. O mesmo cálculo com a escrita 2x dá cerca de 53 por cento para o cache de 1 hora. Assim, uma taxa de acerto de 50 por cento ainda custa $105.00, acima da linha sem cache. Com 90 por cento, os dois ficam em $21.50 e $29.00. Com 99 por cento, o cache curto chega a $11.15, perto do limite de um décimo do preço sem cache.
A taxa de acerto é o valor que deve ser instrumentado. Depois de fixar o tamanho do prefixo, é o único parâmetro que pode controlar.
Quais prefixos justificam um breakpoint
Uma solicitação pode ter até quatro breakpoints de cache. A questão é saber quais blocos justificam um. Os candidatos são blocos idênticos byte a byte entre chamadas e suficientemente grandes para fazer diferença. O gráfico abaixo calcula o custo de quatro formatos comuns em 1.000 solicitações, com uma taxa de acerto de 90 por cento na cache de 5 minutos.
The data behind this chart
[
{
"label": "System prompt",
"prefix_size_tokens": "2,000",
"uncached_usd": "10.00",
"cached_usd": "2.15",
"saved_usd": "7.85"
},
{
"label": "System plus tools",
"prefix_size_tokens": "8,000",
"uncached_usd": "40.00",
"cached_usd": "8.60",
"saved_usd": "31.40"
},
{
"label": "Policy document",
"prefix_size_tokens": "25,000",
"uncached_usd": "125.00",
"cached_usd": "26.88",
"saved_usd": "98.12"
},
{
"label": "Codebase context",
"prefix_size_tokens": "120,000",
"uncached_usd": "600.00",
"cached_usd": "129.00",
"saved_usd": "471.00"
}
]Um prompt de sistema simples com um token 2,000 custa $7.85 menos por 1.000 solicitações do que o custo sem cache, de $10.00. É uma economia real em grande escala, mas não é isso que torna o caching interessante. Ao adicionar as definições das ferramentas, o prompt passa a ter 8,000 tokens e a economia chega a $31.40. Um documento de políticas com 25,000 tokens, sobre o qual todas as solicitações fazem perguntas, poupa $98.12. A última linha é a que altera a arquitetura: 120,000 tokens de contexto de base de código ou de transcrição custam $600.00 sem cache e $129.00 com cache, uma economia de $471.00.
A economia aumenta com o tamanho do prefixo e com a taxa de acerto, e não depende de mais nada. Isso altera o que vale a pena incluir num prompt: quanto custam realmente um milhão de tokens Claude passa a custar um décimo do preço de tabela para tudo o que for enviado mais de uma vez.
Como isto aparece numa fatura mensal
O gráfico abaixo utiliza o prefixo de tokens 8,000 apresentado acima, juntamente com um prompt de sistema e definições de ferramentas, com uma taxa de acerto de 90 por cento, e projeta-o para volumes mensais de pedidos.
The data behind this chart
[
{
"label": "10k requests",
"uncached_usd": "400.00",
"cached_usd": "86.00",
"saved_usd": "314.00"
},
{
"label": "100k requests",
"uncached_usd": "4,000.00",
"cached_usd": "860.00",
"saved_usd": "3,140.00"
},
{
"label": "1M requests",
"uncached_usd": "40,000.00",
"cached_usd": "8,600.00",
"saved_usd": "31,400.00"
}
]Com 10,000 pedidos por mês, a poupança é de $314.00, correspondente à diferença entre $400.00 e $86.00. Com 100,000 pedidos, a poupança é de $3,140.00. Com um milhão de pedidos, o custo dos tokens de entrada sem cache é de $40,000.00, e o cache elimina $31,400.00 desse custo. Estes valores consideram apenas os tokens de entrada. A saída tem um preço separado e o cache não altera esse custo. Tenha isto em conta antes de prometer a alguém uma redução de 90 por cento na fatura. O cache complementa as práticas mais amplas descritas em manter sob controlo a fatura de um agente de IA num VPS.
Como provar que a cache está a funcionar
Não confie apenas no desenho. Leia o bloco de utilização da resposta. Cada resposta da Messages API (application programming interface) indica quantos tokens colocou na cache, quantos tokens leu da cache e quantos tokens novos teve de processar.
from anthropic import Anthropic
client = Anthropic()
resp = client.messages.create(
model="claude-opus-5",
max_tokens=512,
system=[
{
"type": "text",
"text": POLICY_DOCUMENT,
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": question}],
)
u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)Execute o pedido duas vezes com o mesmo documento e uma pergunta diferente. A primeira chamada indica um valor diferente de zero em cache_creation_input_tokens e zero em cache_read_input_tokens. A segunda inverte esses valores, porque o prefixo foi encontrado. input_tokens conta apenas os tokens depois do último breakpoint. Numa segunda chamada normal, esse valor é pequeno e costuma corresponder apenas à nova mensagem do utilizador. As duas chamadas são faturadas, porque a Claude API não tem um nível gratuito, embora, para o prefixo de 20,000 tokens com o preço indicado acima, o par custe cerca de catorze cêntimos.
A mesma verificação a partir da shell, usando um corpo de pedido guardado em request.json:
curl -s https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d @request.json | jq '.usage'Uma segunda chamada normal apresenta algo semelhante a isto:
{
"input_tokens": 42,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 20143,
"output_tokens": 187
}Uma linha mostra a situação real. Se cache_read_input_tokens continuar em 0 entre chamadas, está a pagar a escrita a 1.25x sempre que executa o pedido, sem obter qualquer leitura da cache.
Para a duração de 1 hora, o breakpoint inclui um time to live (TTL):
{
"type": "text",
"text": "your stable prefix",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}Também existe caching automático: um único campo cache_control no nível superior do pedido. Depois disso, a API gere os breakpoints à medida que a conversa cresce. Esse campo consome um dos seus quatro slots de breakpoint. Comece por aqui. Passe para breakpoints explícitos quando precisar de decidir exatamente onde fica o limite.
A regra de ordenação que destrói as taxas de acerto
A cache compara um prefixo byte a byte desde o início do pedido, e o pedido é montado numa ordem fixa: ferramentas, depois sistema e, por fim, mensagens. Uma alteração em qualquer nível invalida esse nível e tudo o que vem depois. Edite uma descrição de ferramenta e o prompt do sistema e todo o histórico de mensagens será invalidado com eles, mesmo que não lhes tenha tocado.
Isto estabelece uma regra sem exceções. Tudo o que muda entre chamadas deve vir depois de tudo o que não muda.
O caso mais comum é um carimbo de data e hora. Uma linha com Current time: 2026-08-03T14:07:11Z no início de um prompt do sistema garante uma taxa de acerto de 0 por cento, porque o hash do prefixo é diferente em cada chamada e nenhuma entrada anterior pode corresponder-lhe. Mova-a para a mensagem do utilizador, no fim. Um identificador de sessão ou um nonce por pedido causa o mesmo problema e tem a mesma correção. Os documentos obtidos que diferem por pedido também devem ficar depois do bloco em cache; caso contrário, empurram todos os tokens estáveis para depois de um limite que muda.
O segundo problema é colocar o ponto de corte no bloco que muda. As gravações na cache acontecem nesse ponto; por isso, se esse bloco for diferente em cada pedido, nada estável é armazenado, e a pesquisa retrospetiva encontra apenas entradas que os pedidos anteriores gravaram nos seus próprios pontos de corte variáveis. Coloque cache_control no último bloco cujo conteúdo seja idêntico entre pedidos.
O terceiro é uma alteração de parâmetro que não considerou conteúdo do prompt. Um modelo diferente tem uma cache diferente. Alterar a escolha da ferramenta invalida tudo desde o nível do sistema. Adicionar ou remover uma ferramenta invalida tudo.
O prefixo mínimo e o no-op silencioso
Um prefixo mais curto do que o mínimo do modelo não é colocado em cache, e nada o informa. Não há erro nem aviso. O pedido é concluído e ambos os contadores mostram 0. Em agosto de 2026, os mínimos publicados são:
- 512 tokens no Claude Opus 5 e no Claude Fable 5
- 1,024 tokens no Claude Sonnet 5 e no Claude Opus 4.8
- 4,096 tokens no Claude Haiku 4.5
Se ambos os contadores mostrarem 0 num pedido que acredita estar em cache, verifique primeiro o comprimento do prefixo. É também por isso que o modelo mais barato não é automaticamente o mais barato para uma carga de trabalho que utiliza cache. O Haiku 4.5 precisa de um prefixo oito vezes mais longo do que o Opus 5 para que o caching seja ativado, pelo que um prompt de sistema com 2,000 tokens é colocado em cache num modelo e ignorado silenciosamente no outro.
Onde o Claude Code coloca a cache e onde ela não ajuda
O Claude Code coloca em cache o seu próprio prefixo. O prompt do sistema e as definições das ferramentas ficam no início de todos os pedidos e não mudam, por isso são escritos uma vez e lidos novamente durante o resto da sessão. É por isso que o custo por turno de uma sessão longa fica muito abaixo do que o tamanho do contexto sugere. Isto aparece nos contadores descritos em como o Claude Code comunica o uso de tokens.
A cache não ajuda quando uma edição ocorre perto do início do contexto. O histórico da conversa só permite acrescentar conteúdo, por isso os novos turnos normais prolongam um prefixo que já está em cache. Editar um ficheiro que foi lido no início da sessão altera o conteúdo no meio desse prefixo. Todos os tokens depois da alteração têm de ser escritos novamente. Um intervalo longo de inatividade produz o mesmo efeito, porque a entrada expira e o turno seguinte paga uma escrita completa. Nenhuma destas situações é um erro. Ambas resultam diretamente da regra do prefixo.
Se estiver a escrever o seu próprio cliente, aplique o layout desde o primeiro pedido, em vez de o adaptar posteriormente. Construa a chamada da forma usada em uma primeira aplicação da Claude API num VPS, com os blocos estáveis primeiro e os blocos variáveis no fim.
Modos de falha e o que verá
Cada chamada é uma escrita. cache_creation_input_tokens é diferente de zero em todos os pedidos, enquanto cache_read_input_tokens permanece em 0. Algo no ponto de interrupção ou antes dele muda entre os pedidos. Imprima os primeiros 200 caracteres do prefixo montado em dois pedidos consecutivos e compare-os visualmente.
Ambos os contadores são 0. O prefixo é menor do que o mínimo do modelo ou o campo cache_control nunca chegou à API. Conte primeiro os tokens do prefixo e, em seguida, registe o corpo do pedido que enviou efetivamente.
As leituras funcionam e depois param. Ocorre uma sequência de acertos, depois uma escrita e, novamente, acertos. O intervalo entre os pedidos foi superior ao tempo de vida. Aceite a escrita ou mude para o TTL de 1 hora depois de confirmar que a taxa de acerto ultrapassa 53 por cento.
A taxa de acerto diminui depois de uma implementação. A descrição de uma ferramenta foi editada ou o modelo foi alterado. Ambos invalidam o prefixo completo. Espere uma ronda dispendiosa de escritas depois de cada implementação que altere o prompt.
A fatura aumentou depois de ativar o armazenamento em cache. A taxa de acerto está abaixo do ponto de equilíbrio. Abaixo de cerca de 22 por cento na cache de 5 minutos, enviar o prefixo sem cache é mais barato. O mesmo se aplica à cache de 1 hora abaixo de cerca de 53 por cento.
FAQ
Quantas vezes um prompt precisa de ser reutilizado para que a cache se pague?
Uma vez, na cache de 5 minutos. Uma escrita custa 1.25x o input base e uma leitura custa 0.1x, por isso N pedidos sem cache custam N, enquanto N pedidos com cache custam 1.25 mais 0.1 vezes N menos 1. Os dois valores cruzam-se em N = 1.28, por isso o segundo pedido já compensa. A cache de 1 hora faz escritas a 2x e cruza-se em N = 2.11, pelo que precisa de duas leituras.
Porque é que cache_read_input_tokens está sempre a zero?
Verifique primeiro o comprimento do prefixo: abaixo do mínimo do modelo, 512 tokens no Claude Opus 5 e 4,096 no Claude Haiku 4.5 em agosto de 2026, a cache é ignorada silenciosamente e ambos os contadores ficam a 0. Se o prefixo for suficientemente longo, procure conteúdo que mude entre chamadas e que esteja no breakpoint ou antes dele, como um timestamp ou um identificador de sessão no system prompt. Se os contadores funcionavam e deixaram de funcionar, o intervalo entre os pedidos foi superior à duração da cache.
A cache de prompts altera as respostas do Claude?
Não. A cache armazena a forma processada dos tokens que já enviou, e o modelo recebe o mesmo prompt em ambos os casos. É uma funcionalidade de faturação e latência, não uma alteração do comportamento. Isto também significa que pode ativá-la num prompt funcional sem repetir as suas avaliações.
Devo pagar pela cache de 1 hora?
Apenas quando o seu tráfego tiver intervalos superiores a 5 minutos e a sua taxa de acerto continuar acima de aproximadamente 53 por cento. A escrita a 2x tem o dobro do custo negativo da escrita a 1.25x quando não há acerto. Uma entrada de 5 minutos é atualizada a cada acerto, por isso o tráfego regular mantém-na ativa a preços de leitura sem pagar pela duração mais longa.