Cache de prompt na Claude API: como funciona e quando vale a pena reutilizar o mesmo contexto?

Se você manda o mesmo system prompt gigante em toda chamada, a Claude API cobra ele inteirinho de novo, toda santa vez

Aí no fim do mês você olha a fatura e não entende: o modelo é o mesmo, a resposta é curtinha, mas o input não para de crescer

O que acontece é simples: cada requisição é independente, então aquele bloco de instruções que nunca muda é reprocessado do zero em cada chamada

Existe um mecanismo oficial na Claude API pra resolver exatamente isso, e ele já está em disponibilidade geral (não precisa mais de beta header). Bora entender o que é o cache de prompt, quanto custa escrever e ler dele, qual o tamanho mínimo pra funcionar e em quais situações reutilizar o mesmo contexto realmente compensa

Como o cache de prompt funciona por baixo do capô

A ideia central: o cache de prompt permite retomar o processamento a partir de prefixos específicos do prompt, reduzindo custo e tempo de processamento quando o prompt tem partes repetidas

Repara na palavra PREFIXO, porque ela explica quase tudo

A hierarquia tools, system e messages:

Os prefixos de cache são criados nessa ordem: tools, depois system, depois messages

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Isso forma uma hierarquia, e a regra é dura: mudança em um nível invalida aquele nível e tudo que vem depois dele

Se você conhece build com camadas de imagem Docker, é bem semelhante: mexeu numa camada de baixo, tudo acima recompila

Ou seja, editar uma ferramenta lá no comecinho derruba o cache do system e das mensagens junto

Tem dois gatilhos extras de invalidação que pegam muita gente de surpresa: mudanças em tool_choice e a presença ou ausência de imagens em qualquer ponto do prompt forçam a criação de uma nova entrada

Quanto tempo a entrada de cache dura?

A duração padrão da entrada é de 5 minutos

E tem um detalhe muito massa: a validade é renovada SEM custo adicional a cada vez que o conteúdo em cache é utilizado

Então uma conversa ativa, com chamadas seguidas, vai empurrando a janela pra frente de graça

Tome cuidado com um ponto de contagem: o tempo é contado a partir do INÍCIO da requisição que escreve ou lê a entrada, não do fim da resposta

Parece detalhe bobo, mas em prompt longo com resposta demorada isso muda a conta de quanto tempo você realmente tem até expirar

Existe também a opção de cache com duração de 1 hora, ativada pelo campo ttl dentro de cache_control

E fora da Claude API?

O recurso não vive só na API da Anthropic

O cache de prompt também está disponível para os modelos Claude via Amazon Bedrock, Google Cloud e Microsoft Foundry

Só que os mínimos podem diferir da Claude API, então se tu roda em nuvem de terceiro, confere o valor da plataforma antes de assumir que é igual

Como ativar o cache de prompt na sua chamada

A boa notícia: é parâmetro, não é reescrita de arquitetura

1. Marque o bloco estável com cache_control. É ele que define o breakpoint, ou seja, até onde vai o prefixo cacheado

<pre><code class="language-json">{ "type": "text", "text": "&lt;seu bloco grande e estável de instruções&gt;", "cache_control": {"type": "ephemeral"} }</code></pre>

O erro comum deste passo: sair espalhando breakpoint por todo lado. O limite é de 4 cache breakpoints por requisição, então gastar slot em bloco pequeno ou instável é desperdício

2. Para cachear definições de ferramentas, coloque o cache_control na ÚLTIMA ferramenta do array tools. Como o cache é por prefixo, marcar a última cobre o array inteiro

<pre><code class="language-json">"tools": [ {"name": "buscar_pedido", "description": "…", "input_schema": {}}, { "name": "criar_ticket", "description": "…", "input_schema": {}, "cache_control": {"type": "ephemeral"} } ]</code></pre>

