Cache de prompt

O "prompt caching" (cache de prompt) otimiza o uso da API permitindo retomar a partir de prefixos específicos em seus prompts. Isso reduz significativamente o tempo de processamento e os custos para tarefas repetitivas ou prompts com elementos consistentes.

Existem duas maneiras de habilitar o cache de prompt:

• Cache automático: Adicione um único campo cache_control no nível superior da sua requisição. O sistema aplica automaticamente o ponto de interrupção de cache ao último bloco cacheável e o move para frente conforme as conversas crescem. Ideal para conversas de múltiplos turnos onde o histórico crescente de mensagens deve ser armazenado em cache automaticamente.
• Pontos de interrupção de cache explícitos: Coloque cache_control diretamente em blocos de conteúdo individuais para ter controle refinado sobre exatamente o que é armazenado em cache.

A maneira mais simples de começar é com o cache automático:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

Com o cache automático, o sistema armazena em cache todo o conteúdo até e incluindo o último bloco cacheável. Em requisições subsequentes com o mesmo prefixo, o conteúdo em cache é reutilizado automaticamente.



Como o cache de prompt funciona

Quando você envia uma requisição com cache de prompt habilitado:

1. O sistema verifica se um prefixo de prompt, até um ponto de interrupção de cache especificado, já está em cache de uma consulta recente.
2. Se encontrado, ele usa a versão em cache, reduzindo o tempo de processamento e os custos.
3. Caso contrário, ele processa o prompt completo e armazena o prefixo em cache assim que a resposta começa.

Isso é especialmente útil para:

• Prompts com muitos exemplos
• Grandes quantidades de contexto ou informações de fundo
• Tarefas repetitivas com instruções consistentes
• Conversas longas de múltiplos turnos

Por padrão, o cache tem uma vida útil de 5 minutos. O cache é atualizado sem custo adicional cada vez que o conteúdo em cache é usado.



Preços

O cache de prompt introduz uma nova estrutura de preços. A tabela abaixo mostra o preço por milhão de tokens para cada modelo suportado:



Modelos suportados

O cache de prompt (tanto automático quanto explícito) é suportado em todos os modelos Claude ativos.



Cache automático

O cache automático é a maneira mais simples de habilitar o cache de prompt. Em vez de colocar cache_control em blocos de conteúdo individuais, adicione um único campo cache_control no nível superior do corpo da sua requisição. O sistema aplica automaticamente o ponto de interrupção de cache ao último bloco cacheável.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())



Como o cache automático funciona em conversas de múltiplos turnos

Com o cache automático, o ponto de cache avança automaticamente conforme as conversas crescem. Cada nova requisição armazena em cache tudo até o último bloco cacheável, e o conteúdo anterior é lido do cache.

O ponto de interrupção de cache se move automaticamente para o último bloco cacheável em cada requisição, então você não precisa atualizar nenhum marcador cache_control conforme a conversa cresce.



Suporte a TTL

Por padrão, o cache automático usa um TTL de 5 minutos. Você pode especificar um TTL de 1 hora a 2x o preço base de tokens de entrada:

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }



Combinando com cache em nível de bloco

O cache automático é compatível com pontos de interrupção de cache explícitos. Quando usados juntos, o ponto de interrupção de cache automático usa um dos 4 slots de pontos de interrupção disponíveis.

Isso permite combinar ambas as abordagens. Por exemplo, use um ponto de interrupção explícito para armazenar em cache seu prompt do sistema, enquanto o cache automático gerencia a conversa:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}



O que permanece igual

O cache automático usa a mesma infraestrutura de cache subjacente. Preços, limites mínimos de tokens, requisitos de ordenação de contexto e a janela de lookback de 20 blocos se aplicam da mesma forma que com pontos de interrupção explícitos.



Casos extremos

• Se o último bloco já tiver um cache_control explícito com o mesmo TTL, o cache automático não tem efeito.
• Se o último bloco tiver um cache_control explícito com um TTL diferente, a API retorna um erro 400.
• Se 4 pontos de interrupção explícitos em nível de bloco já existirem, a API retorna um erro 400 (não há slots restantes para cache automático).
• Se o último bloco não for elegível como alvo de ponto de interrupção de cache automático, o sistema retrocede silenciosamente para encontrar o bloco elegível mais próximo. Se nenhum for encontrado, o cache é ignorado.



