A mecânica do cache, as faixas de preço, as durações de TTL e os limites mínimos de tokens mudam à medida que a Anthropic atualiza a plataforma. Não confie em nenhum número específico de guias de terceiros. Sempre confira a documentação oficial de cache de prompts e a página Modelos e Preços para os valores atuais.
Economia do Cache de Prompts
Toda vez que você chama a API do Claude, você paga por cada token de entrada que envia — incluindo seu prompt de sistema, suas definições de ferramentas e qualquer contexto que você injete. Se você está fazendo muitas chamadas com o mesmo prefixo grande, está pagando para processar esse prefixo do zero toda santa vez.
O cache de prompts muda isso. Você marca uma porção estável do seu prompt como cacheável. A primeira chamada a processa e a armazena. Chamadas subsequentes que acertam o cache pulam esse processamento — e pagam uma fração da taxa normal por esses tokens.
A economia não é cosmética. Para aplicações com prompts de sistema grandes e estáveis ou contexto pesado, o cache pode mudar a economia de um recurso de "caro demais para lançar" para "basicamente de graça para rodar".
O modelo mental: prefixo estável, sufixo volátil
Pense em cada chamada de API como duas partes:
O prefixo estável — conteúdo que não muda entre chamadas. É aqui que o cache se aplica. Exemplos:
- Seu prompt de sistema
- Definições de ferramentas
- Um documento de referência ou base de código grande que você injeta em cada chamada
- Um bloco longo de exemplos few-shot
O sufixo volátil — conteúdo que muda a cada chamada. É aqui que o cache não se aplica. Exemplos:
- A mensagem atual do usuário
- Dados em tempo real que você injeta por requisição
- Histórico de conversa que cresce a cada turno
A regra é simples: estruture seus prompts de forma que o conteúdo estável venha primeiro e o conteúdo que muda venha por último. Os pontos de quebra de cache são posicionais — tudo antes do ponto de quebra marcado é elegível para cache; tudo depois não é.
Se você colocar conteúdo dinâmico antes de conteúdo estático, você quebra o cache, porque o prefixo muda a cada requisição.
Como o modelo de custo funciona
O cache de prompts introduz uma divisão em três vias na forma como os tokens de entrada são precificados:
| Tipo de token | Quando ocorre | Custo em relação à entrada normal |
|---|---|---|
| Gravação de cache | Primeira chamada, ou após o cache expirar | Maior do que a entrada normal |
| Leitura de cache | Chamadas subsequentes que acertam o cache | Muito menor do que a entrada normal |
| Entrada regular | Tokens após o último ponto de quebra de cache | Taxa normal |
Os multiplicadores exatos estão na página oficial de preços e flutuam — confira-os diretamente. O que não muda é a estrutura: gravações custam mais do que o normal, leituras custam muito menos. O ponto de cruzamento — quando você fez chamadas em cache suficientes para recuperar o custo extra da gravação — chega rápido em qualquer prompt com conteúdo estável substancial.
A latência segue o mesmo padrão. Leituras de cache pulam o processamento completo da porção cacheada, o que reduz de forma significativa o tempo até o primeiro token em chamadas com prefixos grandes.
Quando o cache de prompts ajuda
O cache compensa quando duas condições são verdadeiras ao mesmo tempo:
- Você tem um prefixo estável substancial (há um limite mínimo de tokens abaixo do qual o cache não está disponível — confira a documentação atual para o número exato por modelo).
- Esse prefixo é reutilizado com frequência suficiente para acertar o cache mais do que ocasionalmente.
Cenários em que o cache é um encaixe natural:
- Perguntas e respostas sobre documentos — o mesmo documento grande é injetado para muitas perguntas de usuários.
- Assistentes de programação — uma base de código ou árvore de arquivos grande é incluída em cada requisição.
- Laços agênticos — o mesmo prompt de sistema e as mesmas definições de ferramentas são enviados em cada etapa de um fluxo de trabalho de múltiplas etapas.
- Agentes conversacionais com instruções longas — uma persona detalhada, conjunto de regras ou base de conhecimento que nunca muda de uma chamada para outra.
- Processamento em lote — muitas entradas rodam contra o mesmo template.
Quando o cache de prompts não ajuda
O cache não é útil quando:
- Seus prompts são curtos (abaixo do limite mínimo de tokens cacheáveis).
- Seu prefixo muda a cada chamada — injetar um carimbo de tempo, um contexto específico do usuário ou qualquer personalização na parte "estável" invalida o cache.
- Você faz chamadas infrequentes com longos intervalos entre elas. O conteúdo em cache expira após um TTL (uma duração que você pode configurar, dentro dos limites que a API suporta). Se o seu tráfego for esparso, você estará pagando majoritariamente custos de gravação com poucas leituras.
- Seu prefixo é pequeno em relação ao conteúdo dinâmico por chamada. A economia escala com o tamanho do que está em cache.
Estruturando prompts para serem amigáveis ao cache
O único requisito estrutural é a ordem: o conteúdo estável deve vir antes do conteúdo volátil.
Na prática:
[Prompt de sistema — instruções, persona, regras]
[Definições de ferramentas — se estáticas]
[Documentos ou contexto grandes injetados — se forem os mesmos entre chamadas]
--------- ponto de quebra de cache aqui ---------
[Conteúdo dinâmico por chamada — mensagem do usuário, trechos recuperados específicos desta requisição]
Você marca o ponto de quebra com um campo cache_control no último bloco que deseja incluir no cache. Tudo antes desse marcador é elegível para cache; tudo depois é entrada regular.
Você pode colocar até quatro pontos de quebra explícitos em uma única requisição. Isso é útil quando partes diferentes do seu prompt mudam em frequências diferentes — por exemplo, definições de ferramentas mudam raramente, o histórico de conversa muda a cada turno. Cada seção pode ter seu próprio ponto de quebra.
Regras de invalidação de cache
O cache é sensível à ordem. Qualquer mudança em um bloco em cache, ou em qualquer bloco que venha antes dele no prompt, invalida o cache naquele ponto de quebra e em todos os subsequentes.
Mudanças nas definições de ferramentas invalidam todos os caches. Mudanças no prompt de sistema invalidam os caches de sistema e de mensagens. Mudanças no meio da conversa afetam apenas o cache de mensagens.
A implicação prática: se você está injetando qualquer coisa que muda por requisição, certifique-se absolutamente de que ela viva depois do último ponto de quebra de cache, não antes nem dentro dele.
Pré-aquecimento e monitoramento
Você pode pré-aquecer o cache antes de o tráfego de usuários chegar enviando uma requisição com max_tokens: 0 — isso grava o cache sem gerar saída. Útil para trabalhos em lote ou para adiantar o custo de gravação durante horários de baixo pico.
O campo usage da resposta da API lhe diz quantos tokens foram lidos do cache (cache_read_input_tokens), gravados no cache (cache_creation_input_tokens) e cobrados como entrada regular. Monitore esses valores para verificar se seu cache está de fato acertando e para medir a economia que você está realizando.
Use a Calculadora de Custos para modelar a economia esperada antes de se comprometer com uma arquitetura de cache.
A conclusão
O cache de prompts não é uma micro-otimização. Para qualquer aplicação que envia o mesmo prefixo grande repetidamente, é uma decisão econômica estrutural. O modelo para pensar nisso é direto: conteúdo estável vai primeiro, conteúdo volátil vai por último, coloque o ponto de quebra na fronteira.
Se você está desenvolvendo contra a API e ainda não olhou para o cache, confira seus prompts atuais em busca de seções estáveis grandes. Se elas existem, habilitar o cache geralmente exige pouco esforço e a economia é real.