Cache de prompts Claude: quando começa a compensar

O custo do armazenamento em cache de prompts antes de compensar

O armazenamento em 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 modelo. Em agosto de 2026, uma gravação na 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 da cache custa 0.1x. Estes multiplicadores aplicam-se a todos os modelos, por isso o ponto de equilíbrio não muda quando o preço por token muda.

A troca consiste numa sobretaxa imediata por um desconto posterior. Paga um valor adicional uma vez para armazenar um prefixo. Cada pedido posterior que comece exatamente pelos mesmos bytes paga apenas um décimo do preço normal de entrada por essa parte. Um prefixo que nunca seja reutilizado durante o período de validade custa 25 por cento adicionais sem 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 a cache de 5 minutos, o primeiro pedido grava o prefixo a 1.25B e os N menos 1 pedidos restantes leem-no a 0.1B. Igualando os dois valores, obtém-se 0.9N = 1.15, portanto N = 1.28. O segundo pedido já fica mais barato do que não usar cache.

Repita o cálculo com a gravação a 2x da cache de 1 hora e obtém 0.9N = 1.9, portanto N = 2.11. A cache longa precisa de duas leituras para atingir o ponto de equilíbrio, razão pela qual não é a opção predefinida.

O gráfico abaixo calcula estes valores para um prefixo de 20,000 tokens no Claude Opus 5, cuja tarifa base de entrada é $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.

