Prompt caching: o que a Anthropic documenta

Se você manda o mesmo bloco de contexto — um system prompt grande, uma base de exemplos, um histórico de conversa — em toda chamada de API para um LLM, está pagando para o modelo reler aquilo do zero a cada vez. Prompt caching existe para cortar esse desperdício. Na Anthropic, a documentação oficial detalha bem o mecanismo, o TTL e o pricing. Na OpenAI, a página equivalente simplesmente não trouxe conteúdo técnico utilizável nesta pesquisa. Vou separar o que é fato documentado do que é lacuna, sem inventar o que falta.

Por que isso importa no seu custo e na sua latência

Em pipelines de IA que reenviam contexto repetido — RAG com o mesmo conjunto de documentos, agentes com o mesmo conjunto de tools, chatbots com histórico longo — o custo de input token domina a conta. Cache reduz tempo de processamento e custo para esses prefixos repetidos, porque o provedor reaproveita o estado já processado em vez de recomputar do zero (Anthropic, prompt caching).

O ganho é maior quanto mais previsível for o seu padrão de uso: mesmo prefixo, chamadas frequentes dentro da janela de TTL. Se cada chamada tem um contexto diferente, cache não ajuda — só adiciona complexidade.

Como a Anthropic implementa

Dois jeitos de habilitar

A Anthropic oferece dois métodos:

• Automatic caching: você adiciona um único campo cache_control no nível superior da requisição. O sistema aplica o breakpoint de cache automaticamente no último bloco "cacheável" e vai movendo esse breakpoint conforme a conversa cresce. É o caminho recomendado para conversas multi-turno, porque você não precisa recalcular manualmente onde cortar.
• Explicit cache breakpoints: você marca cache_control em blocos de conteúdo específicos, com controle granular sobre o que entra no cache.

Em ambos os casos, o cache referencia o prefixo completo da requisição, nesta ordem: tools, system e messages, até e incluindo o bloco marcado.

O fluxo de checagem é direto: o sistema verifica se aquele prefixo já está cacheado de uma query recente. Se sim, usa a versão cacheada e reduz tempo e custo. Se não, processa o prompt inteiro e cacheia o prefixo no momento em que a resposta começa a ser gerada.

