Prompt Caching na API do Claude: corte custos com contextos repetidos

Prompt caching na API do Claude ficou disponível para todos em dezembro de 2024, prometendo até 90% de redução no custo de tokens de input e 85% de melhora na latência para contextos longos repetidos. Esses números são reais. Só que eles refletem performance nas condições exatas para as quais o recurso foi projetado, o que raramente coincide com o estado em que a maioria dos times está quando começa a usá-lo. A sobretaxa na escrita é onde as coisas complicam, e entender isso antes de instrumentar o código evita que você pague mais do que pagaria com o pricing padrão achando que está economizando.

A mecânica básica é mais simples do que os tradeoffs

Quando você envia uma requisição para a API do Claude com breakpoints cache_control, o sistema verifica se o prefixo do prompt até aquele breakpoint já existe no cache de uma chamada recente. Se existir, essa porção é servida a 10% do preço base do token de input. Se não existir, o sistema escreve no cache a 125% do preço base, ou seja, o custo padrão mais uma sobretaxa de 25%.

O TTL do cache é de 5 minutos por padrão, renovado a cada uso dentro dessa janela, com uma opção de 1 hora disponível. Entradas de cache são isoladas entre organizações e, na API do Claude e no Microsoft Foundry, entre workspaces dentro de uma mesma organização. A Anthropic não armazena o texto bruto do prompt em repouso: apenas representações de cache em formato chave-valor e hashes criptográficos ficam em memória. Esse é o modelo de segurança, e vale saber disso se a sua organização tem exigências de governança de dados sobre o que pode ser cacheado.

A sintaxe é mínima. Você adiciona um bloco cache_control ao conteúdo da mensagem ou system prompt que quer cachear:

{
  "type": "text",
  "text": "[seu contexto estático longo aqui]",
  "cache_control": {"type": "ephemeral"}
}

A documentação da Anthropic também cobre caching automático nos modelos mais novos, que gerencia os breakpoints sem marcação explícita. O caching explícito dá controle exato sobre onde o limite do cache fica, o que importa mais do que parece quando você entende como a sobretaxa de escrita acumula.

O exemplo de 100K tokens documentado pelo Spring.io é a ilustração mais clara do teto: uma requisição que levava 11,5 segundos caiu para 2,4 segundos com caching ativado. Nessa escala, a economia é óbvia e o ponto de break-even chega quase imediatamente. Em contextos menores, o cálculo é menos favorável e mais sensível ao quanto o cache realmente é aproveitado.

A sobretaxa de escrita cria um problema de break-even que a maioria não calcula antes

Esse é o cenário que não aparece nos tutoriais. Um time de automação de marketing está rodando um teste A/B em variações de system prompt para um pipeline de geração de conteúdo com Claude. São cinco variantes de prompt, cada uma com cerca de 8.000 tokens, e eles chamam a API umas 30 vezes por variante durante a fase de avaliação de qualidade de output. Toda chamada a uma variante nova ou modificada escreve no cache. Toda escrita custa 125% do pricing padrão de input. Se a taxa de hit durante a iteração ativa é baixa porque o prompt muda com frequência, o time está pagando o prêmio de escrita na maioria das chamadas sem receber praticamente nenhum desconto de leitura para compensar.

A conta vira de economia para prejuízo. A economia anunciada do prompt caching pressupõe um prompt estável servindo muitas requisições, não um prompt que muda a cada rodada de teste. Isso não é letra miúda maliciosa: a documentação da própria Anthropic enquadra o caching em torno de "contextos usados frequentemente entre chamadas de API", o que implica reutilização, não experimentação. A implicação é fácil de ignorar quando você está instrumentando o caching ao mesmo tempo em que ainda está desenhando o que cachear.

Um artigo de 2026 publicado no arXiv por Luo et al. avaliou estratégias de caching em 500 sessões de agentes e encontrou redução de custo de 41% a 80% e melhora de 13% a 31% no time-to-first-token, mas também constatou que caching ingênuo de contexto completo pode paradoxalmente aumentar a latência. Segundo esse artigo, controle estratégico do limite do cache supera cachear tudo por padrão, e essa conclusão se aplica ao custo tanto quanto à latência. Cachear tudo significa escrever tudo no cache, o que significa pagar o prêmio de escrita sobre conteúdo que pode nunca ser reutilizado a uma taxa que justifique isso.

O break-even depende da sua taxa de hit, não só do volume de tokens. Se você está escrevendo no cache a cada chamada e acertando em menos de aproximadamente 80% das chamadas subsequentes (o limite exato varia por contagem de tokens e pricing do modelo), você pode estar operando com prejuízo líquido em relação ao pricing padrão de input. Times em fase inicial de deploy, rodando experimentos ou com sessões de vida curta estão estruturalmente em desvantagem nesse modelo.

Congelar o prompt é uma restrição de workflow, não uma configuração técnica

A disciplina real que faz o prompt caching compensar é o prompt freezing: tratar o conteúdo cacheado como congelado em produção e redirecionar toda a iteração para um ambiente de teste separado, sem cache. Soa óbvio quando posto assim, mas vai contra como a maioria dos times trabalha na prática, onde o system prompt é um documento vivo que recebe ajustes entre deploys, às vezes várias vezes por dia.

Um padrão operacional razoável divide o fluxo em duas fases distintas. Na fase de experimentação, o caching fica desabilitado. Você paga o pricing padrão de input, sua velocidade de iteração não é prejudicada pelos custos de escrita no cache, e você não acumula penalidades de escrita em prompts que não vão sobreviver à semana. Uma vez que uma variante de prompt é selecionada e congelada, ela vai para o ambiente de produção com caching ativado, onde vai servir alto volume com conteúdo estável e gerar economia real.

