Cache de prompt

O "prompt caching" (cache de prompt) otimiza seu uso da API ao permitir a retomada 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.

Há 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 armazenável em cache e o move adiante à medida que as conversas crescem. Ideal para conversas de múltiplos turnos em que 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-5",
    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 armazenável em cache. 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 o 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 a partir 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 referência
• Tarefas repetitivas com instruções consistentes
• Longas conversas de múltiplos turnos

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

O tempo de vida é medido a partir do início da requisição que grava ou lê a entrada de cache, não a partir do fim de sua resposta. O tempo gasto gerando uma resposta conta contra o tempo de vida: se uma resposta leva 4 minutos para ser transmitida via streaming, uma requisição de acompanhamento que reutilize o mesmo prefixo em cache deve começar dentro de cerca de 1 minuto após a conclusão dessa resposta.

Preços

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

^{1 Acertos e atualizações de cache no Claude Fable 5.1 e no Claude Mythos 5.1 são cobrados a 0,025x o preço de entrada base. Todos os outros modelos usam o multiplicador padrão de 0,1x.}

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 armazenável em cache.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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 à medida que as conversas crescem. Cada nova requisição armazena em cache tudo até o último bloco armazenável em cache, e o conteúdo anterior é lido do cache.

O ponto de interrupção de cache move-se automaticamente para o último bloco armazenável em cache em cada requisição, portanto você não precisa atualizar nenhum marcador cache_control à medida que 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 por 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 ponto de interrupção disponíveis.

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

{
  "model": "claude-opus-5",
  "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 retrospecção 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 já existirem 4 pontos de interrupção explícitos em nível de bloco, a API retorna um erro 400 (não restam slots para o 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 ter 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 do 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.

Os prefixos de cache são criados na seguinte ordem: tools, system e depois messages. Essa ordem forma uma hierarquia em que 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 fim do seu conteúdo estático, e o sistema encontrará automaticamente o prefixo mais longo que uma requisição anterior já gravou no cache. Entender como isso funciona ajuda você a otimizar sua estratégia de cache.

Três princípios fundamentais:

1. Gravações em cache acontecem apenas no seu ponto de interrupção. Marcar um bloco com cache_control grava exatamente uma entrada de cache: um hash do prefixo que termina naquele bloco. O sistema não grava 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 olham para trás em busca de entradas que requisições anteriores gravaram. 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 nenhuma, ele retrocede um bloco de cada vez, verificando se o hash do prefixo em cada posição anterior corresponde a algo já no cache. Ele está procurando gravações anteriores, não conteúdo estável.

3. A janela de retrospecção é 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 é retomada a partir do próximo ponto de interrupção explícito, se houver). Na Claude API, uma sequência de blocos tool_use consecutivos conta como uma posição, assim como uma sequência de blocos tool_result consecutivos, portanto um turno com muitas chamadas de ferramentas paralelas não empurra, por si só, a entrada da requisição anterior para fora da janela.

Exemplo: Retrospecção em uma conversa crescente

Você acrescenta 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 grava 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 grava 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, portanto não há acerto de cache. Adicionar um segundo ponto de interrupção no bloco 15 inicia uma segunda janela de retrospecção 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: Gravação em 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. A retrospecção percorre os blocos 5, 4, 3, 2 e 1, mas o sistema nunca gravou uma entrada em nenhuma dessas posições. Nenhum acerto de cache. Você paga por uma nova gravação em cache a cada requisição e nunca obtém uma leitura.

A retrospecção não encontra conteúdo estável atrás do seu ponto de interrupção e o armazena em cache. Ela encontra entradas que requisições anteriores já gravaram, e gravações acontecem apenas em pontos de interrupção. Mova cache_control para o bloco 5, o último bloco que permanece igual entre requisições, e toda requisição subsequente lerá o prefixo em cache. O cache automático cai na mesma armadilha: ele coloca o ponto de interrupção no último bloco armazenável em cache, que nessa estrutura é aquele que muda a cada requisição, portanto 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ê deseja 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 a retrospecção da próxima requisição encontra a gravação anterior. Para um prompt com um sufixo variável (timestamps, contexto por requisição, a mensagem recebida), coloque o ponto de interrupção no fim 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 gravação em cache

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

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