O erro comum deste passo: esquecer do breakpoint automático. Quando o cache de prompt está ativo e o Claude usa uma ferramenta de servidor (busca web, por exemplo), a API coloca automaticamente um breakpoint no resultado da ferramenta antes da próxima iteração do laço agêntico

E ele OCUPA um dos 4 slots. Então em fluxo agêntico com server tool, considere que você tem 3 pra você

3. Estenda pra 1 hora se as suas chamadas são espaçadas. Mesmo campo, com o ttl explícito

<pre><code class="language-json">{ "type": "text", "text": "&lt;contexto grande reaproveitado ao longo do dia&gt;", "cache_control": {"type": "ephemeral", "ttl": "1h"} }</code></pre>

O erro comum deste passo: tratar o 1h como upgrade grátis. A escrita nesse cache é mais cara que a de 5 minutos, e a tabela da próxima seção mostra o quanto

4. Confira o resultado no usage da resposta. É aqui que você para de achar e passa a saber

<pre><code class="language-json">"usage": { "cache_creation_input_tokens": …, "cache_read_input_tokens": … }</code></pre>

O campo cache_creation_input_tokens são os tokens escritos no cache, e cache_read_input_tokens são os tokens servidos a partir do cache

Na primeira chamada, o normal é ver o valor no campo de ESCRITA e a leitura zerada, afinal é ela que cria a entrada. Da segunda em diante, o número tem que migrar pro campo de leitura

Se não migrar, a documentação tem uma página específica de diagnóstico de cache, a Cache diagnostics, dentro de Build with Claude

Quanto custa escrever e ler do cache de prompt

Aqui o negócio fica interessante, porque o cache não é de graça na entrada e é MUITO barato na saída dele

Os valores são multiplicadores aplicados sobre o preço base de tokens de entrada do modelo que você usa:

Pra aterrissar isso num preço real: o Claude Sonnet 4.6 custa US$ 3 por milhão de tokens de entrada e US$ 15 por milhão de tokens de saída, mesmo preço do Sonnet 4.5

Com esse preço base na mão, é só aplicar os multiplicadores da tabela em cima do valor de input: escrita de 5 minutos sai a 1,25x ele, escrita de 1 hora sai ao dobro, e a leitura sai por 0,1x

Olha o desenho da coisa: você paga um pouco a mais UMA vez pra escrever, e paga uma fração toda vez que lê

E os multiplicadores de cache se somam a outros modificadores de preço, como o desconto da Batch API e residência de dados

O processamento em lote pela Batch API custa 50% menos, então quem já roda em batch empilha os dois efeitos

(esse papo aqui é de quem paga por token na API. Se a tua dúvida ainda é entre pagar por API ou assinar Pro/Max, é outra conversa)

Qual o tamanho mínimo de prompt para o cache funcionar

O cache não pega em prompt pequeno, e o mínimo varia por modelo

Agora a parte que gera mais confusão, presta atenção nisso

Prompts abaixo do mínimo NÃO são armazenados em cache mesmo marcados com cache_control

A requisição é processada normalmente e nenhum erro é retornado

Ou seja: teu código roda liso, tua resposta vem certinha, e o cache simplesmente não existe. Silêncio total, sem aviso

É por isso que o passo de olhar o usage não é opcional

E se você roda em nuvem de terceiro, o mínimo pode ser outro: no Bedrock, o mínimo para Claude Fable 5 e Claude Mythos 5 é de 1.024 tokens

Por que o cache de prompt não está pegando (e como resolver)

Se o número de leitura teima em ficar zerado, quase sempre é um destes quatro

Sintoma: cache_read_input_tokens sempre zerado

Causa: o prompt marcado está abaixo do comprimento mínimo cacheável do modelo

Solução: confere o mínimo do teu modelo na tabela acima e move o breakpoint pra depois de um bloco maior. Lembra que aqui não vem erro nenhum, o silêncio é o comportamento esperado

Sintoma: o cache é reescrito a cada chamada

