Cache de prompt

O 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 breakpoint de cache ao último bloco cacheável e o move para frente conforme as conversas crescem. Ideal para conversas de múltiplos turnos em que o histórico crescente de mensagens deve ser armazenado em cache automaticamente.
• Breakpoints 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é o último bloco cacheável, inclusive. 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 breakpoint 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 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 subsequente que reutiliza o mesmo prefixo em cache deve começar dentro de aproximadamente 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:



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 breakpoint de cache ao último bloco cacheável.

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 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 breakpoint 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 no nível de bloco

O cache automático é compatível com breakpoints de cache explícitos. Quando usados juntos, o breakpoint de cache automático usa um dos 4 slots de breakpoint disponíveis.

Isso permite combinar ambas as abordagens. Por exemplo, use um breakpoint explícito para armazenar em cache seu prompt do sistema, enquanto o cache automático gerencia a 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 lookback de 20 blocos se aplicam da mesma forma que com breakpoints 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 breakpoints explícitos no nível de bloco, a API retorna um erro 400 (não há slots restantes para o cache automático).
• Se o último bloco não for elegível como alvo de breakpoint de cache automático, o sistema retrocede silenciosamente para encontrar o bloco elegível mais próximo. Se nenhum for encontrado, o cache é ignorado.



Breakpoints 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 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.

Os prefixos de cache são criados na seguinte ordem: tools, system, 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 breakpoint 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á gravou no cache. Entender como isso funciona ajuda você a otimizar sua estratégia de cache.

Três princípios fundamentais:

1. Gravações de cache acontecem apenas no seu breakpoint. Marcar um bloco com cache_control grava exatamente uma entrada de cache: um hash do prefixo que termina nesse bloco. O sistema não grava entradas para nenhuma posição anterior. Como o hash é cumulativo, cobrindo tudo até o breakpoint inclusive, alterar qualquer bloco no breakpoint 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 gravaram. Em cada requisição, o sistema calcula o hash do prefixo no seu breakpoint e verifica se há uma entrada de cache correspondente. Se não existir nenhuma, 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 gravações 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 breakpoint, contando o próprio breakpoint 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 breakpoint 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, breakpoint no bloco 10. Não existem entradas de cache anteriores. O sistema grava uma entrada no bloco 10.
• Turno 2: 15 blocos, breakpoint 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. Cache hit 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, breakpoint 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á cache hit. Adicionar um segundo breakpoint no bloco 15 inicia uma segunda janela de lookback ali, que encontra a entrada do turno 2.

Erro comum: Breakpoint 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 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 gravou uma entrada em nenhuma dessas posições. Nenhum cache hit. Você paga por uma nova gravação 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 breakpoint e o armazena em cache. Ele encontra entradas que requisições anteriores já gravaram, e gravações acontecem apenas em breakpoints. Mova cache_control para o bloco 5, o último bloco que permanece igual entre requisições, e cada requisição subsequente lerá o prefixo em cache. O cache automático cai na mesma armadilha: ele coloca o breakpoint no último bloco cacheável, que nesta estrutura é aquele que muda a cada requisição, então use um breakpoint 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 gravação anterior. Para um prompt com um sufixo variável (timestamps, contexto por requisição, a mensagem recebida), coloque o breakpoint no final do prefixo estático, não no bloco variável.



Quando usar múltiplos breakpoints

Você pode definir até 4 breakpoints 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 cache hit quando uma conversa crescente empurra seu breakpoint 20 ou mais blocos além da última gravação de cache



Entendendo os custos de breakpoints de cache

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

• Gravações de cache: Quando novo conteúdo é gravado 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 breakpoints 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 breakpoints 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 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 Google Cloud), Claude Opus 4 (desativado, exceto no Google Cloud) e Claude Sonnet 4 (desativado, exceto no Bedrock e Google Cloud)
• 4.096 tokens para Claude Haiku 4.5
• 2.048 tokens para Claude Haiku 3.5 (desativado, exceto no Bedrock e Google Cloud)

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

Prompts mais curtos não podem ser armazenados em cache, mesmo se marcados com cache_control. Qualquer requisição para armazenar em cache menos que esse número de tokens será processada 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 cache hits 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 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 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, 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.

• Blocos de subconteú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. Alterações 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 alterações. ✘ 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 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 breakpoint de cache).



Cache com blocos de pensamento

Ao usar pensamento 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 geralmente 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 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, Claude Platform on AWS e Microsoft Foundry; Bedrock e Google Cloud usam apenas isolamento no nível da organização.

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

• 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 breakpoints automaticamente.
• Use breakpoints explícitos no 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 breakpoints de cache estrategicamente para separar diferentes seções de prefixo cacheáveis.
• Coloque o breakpoint 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 cache hit 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 detalhados: Compartilhe listas extensas de instruções, procedimentos e exemplos para ajustar as respostas do Claude. Desenvolvedores geralmente 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 alterações 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 os usuários façam perguntas.



Solucionando problemas comuns

Se estiver enfrentando comportamento inesperado:

• Certifique-se de que as seções em cache são idênticas entre chamadas. Para breakpoints 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, uso de imagens, a configuração de pensamento e output_config.effort 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 breakpoint está em um bloco que permanece idêntico entre requisições. Gravações de cache acontecem apenas no breakpoint, 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 breakpoint; ele apenas encontra entradas que requisições anteriores gravaram em seus próprios breakpoints
• 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 os caches
• Use diagnósticos 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 cache_creation_input_tokens atual é igual à soma dos valores no objeto cache_creation.

Se você vir gravações de ephemeral_5m_input_tokens que não solicitou ao usar ferramentas de servidor como 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, porque ele continuará sendo renovado 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 do que 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 além de 5 minutos.
• Quando você quer melhorar a utilização do seu limite de taxa, porque cache hits 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 qualquer entrada 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 cache hit mais alto (ou 0 se não houver hits).
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 de cache de 1 hora para (B - A).
3. Tokens de gravação de 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 cache hits e cache misses. Cada uma tem um preço calculado diferente, mostrado nas caixas coloridas, como resultado.



Pré-aquecendo o cache

O pré-aquecimento de cache permite que você carregue 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 cache miss 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 "cache_control breakpoint" (ponto de interrupção de cache_control), depois 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 de 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 placeholder. Caso contrário, a entrada de cache é associada ao placeholder e a requisição subsequente não a encontrará. 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), então um pré-aquecimento com uma configuração diferente pode gravar uma entrada que seu tráfego real nunca encontra. 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-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), depois envie requisições reais de usuários após o pré-aquecimento ser concluído:

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()

# Mais tarde, 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 maiores entre requisições de usuários, 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 gravada durante o processamento em lote provavelmente expiraria antes da requisição subsequente ser executada.



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 é preferida: 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 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 Claude API, Claude Platform on AWS e 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