• Gravações em cache: Quando novo conteúdo é gravado no cache (25% a mais que os tokens de entrada base para TTL de 5 minutos)
• Leituras de cache: Quando o conteúdo em cache é usado (10% do preço base de tokens de entrada, ou 2,5% no Claude Fable 5.1 e Claude Mythos 5.1)
• 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 dão a você controle sobre quais seções podem ser armazenadas em cache de forma independente.

Estratégias e considerações de cache

Limitações do cache

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

• 512 tokens para Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5, 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 (desativado, exceto no Bedrock e no Google Cloud), Claude Opus 4 (desativado, exceto no Google Cloud) e Claude Sonnet 4 (desativado, exceto no Bedrock e no Google Cloud)
• 4.096 tokens para Claude Haiku 4.5
• 2.048 tokens para Claude Haiku 3.5 (desativado, exceto no Bedrock e no Google Cloud)

Esses mínimos se aplicam em todas as plataformas em que cada modelo está disponível.

Prompts mais curtos não podem ser armazenados em cache, mesmo se marcados com cache_control. Quaisquer requisições para armazenar em cache menos do 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 do que tokens de entrada não armazenados em cache, portanto 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ê precisa de acertos de cache para requisições paralelas, aguarde a primeira resposta antes de enviar as requisições subsequentes.

Atualmente, "ephemeral" é o único tipo de cache suportado, que por padrão tem um tempo de vida 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 do sistema: Blocos de conteúdo no array system
• Mensagens de texto: Blocos de conteúdo no array messages.content, tanto em turnos do usuário quanto do assistente
• Imagens e documentos: Blocos de conteúdo no array messages.content, em turnos do usuário
• Uso de ferramentas e resultados de ferramentas: Blocos de conteúdo no array messages.content, tanto em turnos do usuário quanto do 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 da requisição possa ser armazenada em cache, há 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 as citações podem ser armazenados em cache. Isso permite que você use o 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. Alterações em cada nível invalidam aquele nível e todos os níveis subsequentes.

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

Acompanhando o desempenho do cache

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

• cache_creation_input_tokens: Número de tokens gravados 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).

Cache com blocos de pensamento

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

Cache automático junto com outro conteúdo: Embora os blocos de pensamento não possam ser marcados explicitamente com cache_control, eles são armazenados em cache como parte do conteúdo da requisição quando você faz chamadas subsequentes à API com resultados de ferramentas. Isso acontece comumente durante o uso de ferramentas, quando você passa os 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 o cálculo de custos e o 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 do usuário
• No Opus 4.5+ e Sonnet 4.6+, os blocos de pensamento são preservados por padrão mesmo quando conteúdo de usuário que não é resultado de ferramenta é adicionado, portanto o cache permanece válido
• Em modelos Opus/Sonnet anteriores e em 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 em 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+, os blocos de pensamento anteriores são mantidos por padrão e permanecem parte do prefixo em cache.

Para informações mais detalhadas, consulte Pensamento e cache de prompt.

Armazenamento e compartilhamento de cache

• Isolamento de organização e workspace: Os caches são isolados entre organizações. Organizações diferentes nunca compartilham caches, mesmo que usem prompts idênticos. Os caches também são isolados por workspace dentro de uma organização na Claude API, no Claude Platform on AWS e no Microsoft Foundry; o Bedrock e o Google Cloud usam 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 controle de cache.

• Geração de tokens de saída: O cache de prompt não tem efeito sobre a 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 um cache eficaz

Para otimizar o desempenho do cache de prompt:

• Comece com o cache automático para conversas de múltiplos turnos. Ele cuida do gerenciamento de 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 alteração.
• Armazene em cache conteúdo estável e reutilizável, como instruções do sistema, informações de referência, grandes contextos ou definições de ferramentas frequentes.
• Coloque o 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 armazenáveis em cache.
• 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), esse é o fim 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 codificação: Melhore o autocompletar e as 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 longo completo, incluindo imagens, no seu prompt sem aumentar a latência da resposta.
• Conjuntos de instruções detalhados: 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 o cache de prompt você pode obter um desempenho ainda melhor incluindo mais de 20 exemplos diversos de respostas de alta qualidade.
• Uso de ferramentas agêntico: Melhore o desempenho em cenários que envolvem múltiplas chamadas de ferramentas e alterações iterativas de código, em que cada etapa normalmente requer uma nova chamada à API.
• Converse com livros, artigos, documentação, transcrições de podcasts e outros conteúdos longos: Dê vida a qualquer base de conhecimento incorporando o(s) documento(s) inteiro(s) no prompt e permitindo que os usuários façam perguntas a ele.

