Cálculo de break-even do prompt caching no Claude

Custos do prompt caching antes da economia

O prompt caching permite que o Claude reutilize o início do seu prompt em vez de o ler novamente a cada chamada, e a decisão baseia-se em dois multiplicadores sobre o preço base de entrada do seu modelo. Em outubro de 2026, uma escrita em cache custa 1,25x o valor da entrada base para um tempo de vida de 5 minutos, ou 2x para um tempo de vida de 1 hora, em todos os modelos. Uma leitura de cache custa 0,1x na maioria dos modelos, mas o multiplicador de leitura já não é o mesmo em todo o lado. É de 0,025x no Claude Fable 5.1 e no Claude Mythos 5.1, que foram lançados com essa taxa em 1 de setembro de 2026. É de 0,05x no Claude Opus 5.5 e no Claude Sonnet 5.5, sendo que o Sonnet 5.5 teve a sua taxa reduzida de 0,1x para esse valor em 7 de outubro de 2026. Os cálculos abaixo utilizam a leitura padrão de 0,1x. As leituras mais baratas movem o ponto de equilíbrio ligeiramente a seu favor, e a secção seguinte demonstra em que medida.

A troca consiste num sobrecusto imediato contra um desconto futuro. Paga um valor extra uma única vez para armazenar um prefixo. Cada pedido subsequente que comece exatamente com os mesmos bytes paga então um décimo do preço normal de entrada para essa parte, ou menos nos modelos mencionados acima. Um prefixo que nunca seja reutilizado dentro do seu tempo de vida custou-lhe 25 por cento a mais sem qualquer retorno.

O ponto de equilíbrio, em uma linha de álgebra

Chame B de custo base de entrada do prefixo se você o enviasse sem cache. Sem cache, N requisições custam N vezes B. Com o cache de 5 minutos, a primeira requisição grava o prefixo a 1.25B e as outras N menos 1 requisições o leem a 0.1B. Igualando os dois, temos 0.9N = 1.15, logo N = 1.28. A segunda requisição já é mais barata do que não usar cache.

Repita isso com a gravação de 2x do cache de 1 hora e você obtém 0.9N = 1.9, logo N = 2.11. O cache longo precisa de duas leituras antes de atingir o ponto de equilíbrio, razão pela qual não é a escolha padrão.

Nas leituras mais baratas, a linha se move, mas pouco. A uma leitura de 0.05x, o cache de 5 minutos resulta em 0.95N = 1.2, logo N = 1.26, e a 0.025x resulta em 0.975N = 1.225, também N = 1.26. O cache de 1 hora cai para N = 2.05 e N = 2.03. A resposta prática é a mesma em todos os modelos: o cache de 5 minutos compensa a partir da segunda requisição, o cache de 1 hora a partir da terceira.

O gráfico abaixo precifica isso para um prefixo de 20,000 tokens no Claude Opus 5. Sua taxa base de entrada é de $5 por milhão de tokens em outubro de 2026, inalterada desde agosto. O Opus 5 é agora um modelo legado, embora ainda esteja disponível. Seu sucessor, Claude Opus 5.5, lista $4 por milhão com uma leitura de 0.05x, portanto o mesmo prefixo lá custa $0.10 para gravar e $0.004 para ler. Ajuste cada valor por 0.6 para um modelo de $3 por milhão na leitura padrão de 0.1x. A forma da curva não muda.

[
  {
    "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"
  }
]

Uma requisição isolada custa $0.10 sem cache e $0.125 com cache, portanto, colocar um prompt de uso único em cache é um prejuízo puro. Na segunda requisição, o cache de 5 minutos está em $0.135 contra $0.20. O cache de 1 hora ainda está atrás nesse ponto, $0.21 contra os mesmos $0.20, e ele só supera a linha sem cache na terceira requisição: $0.22 contra $0.30. Em 20 requisições, a diferença é de $2.00 contra $0.315.

Um cache hit também renova a entrada, razão pela qual a tabela de preços publicada nomeia essa coluna como cache hits e renovações. Um endpoint movimentado, portanto, mantém uma entrada de 5 minutos viva indefinidamente a preços de leitura, e o tempo de vida de 1 hora só justifica sua gravação de 2x quando o seu tráfego apresenta lacunas reais.

O custo de uma baixa taxa de acerto

O tráfego real gera falhas. Um pedido que falha no cache, mas ainda carrega um breakpoint, é cobrado como uma escrita. Portanto, a forma correta de modelar isto é calcular o custo como uma função da taxa de acerto. O gráfico abaixo ilustra isso para 1.000 pedidos, cada um carregando o mesmo prefixo de 20.000 tokens.