Pontos de interrupção de cache explícitos

Para mais controle sobre o cache, você pode colocar cache_control diretamente em blocos de conteúdo individuais. Isso é útil quando você precisa armazenar em cache diferentes seções que mudam em frequências diferentes, ou precisa de controle refinado sobre exatamente o que é armazenado em cache.



Estruturando seu prompt

Coloque conteúdo estático (definições de ferramentas, instruções de sistema, contexto, exemplos) no início do seu prompt. Marque o fim do conteúdo reutilizável para cache usando o parâmetro cache_control.

Prefixos de cache são criados na seguinte ordem: tools, system, depois messages. Essa ordem forma uma hierarquia onde cada nível se baseia nos anteriores.



Como funciona a verificação automática de prefixo

Você pode usar apenas um ponto de interrupção de cache no final do seu conteúdo estático, e o sistema encontrará automaticamente o prefixo mais longo que uma requisição anterior já escreveu no cache. Entender como isso funciona ajuda a otimizar sua estratégia de cache.

Três princípios fundamentais:

1. Escritas de cache acontecem apenas no seu ponto de interrupção. Marcar um bloco com cache_control escreve exatamente uma entrada de cache: um hash do prefixo que termina nesse bloco. O sistema não escreve entradas para nenhuma posição anterior. Como o hash é cumulativo, cobrindo tudo até e incluindo o ponto de interrupção, alterar qualquer bloco no ponto de interrupção ou antes dele produz um hash diferente na próxima requisição.

2. Leituras de cache procuram para trás por entradas que requisições anteriores escreveram. Em cada requisição, o sistema calcula o hash do prefixo no seu ponto de interrupção e verifica se há uma entrada de cache correspondente. Se não existir, ele retrocede um bloco por vez, verificando se o hash do prefixo em cada posição anterior corresponde a algo já no cache. Ele está procurando por escritas anteriores, não por conteúdo estável.

3. A janela de lookback é de 20 blocos. O sistema verifica no máximo 20 posições por ponto de interrupção, contando o próprio ponto de interrupção como a primeira. Se o sistema não encontrar nenhuma entrada correspondente nessa janela, a verificação para (ou retoma a partir do próximo ponto de interrupção explícito, se houver).

Exemplo: Lookback em uma conversa crescente

Você anexa novos blocos a cada turno e define cache_control no bloco final de cada requisição:

• Turno 1: 10 blocos, ponto de interrupção no bloco 10. Não existem entradas de cache anteriores. O sistema escreve uma entrada no bloco 10.
• Turno 2: 15 blocos, ponto de interrupção no bloco 15. O bloco 15 não tem entrada, então o sistema retrocede até o bloco 10 e encontra a entrada do turno 1. Acerto de cache no bloco 10; o sistema processa apenas os blocos 11 a 15 do zero e escreve uma nova entrada no bloco 15.
• Turno 3: 35 blocos, ponto de interrupção no bloco 35. O sistema verifica 20 posições (blocos 35 a 16) e não encontra nada. A entrada do turno 2 no bloco 15 está uma posição fora da janela, então não há acerto de cache. Adicionar um segundo ponto de interrupção no bloco 15 inicia uma segunda janela de lookback ali, que encontra a entrada do turno 2.

Erro comum: Ponto de interrupção em conteúdo que muda a cada requisição

Seu prompt tem um grande contexto de sistema estático (blocos 1 a 5) seguido por um bloco por requisição contendo um timestamp e a mensagem do usuário (bloco 6). Você define cache_control no bloco 6:

• Requisição 1: Escrita de cache no bloco 6. O hash inclui o timestamp.
• Requisição 2: O timestamp é diferente, então o hash do prefixo no bloco 6 é diferente. O lookback percorre os blocos 5, 4, 3, 2 e 1, mas o sistema nunca escreveu uma entrada em nenhuma dessas posições. Nenhum acerto de cache. Você paga por uma nova escrita de cache em cada requisição e nunca obtém uma leitura.