Exemplo de uso (sintaxe conforme a documentação oficial — não testado neste ambiente):

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works...",
    messages=[{"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}],
)
print(response.usage.model_dump_json())

Casos de uso em que isso faz diferença real, segundo a documentação: prompts com muitos exemplos (few-shot), grandes volumes de contexto de background, tarefas repetitivas com instruções fixas, e conversas multi-turno longas.

TTL: a janela de 5 minutos que você precisa respeitar

O padrão é um cache com TTL de 5 minutos, renovado sem custo adicional cada vez que o conteúdo cacheado é reutilizado. O detalhe que costuma pegar quem não lê a letra pequena: a contagem do TTL começa no início da requisição que escreve ou lê a entrada de cache — não no fim da resposta.

Isso importa em streaming de respostas longas. Se uma resposta leva 4 minutos para ser transmitida, a próxima requisição que quer reaproveitar o mesmo prefixo cacheado precisa chegar em cerca de 1 minuto após o fim dessa resposta, para caber dentro da janela de 5 minutos. Em pipelines com geração longa e chamadas sequenciais, vale desenhar o fluxo considerando essa janela, em vez de assumir que o cache "fica disponível por 5 minutos a partir de quando a resposta terminou".

A documentação também menciona uma opção de cache de 1 hora, por custo adicional, descrita em uma seção separada que não foi extraída por completo nesta pesquisa — trate como algo a confirmar na doc antes de decidir usar.

Pricing: escrever cache custa mais, acertar custa muito menos

A tabela de preços por milhão de tokens (MTok) trazida pela documentação, com os nomes de modelo como apareceram na fonte consultada:

O padrão é consistente entre os modelos: escrever no cache custa mais caro que o input base (algo entre 25% e 50% mais caro para escrita de 5 minutos, e ainda mais para 1 hora), mas um hit custa uma fração pequena do input base — na faixa de 10% a 25% do preço normal, dependendo do modelo. Isso significa que cache só compensa financeiramente quando você reaproveita o mesmo prefixo mais de uma vez dentro da janela de TTL. Uma única leitura sem reuso é prejuízo líquido, porque você paga o prêmio de escrita sem nunca colher o desconto do hit.

A tabela da fonte consultada foi cortada após Haiku 5.5, com uma referência a "modelos adicionais" sem detalhamento — então não dá para garantir que essa é a lista completa de modelos com cache suportado hoje. Vale confirmar direto na página oficial antes de orçar custo para um modelo que não está nesta tabela.

Há também menção a "zero data retention (ZDR)" e seu impacto sobre prompt caching, remetendo a uma página separada sobre retenção de dados na API, cujo conteúdo não foi extraído aqui. Se seu ambiente tem requisito de ZDR (comum em contextos regulados), isso precisa ser verificado antes de habilitar cache em produção — não assuma que cache e ZDR são compatíveis sem checar.

OpenAI: a lacuna que não vou fingir que não existe

A pesquisa para este post tentou extrair o conteúdo de platform.openai.com/docs/guides/prompt-caching e o resultado foi, na prática, inútil: o que veio foi o menu de navegação do site de documentação da OpenAI — uma lista de links para outras páginas (Agents, Tools, Realtime, Fine-tuning, Evals, Safety etc.) — sem nenhum texto explicativo, exemplo de código, TTL ou tabela de preços sobre prompt caching.

Isso significa que, neste material, não há nenhum fato técnico concreto sobre como a OpenAI implementa cache de prompt: não sei se o mecanismo é automático, se existe TTL configurável, se há desconto equivalente ao "hit" da Anthropic, nem a estrutura de preços. Qualquer afirmação comparativa específica seria invenção, e não vou fazer isso.

O que se sabe, de forma geral e pública (sem entrar em números), é que a OpenAI oferece prompt caching automático para prefixos repetidos em alguns modelos — mas confirmar mecanismo, TTL e desconto exige ir direto à documentação oficial no momento em que você for implementar, porque este resumo não sustenta esses detalhes.

Critérios práticos para decidir se cache vale a pena

Com o que está documentado para a Anthropic, alguns critérios objetivos para decidir:

• Frequência de reuso dentro do TTL: se o mesmo prefixo é chamado mais de uma vez em menos de 5 minutos (ou 1 hora, no plano pago), cache tende a compensar. Se o intervalo entre chamadas repetidas é maior que o TTL, você paga o prêmio de escrita sem nunca acertar o hit.
• Tamanho do prefixo fixo: contextos grandes e estáveis (documentação de referência, exemplos few-shot, instruções de sistema longas) se beneficiam mais do que prompts curtos e variáveis.
• Padrão de conversa: multi-turno longo favorece o automatic caching, porque o breakpoint se move sozinho conforme a conversa cresce.
• Requisitos de retenção de dados: se seu ambiente exige zero data retention, verifique a compatibilidade antes de habilitar — a própria documentação sinaliza que há implicações aqui.

Recomendação condicionada

Se o seu caso é RAG ou agente com contexto fixo reusado em alta frequência, habilite prompt caching na Anthropic usando automatic caching para conversas multi-turno e explicit breakpoints quando precisar de controle fino sobre o que é cacheado. Monitore usage na resposta para confirmar que está acertando hits, não só escrevendo cache.

Se seu volume de chamadas repetidas dentro da janela de TTL é baixo, ou se o contexto muda a cada chamada, não force cache — o prêmio de escrita vira custo extra sem retorno.

Para OpenAI, a decisão não pode ser tomada com base neste material: antes de implementar, consulte a documentação oficial atualizada diretamente, porque a extração usada aqui não trouxe mecanismo, TTL nem preços.

Premissas e limitações

Este post usa como base a documentação pública da Anthropic acessada em outubro de 2026, com a tabela de preços cortada após o modelo Haiku 5.5 (há menção a "modelos adicionais" sem detalhe). O exemplo de código Python não foi executado neste ambiente — valide a sintaxe atual na documentação antes de rodar em produção. A seção sobre cache de 1 hora e sobre compatibilidade com zero data retention remete a páginas que não foram totalmente extraídas; trate como ponto a confirmar, não como fato fechado. Para a OpenAI, a fonte consultada não retornou conteúdo técnico sobre prompt caching — qualquer decisão sobre a implementação dela exige consulta direta à documentação oficial no momento da implementação.

Próximo passo prático: se você já usa a API da Anthropic com prefixos repetidos, adicione cache_control numa chamada de teste, leia o campo usage da resposta e confirme se está vendo hits antes de assumir que o cache está economizando alguma coisa.