O posicionamento do breakpoint cache_control segue essa lógica. O caching deve ficar no limite entre o contexto estável (instruções do sistema, documentos de referência, exemplos few-shot) e o conteúdo dinâmico (mensagens do usuário, variáveis de sessão, resultados de ferramentas). O achado do artigo do arXiv de que excluir resultados dinâmicos de ferramentas dos limites do cache supera o caching de contexto completo reflete exatamente esse princípio: conteúdo dinâmico não se beneficia do caching e dilui a eficiência do que você está cacheando ao forçar escritas mais frequentes.

Para sistemas com pipelines RAG densos em documentos, a economia é mais favorável por padrão porque os documentos recuperados costumam ser grandes, estáveis dentro de uma sessão e reutilizados em múltiplos turnos. Um contexto de documento de 50.000 tokens cacheado no início de uma sessão e referenciado em 20 turnos gera o tipo de taxa de hit que torna a sobretaxa de escrita irrelevante. Esse é o caso de uso para o qual o prompt caching foi claramente otimizado, e aparece.

Na prática

Trabalho com automação de catálogo e pipelines de personalização de e-mail para uma operação de varejo online. O padrão que mapeia mais diretamente aqui é o de payloads grandes e relativamente estáticos que precisam ser referenciados em muitas chamadas sucessivas. Catálogos de produtos, documentos de taxonomia, tabelas de mapeamento de atributos: são grandes, mudam em um calendário previsível em vez de a cada chamada, e são referenciados repetidamente dentro de uma sessão ou rodada de workflow. Esse é o perfil que o prompt caching recompensa.

Testar geração de subject lines de e-mail com conjuntos de instruções variados é o contra-exemplo que vale marcar para quem trabalha em contexto similar: os prompts são curtos, mudam constantemente, e o volume por chamada por variante é baixo. Cachear ali prejudicaria mais do que ajudaria. Vale separar esse caso dos usos com fundamentação em documentos, onde o recurso genuinamente se paga. Para quem quer entender melhor as limitações de custo e throughput da API antes de arquitetar o uso de caching, o post sobre estratégias práticas com rate limits da API do Claude complementa bem essa discussão.

O tradeoff que a cobertura genérica ignora

A maioria dos tutoriais sobre prompt caching apresenta o recurso como "adicione cache_control e economize". Isso é verdade na média, mas mascara uma variância alta dependendo do perfil de uso.

O ponto que raramente aparece: o caching explícito e o caching automático têm comportamentos diferentes em relação a quem controla o breakpoint. Com caching explícito, você define exatamente onde o cache corta, o que permite excluir seções que mudam com frequência. Com caching automático, o modelo escolhe os breakpoints, o que funciona bem para casos padrão mas pode ser subótimo quando sua estrutura de prompt não é convencional.

Um detalhe adicional: cache entries não são compartilhadas entre modelos diferentes. Se você cachear um contexto com Claude 3.5 Sonnet e depois mudar para Claude 3.5 Haiku numa chamada de fallback, a entrada de cache não vai ser aproveitada. Para arquiteturas que usam múltiplos modelos como estratégia de custo-latência, isso importa e precisa ser planejado. O tema de como lidar com contextos grandes de forma eficiente em codebases reais tem sobreposição com o que o post sobre gerenciamento de contexto no Claude Code aborda, se você estiver aplicando caching em workflows de desenvolvimento.

A segurança do cache também merece atenção em arquiteturas multi-tenant. Entradas de cache são isoladas por organização ou workspace, mas um system prompt cacheado por um usuário pode servir hits de cache para outro usuário na mesma organização se o prefixo for idêntico. Esse é comportamento esperado e documentado, não uma vulnerabilidade, mas times que operam com dados sensíveis por usuário precisam garantir que o conteúdo cacheado seja genuinamente compartilhável dentro do escopo organizacional definido.

FAQ

O cache funciona entre sessões diferentes de usuários, ou só dentro de uma sessão?

Entradas de cache persistem por até 5 minutos por padrão (1 hora com a opção de TTL estendido) e são acessíveis a qualquer requisição da mesma organização ou workspace que enviar o mesmo prefixo cacheado dentro dessa janela. Não são escopadas por sessão, então um system prompt cacheado pela requisição de um usuário pode servir hits de cache para a requisição de outro usuário na mesma organização, desde que o prefixo seja idêntico. Os detalhes estão na documentação de caching da Anthropic.

Quais modelos do Claude suportam prompt caching?

Segundo a documentação atual da Anthropic, tanto o caching automático quanto o explícito são suportados em todos os modelos Claude ativos, incluindo Claude 3.5 Sonnet, Claude 3.5 Haiku e a família Claude 3. As proporções de pricing (10% para leituras de cache, 125% para escritas) se aplicam consistentemente, embora os preços base de token de input variem por modelo.

Posso cachear definições de ferramentas e exemplos few-shot, além de system prompts?

Sim. O breakpoint cache_control pode ser colocado em qualquer bloco de conteúdo, incluindo definições de ferramentas e trocas de exemplo no array de mensagens. Cachear exemplos few-shot é um dos casos de uso mais eficientes quando esses exemplos são estáveis e o volume de chamadas justifica o custo de escrita. A restrição é que o prefixo cacheado precisa corresponder exatamente: qualquer alteração no conteúdo antes do breakpoint invalida a entrada de cache.

Prompt caching foi projetado em torno de uma aposta específica sobre como sistemas de IA em produção se parecem em escala: contextos estáveis, alto volume de chamadas e padrões de reutilização previsíveis. Quando o seu sistema tem esse perfil, a economia chega rápido e se acumula a cada chamada. Quando não tem, a sobretaxa de escrita é o custo de aprender essa lição antes de redesenhar o workflow.