O lookback não encontra conteúdo estável atrás do seu ponto de interrupção e o armazena em cache. Ele encontra entradas que requisições anteriores já escreveram, e escritas acontecem apenas em pontos de interrupção. Mova cache_control para o bloco 5, o último bloco que permanece igual entre requisições, e cada requisição subsequente lê o prefixo em cache. O cache automático cai na mesma armadilha: ele coloca o ponto de interrupção no último bloco cacheável, que nesta estrutura é aquele que muda a cada requisição, então use um ponto de interrupção explícito no bloco 5 em vez disso.

Conclusão principal: Coloque cache_control no último bloco cujo prefixo é idêntico entre as requisições que você quer que compartilhem um cache. Em uma conversa crescente, o bloco final funciona desde que cada turno adicione menos de 20 blocos: o conteúdo anterior nunca muda, então o lookback da próxima requisição encontra a escrita anterior. Para um prompt com um sufixo variável (timestamps, contexto por requisição, a mensagem recebida), coloque o ponto de interrupção no final do prefixo estático, não no bloco variável.



Quando usar múltiplos pontos de interrupção

Você pode definir até 4 pontos de interrupção de cache se quiser:

• Armazenar em cache diferentes seções que mudam em frequências diferentes (por exemplo, ferramentas raramente mudam, mas o contexto é atualizado diariamente)
• Ter mais controle sobre exatamente o que é armazenado em cache
• Garantir um acerto de cache quando uma conversa crescente empurra seu ponto de interrupção 20 ou mais blocos além da última escrita de cache



Entendendo os custos de pontos de interrupção de cache

Pontos de interrupção de cache em si não adicionam nenhum custo. Você é cobrado apenas por:

• Escritas de cache: Quando novo conteúdo é escrito no cache (25% a mais que tokens de entrada base para TTL de 5 minutos)
• Leituras de cache: Quando conteúdo em cache é usado (10% do preço base de tokens de entrada)
• Tokens de entrada regulares: Para qualquer conteúdo não armazenado em cache

Adicionar mais pontos de interrupção cache_control não aumenta seus custos - você ainda paga o mesmo valor com base no conteúdo que é realmente armazenado em cache e lido. Os pontos de interrupção simplesmente dão a você controle sobre quais seções podem ser armazenadas em cache independentemente.



Estratégias e considerações de cache



Limitações de cache

Na Claude API, Claude Platform on AWS, Google Cloud e Microsoft Foundry, o comprimento mínimo de prompt cacheável é:

• 512 tokens para Claude Fable 5 e Claude Mythos 5
• 2.048 tokens para Claude Mythos Preview e Claude Opus 4.7
• 4.096 tokens para Claude Opus 4.6 e Claude Opus 4.5
• 1.024 tokens para Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1 (descontinuado), Claude Opus 4 (retirado, exceto no Google Cloud) e Claude Sonnet 4 (retirado, exceto no Bedrock e Google Cloud)
• 4.096 tokens para Claude Haiku 4.5
• 2.048 tokens para Claude Haiku 3.5 (retirado, exceto no Google Cloud)

A disponibilidade de modelos varia por plataforma, assim como o mínimo para modelos recém-lançados: no Amazon Bedrock, o comprimento mínimo de prompt cacheável para Claude Fable 5 e Claude Mythos 5 é de 1.024 tokens.

Prompts mais curtos não podem ser armazenados em cache, mesmo se marcados com cache_control. Quaisquer requisições para armazenar em cache menos que esse número de tokens serão processadas sem cache, e nenhum erro é retornado. Para verificar se um prompt foi armazenado em cache, verifique os campos de uso da resposta: se tanto cache_creation_input_tokens quanto cache_read_input_tokens forem 0, o prompt não foi armazenado em cache (provavelmente porque não atendeu ao requisito de comprimento mínimo).

Se seu prompt ficar um pouco abaixo do mínimo para seu modelo e plataforma, expandir o conteúdo em cache para atingir o limite geralmente vale a pena. Leituras de cache custam significativamente menos que tokens de entrada não armazenados em cache, então atingir o mínimo pode reduzir custos para prompts reutilizados com frequência.