[
  {
    "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 única vez representa uma perda líquida. No segundo pedido, a cache de 5 minutos fica em $0.135, contra $0.20. Nesse ponto, a cache de 1 hora ainda fica acima, com $0.21, contra os mesmos $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.

Uma leitura da cache também atualiza a entrada, razão pela qual a tabela de preços publicada chama essa coluna leituras e atualizações da cache. Um endpoint com tráfego intenso mantém, portanto, uma entrada de 5 minutos ativa indefinidamente a preços de leitura, enquanto a validade de 1 hora só compensa a gravação a 2x quando o tráfego tem intervalos reais.

O custo de uma baixa taxa de acerto

As falhas de cache acontecem com tráfego real. Um pedido que não encontra a entrada no cache, mas que ainda contém um breakpoint, é cobrado como uma escrita. Por isso, a forma correta de modelar o custo é em função da taxa de acerto. O gráfico abaixo mostra esse comportamento para 1,000 pedidos, cada um contendo 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. 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 resulta em 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 valores chegam a $21.50 e $29.00. Com 99 por cento, o cache curto chega a $11.15, próximo do limite inferior de um décimo do preço sem cache.

A taxa de acerto é o valor que deve instrumentar, porque é o único parâmetro que pode controlar depois de fixar o tamanho do prefixo.

Quais prefixos justificam um breakpoint

Uma requisição pode conter até quatro breakpoints de cache. A questão é decidir quais blocos justificam um deles. Os candidatos são blocos idênticos byte a byte entre chamadas e suficientemente grandes para ter impacto. O gráfico abaixo calcula o custo de quatro formatos comuns em 1.000 requisições, 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 system prompt simples com 2,000 tokens poupa $7.85 por 1.000 requisições em comparação com $10.00 sem cache. É uma poupança relevante em grande escala, mas não é isso que torna o caching interessante. Se adicionar as definições das ferramentas, passa para 8,000 tokens e poupa $31.40. Um documento de políticas com 25,000 tokens, sobre o qual todas as requisições colocam perguntas, poupa $98.12. A última linha é a que altera a arquitetura: 120,000 tokens de contexto de uma base de código ou transcrição custam $600.00 sem cache e $129.00 com cache, uma poupança de $471.00.

As poupanças aumentam com o tamanho do prefixo e com a taxa de acerto, e não dependem de mais nada. Isto altera o que vale a pena incluir num prompt: quanto custam realmente um milhão de tokens do Claude passa a custar um décimo do preço indicado para tudo o que enviar mais de uma vez.

Como isto aparece numa fatura mensal

O gráfico abaixo usa o prefixo de tokens 8,000 definido acima, um prompt de sistema e definições de ferramentas, com uma taxa de acerto de 90 por cento, e projeta o resultado 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, que corresponde à diferença entre $400.00 e $86.00. Com 100,000 pedidos, a poupança é de $3,140.00. Com 1 milhão de pedidos, o custo dos tokens de entrada sem cache é de $40,000.00, e o caching elimina $31,400.00 desse valor. Estes valores referem-se apenas aos tokens de entrada. A saída é cobrada separadamente, e o caching 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 caching complementa as práticas mais amplas descritas em manter a fatura de um agente de IA sob controlo num VPS.

Como provar que o cache está a funcionar

Não confie apenas no desenho. Leia o bloco de utilização da resposta. Cada resposta da Messages API (interface de programação de aplicações) indica os tokens colocados no cache, os tokens lidos do cache e os tokens novos que 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 duas vezes com o mesmo documento e uma pergunta diferente. A primeira chamada apresenta um valor cache_creation_input_tokens diferente de zero e cache_read_input_tokens igual a zero. A segunda inverte esses valores, porque o prefixo foi encontrado. input_tokens contabiliza apenas os tokens depois do último ponto de interrupção. Numa segunda chamada normal, esse valor é pequeno, normalmente apenas a nova mensagem do utilizador.

Pode fazer 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 o resultado real. Se cache_read_input_tokens continuar em 0 entre chamadas, estará a pagar a escrita a 1.25x em todas as chamadas sem receber qualquer benefício do cache.

Para a duração de 1 hora, o ponto de interrupção inclui um tempo de vida (TTL):

{
  "type": "text",
  "text": "your stable prefix",
  "cache_control": {"type": "ephemeral", "ttl": "1h"}
}

Também existe cache automático: um único campo cache_control no nível superior do pedido, depois do qual a API gere os pontos de interrupção à medida que a conversa cresce. Esse mecanismo consome um dos seus quatro slots de pontos de interrupção. Comece por aqui. Use pontos de interrupção explícitos quando precisar de decidir exatamente onde fica o limite.

A regra de ordenação que destrói as taxas de acerto

O 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. Editar a descrição de uma ferramenta invalida o prompt do sistema e todo o histórico de mensagens, mesmo que não os tenha alterado.

Isto estabelece uma regra sem exceções. Tudo o que muda entre pedidos deve vir depois de tudo o que não muda.

O responsável 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 pedido e nenhuma entrada anterior pode corresponder. Mova essa linha 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, colocam todos os tokens estáveis atrás de um limite que muda.

O segundo problema é colocar o ponto de interrupção no bloco que muda. As gravações no cache ocorrem 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 respetivos pontos de interrupção variáveis. Coloque cache_control no último bloco cujo conteúdo seja idêntico entre pedidos.

O terceiro problema é uma alteração de parâmetro que não considerou conteúdo do prompt. Um modelo diferente tem um cache diferente. Alterar a seleção da ferramenta invalida tudo a partir do nível do sistema. Adicionar ou remover uma ferramenta invalida tudo.

O prefixo mínimo e a operação silenciosa sem efeito

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. Esta também é a razão pela qual o modelo mais barato não é automaticamente o mais barato para uma carga de trabalho com cache. O Haiku 4.5 precisa de um prefixo oito vezes mais longo do que o Opus 5 para que o cache seja ativado, por isso um prompt de sistema com 2,000 tokens é colocado em cache num modelo e é silenciosamente ignorado no outro.

Onde o Claude Code armazena a cache e onde isso não ajuda

O Claude Code armazena 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 de posição. Por isso, são gravados uma vez e reutilizados durante o resto da sessão. É por esse motivo que o custo por turno de uma sessão longa é muito inferior ao 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 adicionar conteúdo no fim. Assim, os novos turnos normais ampliam 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 gravados novamente. Um longo período de inatividade produz o mesmo efeito, porque a entrada expira e o turno seguinte tem de pagar uma gravação completa. Nenhuma destas situações é um erro. Ambas são consequência direta da regra do prefixo.

Se estiver a escrever o seu próprio cliente, aplique esta estrutura desde o primeiro pedido, em vez de a adaptar depois. Construa a chamada como no exemplo uma primeira aplicação da API Claude num VPS, com os blocos estáveis primeiro e os blocos voláteis 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 está abaixo do 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, seguida de uma escrita, e depois de novos 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 acertos ultrapassa 53 por cento.

A taxa de acertos diminui depois de uma implementação. A descrição de uma ferramenta foi editada ou o modelo foi alterado. Ambas as alterações invalidam todo o prefixo. 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 acertos 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. Abaixo de cerca de 53 por cento, o mesmo se aplica à cache de 1 hora.

FAQ

Quantas vezes um prompt tem de ser reutilizado para que o armazenamento em cache seja compensador?

Uma vez, na cache de 5 minutos. Uma escrita custa 1.25x o custo base dos tokens de entrada e uma leitura custa 0.1x. Assim, 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, pelo que o segundo pedido já é mais barato. A cache de 1 hora tem uma escrita a 2x e cruza-se em N = 2.11, pelo que precisa de duas leituras.

Porque é que cache_read_input_tokens é sempre 0?

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, o armazenamento em cache é ignorado silenciosamente e ambos os contadores ficam a 0. Se o prefixo tiver comprimento suficiente, procure conteúdo que mude entre chamadas e 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 ao tempo de vida da cache.

O armazenamento em 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 nos dois casos. É uma funcionalidade de faturação e latência, não uma alteração de comportamento. Isto também significa que pode ativá-la num prompt funcional sem repetir as 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 acertos continuar acima de aproximadamente 53 por cento. A escrita a 2x duplica o custo desfavorável da escrita a 1.25x quando não há acerto. Uma entrada de 5 minutos é renovada a cada acerto, pelo que um tráfego constante a mantém ativa ao preço das leituras sem nunca pagar pelo tempo de vida mais longo.