Solucionando problemas comuns

Se estiver enfrentando comportamento inesperado:

• Garanta que as seções em cache sejam idênticas entre as 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 do tempo de vida do cache (5 minutos por padrão)
• Verifique se tool_choice, o uso de imagens, a configuração de pensamento e output_config.effort permanecem consistentes entre as 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 do cache)
• Confirme que seu ponto de interrupção está em um bloco que permanece idêntico entre requisições. Gravações em cache acontecem apenas no ponto de interrupção, e se esse bloco muda (timestamps, contexto por requisição, a mensagem recebida), o hash do prefixo nunca corresponde. A retrospecção não encontra conteúdo estável atrás do ponto de interrupção; ela só encontra entradas que requisições anteriores gravaram 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 para JSON, quebrando os caches
• Use o diagnóstico de cache para fazer a API comparar requisições consecutivas e relatar 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 inclui 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 gravações ephemeral_5m_input_tokens que não solicitou ao usar ferramentas de servidor como a busca na web, consulte Uso de ferramentas com cache de prompt.

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 do que a cada 5 minutos), continue usando o cache de 5 minutos, pois ele continuará sendo renovado sem custo adicional.

O cache de 1 hora é mais indicado nos seguintes cenários:

• Quando você tem prompts que provavelmente são usados com menos frequência do que a cada 5 minutos, mas com mais frequência do 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 após 5 minutos.
• Quando você deseja melhorar a utilização do seu limite de taxa, pois 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 de 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 posições de cobrança no seu prompt:

1. Posição A: A contagem de tokens no acerto de cache mais alto (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 não existir nenhum).
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 gravação em cache de 1 hora para (B - A).
3. Tokens de gravação em cache de 5 minutos para (C - B).

Aqui estão três 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é-aquecimento do cache

O "cache pre-warming" (pré-aquecimento do cache) permite que você carregue seu prompt do sistema ou definições de ferramentas no cache de prompt antes que um usuário dispare uma requisição real. Isso elimina a penalidade de latência por 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 grava o cache em qualquer ponto de interrupção cache_control, e 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 subsequente (normalmente seu prompt do sistema ou definições de ferramentas), não na mensagem de usuário de placeholder. Caso contrário, a entrada de cache fica associada ao placeholder e a requisição subsequente não a atingirá. Use também a mesma configuração de thinking e output_config.effort das suas requisições subsequentes: esses valores são renderizados no prompt (consulte O que invalida o cache), portanto um pré-aquecimento com uma configuração diferente pode gravar uma entrada que seu tráfego real nunca atinge. Isso significa usar um ponto de interrupção de cache explícito em vez do 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 de placeholder pode ser qualquer string com conteúdo que não seja apenas espaços 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-5",
    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-5",
  "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) e, em seguida, envie as requisições reais dos usuários após a conclusão do pré-aquecimento:

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-5",
        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-5",
        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 enviar uma mensagem, o prefixo do prompt do sistema já estará em cache.
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.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 mais longos entre requisições de usuários, use a duração de cache de 1 hora.

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, que não se aplica ao processamento em lote, e uma entrada de cache gravada 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, portanto 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:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents.",
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?",
        }
    ],
)
print(response.usage.model_dump_json())

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": { "location": { "type": "string" } },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": { "timezone": { "type": "string" } },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        # ...longa conversa até agora
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ],
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Good to know."},
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"},
                },
            ],
        },
    ],
)
print(response.usage.model_dump_json())

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"}
                },
                "required": ["query"],
            },
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {"type": "string", "description": "Document ID"}
                },
                "required": ["doc_id"],
            },
            "cache_control": {"type": "ephemeral"},
        },
    ],
    system=[
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"},
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"},
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
                }
            ],
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
    ],
)
print(response.usage.model_dump_json())

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 nem as respostas do Claude.

As representações de cache KV (key-value, ou chave-valor) e os hashes criptográficos do conteúdo em cache são mantidos apenas em memória e não são armazenados em repouso. As 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. As entradas de cache são isoladas entre organizações e, na Claude API, na Claude Platform on AWS e no Microsoft Foundry, entre workspaces dentro de uma organização.

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

Perguntas frequentes

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

client.beta.prompt_caching.messages.create(**params)

client.messages.create(**params)

client.beta.promptCaching.messages.create(/* ... */);

client.messages.create(/* ... */);