Para requisições concorrentes, observe que uma entrada de cache só fica disponível depois que a primeira resposta começa. Se você precisar de acertos de cache para requisições paralelas, aguarde a primeira resposta antes de enviar requisições subsequentes.

Atualmente, "ephemeral" é o único tipo de cache suportado, que por padrão tem uma vida útil de 5 minutos.



O que pode ser armazenado em cache

A maioria dos blocos na requisição pode ser armazenada em cache. Isso inclui:

• Ferramentas: Definições de ferramentas no array tools
• Mensagens de sistema: Blocos de conteúdo no array system
• Mensagens de texto: Blocos de conteúdo no array messages.content, tanto para turnos de usuário quanto de assistente
• Imagens e Documentos: Blocos de conteúdo no array messages.content, em turnos de usuário
• Uso de ferramentas e resultados de ferramentas: Blocos de conteúdo no array messages.content, tanto em turnos de usuário quanto de assistente

Cada um desses elementos pode ser armazenado em cache, seja automaticamente ou marcando-os com cache_control.



O que não pode ser armazenado em cache

Embora a maioria dos blocos de requisição possa ser armazenada em cache, existem algumas exceções:

• Blocos de pensamento não podem ser armazenados em cache diretamente com cache_control. No entanto, blocos de pensamento PODEM ser armazenados em cache junto com outro conteúdo quando aparecem em turnos anteriores do assistente. Quando armazenados em cache dessa forma, eles CONTAM como tokens de entrada quando lidos do cache.

• Sub-blocos de conteúdo (como citações) em si não podem ser armazenados em cache diretamente. Em vez disso, armazene em cache o bloco de nível superior.

  No caso de citações, os blocos de conteúdo de documento de nível superior que servem como material de origem para citações podem ser armazenados em cache. Isso permite que você use cache de prompt com citações de forma eficaz, armazenando em cache os documentos que as citações referenciarão.

• Blocos de texto vazios não podem ser armazenados em cache.



O que invalida o cache

Modificações no conteúdo em cache podem invalidar parte ou todo o cache.

Conforme descrito em Estruturando seu prompt, o cache segue a hierarquia: tools → system → messages. Mudanças em cada nível invalidam esse nível e todos os níveis subsequentes.

A tabela a seguir mostra quais partes do cache são invalidadas por diferentes tipos de mudanças. ✘ indica que o cache é invalidado, enquanto ✓ indica que o cache permanece válido.



Monitorando o desempenho do cache

Monitore o desempenho do cache usando estes campos de resposta da API, dentro de usage na resposta (ou evento message_start se estiver usando streaming):

• cache_creation_input_tokens: Número de tokens escritos no cache ao criar uma nova entrada.
• cache_read_input_tokens: Número de tokens recuperados do cache para esta requisição.
• input_tokens: Número de tokens de entrada que não foram lidos do cache nem usados para criar um cache (ou seja, tokens após o último ponto de interrupção de cache).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens



Cache com blocos de pensamento

Ao usar pensamento estendido com cache de prompt, blocos de pensamento têm comportamento especial:

Cache automático junto com outro conteúdo: Embora blocos de pensamento não possam ser explicitamente marcados com cache_control, eles são armazenados em cache como parte do conteúdo da requisição quando você faz chamadas de API subsequentes com resultados de ferramentas. Isso comumente acontece durante o uso de ferramentas quando você passa blocos de pensamento de volta para continuar a conversa.

Contagem de tokens de entrada: Quando blocos de pensamento são lidos do cache, eles contam como tokens de entrada nas suas métricas de uso. Isso é importante para cálculo de custos e orçamento de tokens.

Padrões de invalidação de cache:

• O cache permanece válido quando apenas resultados de ferramentas são fornecidos como mensagens de usuário
• No Opus 4.5+ e Sonnet 4.6+, blocos de pensamento são preservados por padrão mesmo quando conteúdo de usuário que não é resultado de ferramenta é adicionado, então o cache permanece válido
• Em modelos Opus/Sonnet anteriores e todos os modelos Haiku, o cache é invalidado quando conteúdo de usuário que não é resultado de ferramenta é adicionado, fazendo com que todos os blocos de pensamento anteriores sejam removidos do contexto
• Esse comportamento de cache ocorre mesmo sem marcadores cache_control explícitos