Causa: alguma coisa está mudando no array tools. Ele fica ANTES do campo system no prefixo da requisição, então editar tools invalida o cache da conversa inteira

Solução: congela as definições de ferramentas. Se a lista de tools é montada dinamicamente (ordem variável, descrição gerada, ferramenta que entra e sai), você está pagando escrita nova toda vez sem perceber

Sintoma: cache funciona às vezes e some sem motivo aparente

Causa: mudança em tool_choice ou presença/ausência de imagens em qualquer ponto do prompt. Qualquer um dos dois força a criação de uma nova entrada

Solução: se o teu fluxo alterna entre chamadas com e sem imagem no mesmo prefixo, separa os caminhos. Misturar os dois no mesmo histórico é receita de cache quebrado

Sintoma: toda instrução nova derruba o prefixo

Causa: a instrução está sendo enfiada no campo system do topo, que é justamente o pedaço cacheado

Solução: dá pra usar mensagens system no meio da conversa, inserindo a instrução nova ao FINAL do histórico em vez de editar o campo system do topo. Uma mensagem com "role": "system" no fim do histórico mantém o prefixo cacheado válido

Muito massa isso, né? Você guia o modelo no meio do caminho sem pagar o prefixo de novo

E pra fechar um medo comum: adicionar mais breakpoints de cache_control NÃO aumenta o custo por si só

A cobrança continua baseada no que é efetivamente escrito e lido do cache, o que existe é o limite de 4 por requisição

Como prevenir tudo isso na prática: congela tools e system, acompanha os dois campos de usage em toda resposta e usa a página Cache diagnostics quando o número não bater

Quando vale a pena reutilizar o mesmo contexto (e quando não)

O critério é um só: repetição do mesmo prefixo dentro da janela de validade

A partir daí, dá pra listar onde compensa

• Bloco grande e estável de instruções, repetido em muitas chamadas seguidas. Você paga 1,25x uma vez e lê a 0,1x nas seguintes. Vale investir em escrever bem esse bloco de instruções, já que ele vira ativo reutilizado e não texto descartável
• Conversas longas. O histórico cresce, mas o prefixo lá do começo não muda, então a parte pesada vai sendo servida do cache
• Agentes com definições de ferramentas fixas. Array tools congelado é o cenário perfeito, marca a última ferramenta e pronto
• Chamadas espaçadas ao longo do tempo. Aqui o TTL de 1 hora faz sentido mesmo com escrita a 2x, porque com 5 minutos a entrada expiraria antes da próxima chamada e você pagaria escrita nova de qualquer jeito

E onde NÃO compensa:

• Prompt abaixo do mínimo do modelo. Não vai cachear, ponto. E não vai te avisar
• Contexto que muda a cada requisição. Se o prefixo é diferente sempre, você só paga escrita a 1,25x e nunca colhe a leitura a 0,1x
• Fluxo com imagens entrando e saindo do prompt. Invalidação garantida
• Chamada única, sem repetição. Escrita mais cara sem leitura depois é só conta maior

Quem quiser ver o recurso aplicado em um produto real: o Claude Code tem documentação oficial própria sobre como usa o cache de prompt

Conclusão

O cache de prompt na Claude API não é fórmula mágica, é uma troca bem simples de entender

Você paga um pouco a mais pra escrever o prefixo (1,25x no de 5 minutos, 2x no de 1 hora) e paga 0,1x toda vez que lê ele de volta

Se o mesmo prefixo se repete dentro da janela de validade, a conta fecha rápido. Se não se repete, não adianta marcar nada

Próximo passo, bem concreto e sem enrolação: pega o MAIOR bloco estável do teu prompt, marca ele com cache_control, roda duas chamadas seguidas e compara cache_creation_input_tokens com cache_read_input_tokens

Se na segunda chamada o número migrou pro campo de leitura, tá pegando 🙂

Se continuou zerado, volta na seção de sintomas antes de mexer em qualquer outra coisa

até o próximo post!