[
  {
    "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. Resolvendo 1.25 menos 1.15h = 1, o cache de 5 minutos começa a poupar dinheiro a uma taxa de acerto de cerca de 22 por cento, razão pela qual 25 por cento já apresenta $96.25. O mesmo cálculo para a escrita 2x resulta em cerca de 53 por cento para o cache de 1 hora, pelo que uma taxa de acerto de 50 por cento ainda custa $105.00, acima da linha sem cache. A 90 por cento, ambos situam-se em $21.50 e $29.00. A 99 por cento, o cache curto atinge $11.15, próximo do limite mínimo de um décimo do preço sem cache.

Num modelo com leitura de 0.05x, os limiares caem para cerca de 21 por cento para o cache de 5 minutos e 51 por cento para o cache de 1 hora. Numa leitura de 0.025x, estes caem para cerca de 20 e 51 por cento. O limite mínimo desce com o preço da leitura, para um vigésimo ou um quadragésimo do custo sem cache.

A taxa de acerto é o número a monitorizar, pois é o único parâmetro que controla após a definição do tamanho do prefixo.

Quais prefixos valem um breakpoint

Um pedido pode carregar até quatro breakpoints de cache, portanto a questão é quais blocos merecem um. Os candidatos são blocos que são byte-idênticos entre chamadas e grandes o suficiente para serem relevantes. O gráfico abaixo precifica quatro formatos comuns ao longo de 1.000 pedidos com uma taxa de acerto de 90 por cento no cache de 5 minutos.

[
  {
    "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 de tokens 2,000 simples economiza $7.85 por 1.000 pedidos contra $10.00 sem cache. É dinheiro real em volume, mas não é isso que torna o cache interessante. Adicione as definições de ferramentas e você chega a 8,000 tokens e $31.40 economizados. Um documento de política de 25,000 tokens sobre o qual cada pedido faz perguntas economiza $98.12. A última linha é a que altera a arquitetura: 120,000 tokens de base de código ou contexto de transcrição custam $600.00 sem cache e $129.00 com cache, uma economia de $471.00.

As economias escalam com o tamanho do prefixo e com a taxa de acerto, e com nada mais. Isso muda o que vale a pena colocar num prompt: quanto custam realmente um milhão de tokens do Claude cai para um décimo do preço de tabela, ou menos nos modelos com leituras mais baratas, para qualquer coisa que você envie 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.

[
  {
    "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 anula as taxas de acerto

O cache corresponde a um prefixo byte a byte a partir do início da requisição, e a requisição é montada numa ordem fixa: ferramentas, depois sistema, depois mensagens. Uma alteração em qualquer nível invalida esse nível e tudo o que vem a seguir. Edite uma descrição de ferramenta e o prompt do sistema e todo o histórico de mensagens serão invalidados com ela, mesmo que você não os tenha tocado.

Isso resulta numa regra sem exceções. Tudo o que muda entre chamadas deve vir depois de tudo o que não muda.

O culpado habitual é um timestamp. Uma linha contendo Current time: 2026-08-03T14:07:11Z no topo de um prompt de 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 a ele. Mova-o para a mensagem do usuário, no final. Um identificador de sessão ou um nonce por requisição quebra as coisas da mesma forma e tem a mesma correção. Documentos recuperados que diferem por requisição também devem ficar após o bloco em cache, caso contrário, eles empurram cada token estável para trás de um limite que se move.

O segundo culpado é colocar o ponto de interrupção (breakpoint) no bloco que muda. As escritas no cache ocorrem no ponto de interrupção, portanto, se esse bloco for diferente a cada vez, nada estável é armazenado, e a busca encontra apenas entradas que requisições anteriores escreveram em seus próprios pontos de interrupção móveis. Coloque cache_control no último bloco cujo conteúdo é idêntico entre as requisições.

O terceiro é uma alteração de parâmetro que você não considerou como conteúdo do prompt. Um modelo diferente possui um cache diferente. Alterar tool_choice invalida o histórico de mensagens, embora as ferramentas e o prompt do sistema permaneçam em cache. Adicionar ou remover uma ferramenta invalida tudo.

O prefixo mínimo e o no-op silencioso

Um prefixo menor que o mínimo do modelo não é armazenado em cache, e nada o notificará sobre isso. Não há erro nem aviso. O pedido é bem-sucedido e ambos os contadores exibem 0. Em outubro de 2026, os mínimos publicados são:

• 512 tokens no Claude Opus 5 e Claude Fable 5, e nos mais recentes Opus 5.5, Sonnet 5.5, Fable 5.1 e Haiku 5.5
• 1.024 tokens no Claude Sonnet 5 e Claude Opus 4.8
• 4.096 tokens no Claude Haiku 4.5

Se ambos os contadores exibirem 0 em um pedido que você acredita estar em cache, verifique o tamanho do prefixo antes de qualquer outra coisa. É por isso que o modelo mais barato nem sempre é automaticamente o mais barato para uma carga de trabalho com cache. O Haiku 4.5 exige um prefixo oito vezes maior que o Opus 5 para que o cache seja ativado; portanto, um prompt de sistema de 2.000 tokens é armazenado em cache em um e ignorado silenciosamente no outro.

Onde o Claude Code armazena cache para si e onde não o pode fazer

O Claude Code armazena o seu próprio prefixo em cache. O system prompt e as definições de ferramentas situam-se no início de cada pedido e não se alteram, pelo que 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 é muito inferior ao que o tamanho do contexto sugere, e isso reflete-se nos contadores descritos em como o Claude Code reporta a utilização de tokens.

Onde não o pode ajudar é numa alteração perto do início do contexto. O histórico da conversação é apenas de anexação, pelo que os novos turnos comuns estendem um prefixo que já está em cache. Editar um ficheiro que foi lido no início da sessão não quebra isto, porque o Claude Code anexa uma nota de que o ficheiro foi alterado em vez de reescrever a leitura anterior. O que quebra a cache é a mudança de modelos, porque cada modelo tem a sua própria cache. Ligar um servidor MCP cujas ferramentas são carregadas no prefixo também a quebra, assim como a compactação da conversação. Cada uma destas ações faz com que o turno seguinte escreva o prefixo novamente. Um longo período de inatividade faz o mesmo, porque a entrada expira e o turno seguinte paga uma escrita completa. Nenhum destes casos é um erro. É a regra do prefixo a fazer exatamente o que diz.

Se estiver a escrever o seu próprio cliente, aplique o layout do primeiro pedido em vez de o adaptar posteriormente: construa a chamada da forma que uma primeira aplicação da API Claude num VPS faz, com os blocos estáveis primeiro e os voláteis por último.

Modos de falha e o que você verá

Cada chamada é uma escrita. cache_creation_input_tokens é diferente de zero em cada requisição, enquanto cache_read_input_tokens permanece 0. Algo no ponto de interrupção ou antes dele muda entre as chamadas. Imprima os primeiros 200 caracteres do seu prefixo montado em duas requisições consecutivas e compare-os visualmente.

Ambos os contadores são 0. O prefixo está abaixo do mínimo do modelo ou o campo cache_control nunca chegou à API. Conte os tokens do prefixo primeiro e, em seguida, registre o corpo da requisição que você realmente enviou.

As leituras funcionam e depois param. Uma sequência de acertos, depois uma escrita e, em seguida, acertos novamente. O intervalo entre as requisições foi maior que o tempo de vida (TTL). Aceite a escrita ou mude para o TTL de 1 hora após verificar se sua taxa de acertos ultrapassa 53 por cento, ou cerca de 51 por cento em um modelo com leitura de 0.05x ou 0.025x.

A taxa de acertos cai após um deploy. Uma descrição de ferramenta foi editada ou um modelo foi alterado. Ambos invalidam todo o prefixo. Espere uma rodada cara de escritas após cada deploy que altere o prompt.

A fatura aumentou após você ativar o cache. Sua taxa de acertos está abaixo do ponto de equilíbrio. Abaixo de cerca de 22 por cento no cache de 5 minutos, enviar o prefixo sem cache é mais barato; abaixo de cerca de 53 por cento, o mesmo se aplica ao cache de 1 hora. Nos modelos com leitura mais barata, esses limites situam-se em cerca de 20 a 21 por cento e 51 por cento.

FAQ

Quantas vezes um prompt deve ser reutilizado para que o cache compense?

Uma vez, no cache de 5 minutos. Uma escrita custa 1,25x a entrada base e uma leitura custa 0,1x na maioria dos modelos, portanto, 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, logo, o segundo pedido já apresenta vantagem. Em modelos com leitura de 0,05x ou 0,025x, o cruzamento ocorre em N = 1,26, o que resulta na mesma conclusão. O cache de 1 hora escreve a 2x e cruza em N = 2,11, ou cerca de 2,05 nas leituras mais baratas, portanto, requer duas leituras.

Por que cache_read_input_tokens é sempre 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 outubro de 2026, o cache é ignorado silenciosamente e ambos os contadores marcam 0. Se o prefixo for longo o suficiente, procure por conteúdo que mude entre chamadas posicionado no ou antes do ponto de interrupção, como um timestamp ou um identificador de sessão no system prompt. Se os contadores estavam a funcionar e pararam, o intervalo entre os pedidos foi superior ao tempo de vida do cache.

O prompt caching altera as respostas do Claude?

Não. O cache armazena a forma processada dos tokens que já enviou, e o modelo vê o mesmo prompt de qualquer maneira. É uma funcionalidade de faturação e latência, não uma alteração de comportamento. Isto também significa que pode ativá-lo num prompt funcional sem ter de executar novamente as suas avaliações.

Devo pagar pelo cache de 1 hora?

Apenas quando o seu tráfego tiver intervalos superiores a 5 minutos e a sua taxa de acertos ainda atingir cerca de 53 por cento, ou cerca de 51 por cento num modelo com leitura mais barata. Em caso de falha, a escrita de 2x custa quatro vezes mais do que a escrita de 1,25x. Uma escrita de 1 hora falhada desperdiça o preço total da entrada base do prefixo, enquanto uma escrita de 5 minutos falhada desperdiça apenas um quarto desse valor. Uma entrada de 5 minutos é renovada a cada acerto, portanto, um tráfego constante mantém-na ativa a preços de leitura sem nunca pagar pelo tempo de vida mais longo.