Para mais detalhes sobre invalidação de cache, consulte O que invalida o cache.

Exemplo com uso de ferramentas:

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

Em modelos Opus/Sonnet anteriores e todos os modelos Haiku, todos os blocos de pensamento anteriores são removidos do contexto neste ponto. No Opus 4.5+ e Sonnet 4.6+, blocos de pensamento anteriores são mantidos por padrão e permanecem parte do prefixo em cache.

Para informações mais detalhadas, consulte a documentação de pensamento estendido.



Armazenamento e compartilhamento de cache

• Isolamento de organização e workspace: Caches são isolados entre organizações. Organizações diferentes nunca compartilham caches, mesmo que usem prompts idênticos. A partir de 5 de fevereiro de 2026, caches também são isolados por workspace dentro de uma organização na Claude API, Claude Platform on AWS e Microsoft Foundry; Bedrock e Google Cloud continuam a usar apenas isolamento em nível de organização.

• Correspondência exata: Acertos de cache exigem segmentos de prompt 100% idênticos, incluindo todo o texto e imagens até e incluindo o bloco marcado com cache control.

• Geração de tokens de saída: O cache de prompt não tem efeito na geração de tokens de saída. A resposta que você recebe é idêntica à que você obteria se o cache de prompt não fosse usado.



Melhores práticas para cache eficaz

Para otimizar o desempenho do cache de prompt:

• Comece com cache automático para conversas de múltiplos turnos. Ele gerencia pontos de interrupção automaticamente.
• Use pontos de interrupção explícitos em nível de bloco quando precisar armazenar em cache diferentes seções com diferentes frequências de mudança.
• Armazene em cache conteúdo estável e reutilizável como instruções de sistema, informações de fundo, contextos grandes ou definições de ferramentas frequentes.
• Coloque conteúdo em cache no início do prompt para melhor desempenho.
• Use pontos de interrupção de cache estrategicamente para separar diferentes seções de prefixo cacheáveis.
• Coloque o ponto de interrupção no último bloco que permanece idêntico entre requisições. Para um prompt com um prefixo estático e um sufixo variável (timestamps, contexto por requisição, a mensagem recebida), isso é o final do prefixo, não o bloco variável.
• Analise regularmente as taxas de acerto de cache e ajuste sua estratégia conforme necessário.



Otimizando para diferentes casos de uso

Adapte sua estratégia de cache de prompt ao seu cenário:

• Agentes conversacionais: Reduza custo e latência para conversas estendidas, especialmente aquelas com instruções longas ou documentos enviados.
• Assistentes de código: Melhore o autocompletar e perguntas e respostas sobre a base de código mantendo seções relevantes ou uma versão resumida da base de código no prompt.
• Processamento de documentos grandes: Incorpore material completo de formato longo, incluindo imagens, no seu prompt sem aumentar a latência de resposta.
• Conjuntos de instruções detalhadas: Compartilhe listas extensas de instruções, procedimentos e exemplos para ajustar as respostas do Claude. Desenvolvedores frequentemente incluem um ou dois exemplos no prompt, mas com cache de prompt você pode obter desempenho ainda melhor incluindo mais de 20 exemplos diversos de respostas de alta qualidade.
• Uso de ferramentas agêntico: Melhore o desempenho para cenários envolvendo múltiplas chamadas de ferramentas e mudanças iterativas de código, onde cada etapa normalmente requer uma nova chamada de API.
• Converse com livros, artigos, documentação, transcrições de podcasts e outros conteúdos de formato longo: Dê vida a qualquer base de conhecimento incorporando o(s) documento(s) inteiro(s) no prompt e permitindo que usuários façam perguntas.



Solucionando problemas comuns

Se estiver experimentando comportamento inesperado:

• Certifique-se de que as seções em cache são idênticas entre chamadas. Para pontos de interrupção explícitos, verifique se os marcadores cache_control estão nos mesmos locais
• Verifique se as chamadas são feitas dentro da vida útil do cache (5 minutos por padrão)
• Verifique se tool_choice e o uso de imagens permanecem consistentes entre chamadas
• Valide que você está armazenando em cache pelo menos o número mínimo de tokens para seu modelo e plataforma (consulte Limitações de cache)
• Confirme que seu ponto de interrupção está em um bloco que permanece idêntico entre requisições. Escritas de cache acontecem apenas no ponto de interrupção, e se esse bloco mudar (timestamps, contexto por requisição, a mensagem recebida), o hash do prefixo nunca corresponde. O lookback não encontra conteúdo estável atrás do ponto de interrupção; ele apenas encontra entradas que requisições anteriores escreveram em seus próprios pontos de interrupção
• Verifique se as chaves nos seus blocos de conteúdo tool_use têm ordenação estável, já que algumas linguagens (por exemplo, Swift, Go) randomizam a ordem das chaves durante a conversão JSON, quebrando caches
• Use diagnósticos de cache para fazer a API comparar requisições consecutivas e reportar qual parte do prompt divergiu



Duração de cache de 1 hora

Se você achar que 5 minutos é muito pouco, a Anthropic também oferece uma duração de cache de 1 hora com custo adicional.

Para usar o cache estendido, inclua ttl na definição de cache_control assim:

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

A resposta incluirá informações detalhadas de cache como as seguintes:

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

Observe que o campo atual cache_creation_input_tokens é igual à soma dos valores no objeto cache_creation.

Se você vir escritas de ephemeral_5m_input_tokens que não solicitou ao usar ferramentas de servidor como busca na web, consulte este guia sobre cache de prompt e uso de ferramentas.



Quando usar o cache de 1 hora

Se você tem prompts que são usados em uma cadência regular (ou seja, prompts do sistema que são usados com mais frequência que a cada 5 minutos), continue a usar o cache de 5 minutos, já que ele continuará a ser atualizado sem custo adicional.

O cache de 1 hora é melhor usado nos seguintes cenários:

• Quando você tem prompts que provavelmente são usados com menos frequência que 5 minutos, mas com mais frequência que a cada hora. Por exemplo, quando um subagente agêntico levará mais de 5 minutos, ou ao armazenar uma longa conversa de chat com um usuário e você geralmente espera que esse usuário possa não responder nos próximos 5 minutos.
• Quando a latência é importante e seus prompts de acompanhamento podem ser enviados além de 5 minutos.
• Quando você quer melhorar a utilização do seu limite de taxa, já que acertos de cache não são deduzidos do seu limite de taxa.



Misturando diferentes TTLs

Você pode usar controles de cache de 1 hora e 5 minutos na mesma requisição, mas com uma restrição importante: Entradas de cache com TTL mais longo devem aparecer antes de TTLs mais curtos (ou seja, uma entrada de cache de 1 hora deve aparecer antes de quaisquer entradas de cache de 5 minutos).

Ao misturar TTLs, a API determina três locais de cobrança no seu prompt:

1. Posição A: A contagem de tokens no maior acerto de cache (ou 0 se não houver acertos).
2. Posição B: A contagem de tokens no bloco cache_control de 1 hora mais alto após A (ou igual a A se nenhum existir).
3. Posição C: A contagem de tokens no último bloco cache_control.

Você será cobrado por:

1. Tokens de leitura de cache para A.
2. Tokens de escrita de cache de 1 hora para (B - A).
3. Tokens de escrita de cache de 5 minutos para (C - B).

Aqui estão 3 exemplos. Isso representa os tokens de entrada de 3 requisições, cada uma com diferentes acertos e falhas de cache. Cada uma tem um preço calculado diferente, mostrado nas caixas coloridas, como resultado.



Pré-aquecendo o cache

O pré-aquecimento de cache permite carregar seu prompt do sistema ou definições de ferramentas no cache de prompt antes que um usuário acione uma requisição real. Isso elimina a penalidade de latência de falha de cache na primeira interação do usuário, reduzindo o "time-to-first-token" (tempo até o primeiro token), ou TTFT, para aplicações sensíveis à latência.



Como funciona

Defina max_tokens: 0 na sua requisição. A API lê seu prompt no modelo e escreve o cache em qualquer ponto de interrupção cache_control, então retorna imediatamente sem gerar nenhuma saída. A resposta tem um array content vazio, stop_reason: "max_tokens" e um bloco usage totalmente preenchido.

Coloque o ponto de interrupção cache_control no último bloco que é compartilhado com a requisição de acompanhamento (normalmente seu prompt do sistema ou definições de ferramentas), não na mensagem de usuário placeholder. Caso contrário, a entrada de cache é vinculada ao placeholder e a requisição de acompanhamento não a encontrará. Isso significa usar um ponto de interrupção de cache explícito em vez de cache automático, já que o cache automático coloca o ponto de interrupção no último bloco, que aqui é o placeholder. A mensagem de usuário placeholder pode ser qualquer string com conteúdo que não seja apenas espaço em branco (os exemplos aqui usam "warmup"); seu conteúdo é lido no modelo mas nunca respondido.

client = anthropic.Anthropic()

# Dispare isto antes da chegada dos usuários para aquecer o cache compartilhado do prompt do sistema.
prewarm = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)  # []
print(prewarm.usage)

A API retorna um array content vazio:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-4-8",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}



Padrão de uso típico

Dispare uma requisição de pré-aquecimento quando sua aplicação iniciar (ou em um intervalo agendado), então envie requisições reais de usuário após o pré-aquecimento completar:

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-4-8",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# Aqueça o cache antes que qualquer tráfego de usuário chegue.
prewarm_cache()

# Depois, quando o usuário envia uma mensagem, o prefixo do prompt do sistema já está em cache.
response = respond("How do I implement a binary search tree?")
print(response.content[0].text)

Tenha em mente que o TTL do cache ainda se aplica. Para o cache padrão de 5 minutos, envie uma nova requisição de pré-aquecimento pelo menos a cada 5 minutos para manter o cache aquecido. Para intervalos maiores entre requisições de usuário, use a duração de cache de 1 hora em vez disso.



Limitações

Uma requisição com max_tokens: 0 é rejeitada com um invalid_request_error se qualquer um dos seguintes estiver definido, já que cada um implica uma saída que um orçamento de zero tokens não pode produzir:

• stream: true
• Pensamento estendido (thinking.type: "enabled")
• Saídas estruturadas (output_config.format)
• tool_choice de {"type": "tool", ...} ou {"type": "any"}

max_tokens: 0 também é rejeitado dentro de uma requisição de Message Batches. O pré-aquecimento visa o tempo até o primeiro token, o que não se aplica ao processamento em lote, e uma entrada de cache escrita durante o processamento em lote provavelmente expiraria antes da execução da requisição subsequente.



Substituindo a solução alternativa max_tokens=1

Antes de max_tokens: 0 estar disponível, algumas aplicações usavam chamadas de aquecimento com max_tokens: 1 para obter o mesmo efeito. A abordagem max_tokens: 0 é preferível: nenhuma saída é produzida, então não há resposta de um único token para descartar, nenhum token de saída é cobrado, e a intenção da requisição é inequívoca.



Exemplos de cache de prompt

Para ajudar você a começar com o cache de prompt, o cookbook de cache de prompt fornece exemplos detalhados e melhores práticas.

Os trechos de código a seguir mostram vários padrões de cache de prompt. Esses exemplos demonstram como implementar o cache em diferentes cenários, ajudando você a entender as aplicações práticas desse recurso:



Retenção de dados

O cache de prompt (tanto automático quanto explícito) é elegível para ZDR. A Anthropic não armazena o texto bruto dos seus prompts ou das respostas do Claude.

Representações de cache KV (chave-valor) e hashes criptográficos do conteúdo em cache são mantidos apenas em memória e não são armazenados em repouso. Entradas em cache têm um tempo de vida mínimo de 5 minutos (padrão) ou 1 hora (estendido), após o qual são excluídas prontamente, embora não imediatamente. Entradas de cache são isoladas entre organizações e, na API do Claude, na Claude Platform na AWS e no Microsoft Foundry, entre workspaces dentro de uma organização.

Para elegibilidade ZDR em todos os recursos, consulte API e retenção de dados.



Perguntas frequentes