Cache de prompt

O "prompt caching" (cache de prompt) otimiza o uso da API ao permitir retomar o processamento a partir de prefixos específicos dos seus prompts. Isso reduz significativamente o tempo de processamento e os custos em tarefas repetitivas ou em 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 solicitação. O sistema aplica automaticamente o "cache breakpoint" (ponto de interrupção de cache) ao último bloco que pode ser armazenado em cache e o move para frente à medida que as conversas crescem. É a melhor opção 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-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 que pode ser armazenado em cache, inclusive. Em solicitações subsequentes com o mesmo prefixo, o conteúdo em cache é reutilizado automaticamente.

Como o cache de prompt funciona

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

1. O sistema verifica se um prefixo do 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 base
• 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 sempre que o conteúdo em cache é usado.

O tempo de vida é medido a partir do início da solicitação que grava ou lê a entrada de cache, e não a partir do fim da 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 solicitação de acompanhamento que reutiliza o mesmo prefixo em cache deve começar em 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 compatível:

Model	Base tokens		Prompt caching
Name	Input	Output	5m writes	1h writes	Hits and refreshes
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work	$4 / MTok	$20 / MTok	$5 / MTok	$8 / MTok	$0.20 / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Haiku 4.5The fastest model with near-frontier intelligence	$1 / MTok	$5 / MTok	$1.25 / MTok	$2 / MTok	$0.10 / MTok
Additional models
Claude Mythos 5.1	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Fable 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Mythos 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Opus 5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.8	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.7	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.6	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.1	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Opus 4	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Sonnet 5	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Sonnet 4.6	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4.5	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Haiku 3.5	$0.80 / MTok	$4 / MTok	$1 / MTok	$1.60 / MTok	$0.08 / MTok

^{1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.}

^{2 Cache hits and refreshes on Claude Opus 5.5 are priced at 0.05x the base input price.}

^{All other models use the standard 0.1x multiplier.}

Modelos compatíveis

O cache de prompt (tanto automático quanto explícito) é compatível com 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 solicitação. O sistema aplica automaticamente o ponto de interrupção de cache ao último bloco que pode ser armazenado em cache.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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 solicitação armazena em cache tudo até o último bloco que pode ser armazenado em cache, e o conteúdo anterior é lido do cache.

O ponto de interrupção de cache se move automaticamente para o último bloco que pode ser armazenado em cache em cada solicitação, então 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 "time to live" (tempo de vida), ou TTL, de 5 minutos. Você pode especificar um TTL de 1 hora por 2x o preço base dos 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 em conjunto, o ponto de interrupção de cache automático ocupa 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-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 há slots restantes 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 seções diferentes que mudam com frequências diferentes, ou precisa de controle refinado sobre exatamente o que é armazenado em cache.

Estruturando seu prompt

Coloque o 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, em seguida, messages. Essa ordem forma uma hierarquia em que cada nível se baseia nos anteriores.

Como funciona a verificação automática de prefixos

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 solicitaçã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 nesse bloco. O sistema não grava entradas para nenhuma posição anterior. Como o hash é cumulativo, cobrindo tudo até o ponto de interrupção, inclusive, alterar qualquer bloco no ponto de interrupção ou antes dele produz um hash diferente na próxima solicitação.

2. Leituras de cache procuram para trás por entradas que solicitações anteriores gravaram. Em cada solicitaçã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 houver, ele retrocede um bloco por vez, verificando se o hash do prefixo em cada posição anterior corresponde a algo que já está no cache. Ele procura gravações anteriores, não conteúdo estável.

3. A "lookback window" (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 recomeça 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, de modo que um turno com muitas chamadas de ferramentas paralelas não empurra, por si só, a entrada da solicitaçã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 solicitaçã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. Há um "cache hit" (acerto de cache) no bloco 10; o sistema processa do zero apenas os blocos 11 a 15 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, então não há acerto de cache. Adicionar um segundo ponto de interrupção no bloco 15 inicia ali uma segunda janela de retrospecção, que encontra a entrada do turno 2.

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

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

• Solicitação 1: Gravação em cache no bloco 6. O hash inclui o timestamp.
• Solicitaçã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. Não há acerto de cache. Você paga por uma nova gravação em cache a cada solicitaçã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 para armazená-lo em cache. Ela encontra entradas que solicitações anteriores já gravaram, e as gravações acontecem apenas nos pontos de interrupção. Mova cache_control para o bloco 5, o último bloco que permanece igual entre as solicitações, e todas as solicitações subsequentes lerão o prefixo em cache. O cache automático cai na mesma armadilha: ele coloca o ponto de interrupção no último bloco que pode ser armazenado em cache, que nessa estrutura é o que muda a cada solicitação, então use um ponto de interrupção explícito no bloco 5 em vez disso.

Ponto principal: Coloque cache_control no último bloco cujo prefixo é idêntico entre as solicitaçõ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 solicitação encontra a gravação anterior. Para um prompt com um sufixo variável (timestamps, contexto por solicitaçã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 seções diferentes que mudam com frequências diferentes (por exemplo, as 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 dos tokens de entrada, ou 2,5% no Claude Fable 5.1 e no Claude Mythos 5.1, e 5% no Claude Opus 5.5)
• Tokens de entrada regulares: Para qualquer conteúdo que não esteja em cache

Adicionar mais pontos de interrupção cache_control não aumenta seus custos; você continua pagando o mesmo valor com base no conteúdo que é efetivamente armazenado e lido do cache. 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, na Claude Platform on AWS, no Google Cloud e no Microsoft Foundry, o comprimento mínimo de prompt que pode ser armazenado em cache é:

• 512 tokens para Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.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 que marcados com cache_control. Quaisquer solicitaçõ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, confira os campos de uso da resposta: se cache_creation_input_tokens e cache_read_input_tokens forem ambos 0, o prompt não foi armazenado em cache (provavelmente porque não atingiu o requisito de comprimento mínimo).

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

Para solicitações simultâneas, 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 solicitações paralelas, aguarde a primeira resposta antes de enviar as solicitações subsequentes.

Atualmente, "ephemeral" é o único tipo de cache compatível, que por padrão tem um tempo de vida de 5 minutos.

O que pode ser armazenado em cache

A maioria dos blocos da solicitaçã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-o com cache_control.

O que não pode ser armazenado em cache

Embora a maioria dos blocos da solicitaçã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) 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 usar 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 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.

Em modelos compatíveis com alterações de ferramentas no meio da conversa, o cabeçalho beta inline-tools-2026-09-15 permite adicionar uma ferramenta, ou alterar a definição de uma ferramenta, no meio de uma conversa sem editar tools. Envie a definição em um bloco tool_addition em uma mensagem do sistema no meio da conversa e deixe tools exatamente como você o enviou pela primeira vez. O prefixo em cache continua correspondendo, então apenas a mensagem acrescentada é processada como nova entrada. A única exceção é um array tools sem nenhuma ferramenta não adiada, em que a primeira ferramenta definida dessa forma custa uma falha completa de cache nessa solicitação. Consulte Definir ferramentas em uma mensagem.

Acompanhando o desempenho do cache

Monitore o desempenho do cache usando estes campos da 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 solicitaçã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 solicitação quando você faz chamadas de API subsequentes com resultados de ferramentas. Isso costuma acontecer durante o uso de ferramentas, quando você devolve os blocos de pensamento 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 do cache:

• O cache permanece válido quando apenas resultados de ferramentas são fornecidos como mensagens do usuário
• No Opus 4.5+ e no Sonnet 4.6+, os blocos de pensamento são preservados por padrão mesmo quando é adicionado conteúdo do usuário que não é resultado de ferramenta, então o cache permanece válido
• Em modelos Opus/Sonnet anteriores e em todos os modelos Haiku, o cache é invalidado quando é adicionado conteúdo do usuário que não é resultado de ferramenta, 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 a invalidação do 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 no Sonnet 4.6+, os blocos de pensamento anteriores são mantidos por padrão e continuam fazendo parte do prefixo em cache.

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

Armazenamento e compartilhamento do cache

• Isolamento por 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, na 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 as imagens até o bloco marcado com controle de cache, inclusive.

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

Práticas recomendadas 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 gerencia os pontos de interrupção automaticamente.
• Use pontos de interrupção explícitos em nível de bloco quando precisar armazenar em cache seções diferentes com frequências de alteração diferentes.
• Armazene em cache conteúdo estável e reutilizável, como instruções do sistema, informações de base, contextos grandes ou definições de ferramentas frequentes.
• Coloque o conteúdo em cache no início do prompt para obter o melhor desempenho.
• Use pontos de interrupção de cache de forma estratégica para separar diferentes seções de prefixo que podem ser armazenadas em cache.
• Coloque o ponto de interrupção no último bloco que permanece idêntico entre as solicitações. Para um prompt com um prefixo estático e um sufixo variável (timestamps, contexto por solicitaçã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 o custo e a "latency" (latência) em conversas longas, especialmente aquelas com instruções extensas ou documentos enviados.
• Assistentes de programação: Melhore o preenchimento automático e as perguntas e respostas sobre a base de código mantendo no prompt as seções relevantes ou uma versão resumida da base de código.
• Processamento de documentos grandes: Incorpore material completo de formato longo, incluindo imagens, no seu prompt sem aumentar a latência da resposta.
• Conjuntos de instruções detalhadas: Compartilhe listas extensas de instruções, procedimentos e exemplos para ajustar as respostas do Claude. Os desenvolvedores costumam incluir 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 exige 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) ao prompt e permitindo que os usuários façam perguntas sobre ele.

Solução de problemas comuns

Se você estiver enfrentando um comportamento inesperado:

• Certifique-se de 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
• Confirme que você está armazenando em cache pelo menos o número mínimo de tokens para o 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 as solicitações. As gravações em cache acontecem apenas no ponto de interrupção e, se esse bloco mudar (timestamps, contexto por solicitação, a mensagem recebida), o hash do prefixo nunca corresponderá. A retrospecção não encontra conteúdo estável atrás do ponto de interrupção; ela só encontra entradas que solicitaçõ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, pois algumas linguagens (por exemplo, Swift, Go) tornam aleatória a ordem das chaves durante a conversão para JSON, quebrando os caches
• Use o diagnóstico de cache para que a API compare solicitações consecutivas e informe qual parte do prompt divergiu

Duração de cache de 1 hora

Se você achar que 5 minutos é pouco tempo, 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 desta forma:

"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 pesquisa 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 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 agente secundário agêntico levará mais de 5 minutos, ou ao armazenar uma longa conversa de chat com um usuário quando 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 depois de 5 minutos.
• Quando você deseja melhorar a utilização do seu limite de taxa, já que os acertos de cache não são descontados do seu limite de taxa.

Misturando TTLs diferentes

Você pode usar controles de cache de 1 hora e de 5 minutos na mesma solicitação, mas com uma restrição importante: entradas de cache com "time to live" (tempo de vida), ou TTL, mais longo devem aparecer antes das entradas com 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 "cache hit" (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 escrita de cache de 1 hora para (B - A).
3. Tokens de escrita de cache de 5 minutos para (C - B).

Aqui estão três exemplos. Isto representa os tokens de entrada de 3 solicitações, cada uma com diferentes cache hits (acertos de cache) e cache misses (falhas de cache). Como resultado, cada uma tem um preço calculado diferente, mostrado nas caixas coloridas.

Pré-aquecendo o cache

O "cache pre-warming" (pré-aquecimento do cache) permite que você carregue seu "system prompt" (prompt do sistema) ou suas definições de ferramentas no cache de prompt antes que um usuário dispare uma solicitação real. Isso elimina a penalidade de "latency" (latência) causada pela 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 solicitação. A API lê seu prompt no modelo e escreve o cache em qualquer "breakpoint" (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 breakpoint cache_control no último bloco que é compartilhado com a solicitação seguinte (normalmente seu prompt do sistema ou suas definições de ferramentas), e não na mensagem de usuário de espaço reservado. Caso contrário, a entrada de cache fica vinculada ao espaço reservado e a solicitação seguinte não a acertará. Use também a mesma configuração de thinking e o mesmo output_config.effort das suas solicitações seguintes: esses valores são renderizados no prompt (consulte O que invalida o cache), então um pré-aquecimento com uma configuração diferente pode escrever uma entrada que seu tráfego real nunca acerta. Isso significa usar um breakpoint de cache explícito em vez do cache automático, já que o cache automático coloca o breakpoint no último bloco, que aqui é o espaço reservado. A mensagem de usuário de espaço reservado 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-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-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 solicitação de pré-aquecimento quando sua aplicação iniciar (ou em um intervalo agendado) e, em seguida, envie as solicitaçõ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-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-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# Aqueça o cache antes que chegue qualquer tráfego de usuários.
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)

Lembre-se de que o TTL do cache continua se aplicando. Para o cache padrão de 5 minutos, envie uma nova solicitação de pré-aquecimento pelo menos a cada 5 minutos para manter o cache aquecido. Para intervalos mais longos entre as solicitações dos usuários, use a duração de cache de 1 hora.

Limitações

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

• stream: true
• "Extended thinking" (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 solicitaçã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 solicitação seguinte.

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 com 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 solicitação é inequívoca.

Exemplos de cache de prompt

Para ajudar você a começar com o "prompt caching" (cache de prompt), o cookbook de cache de prompt fornece exemplos detalhados e boas 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-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-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-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        # ...conversa longa até aqui
        {
            "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-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 "Zero Data Retention" (retenção zero de dados), ou ZDR. A Anthropic não armazena o texto bruto dos seus prompts nem das respostas do Claude.

As representações de cache de "key-value" (chave-valor), ou KV, 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, no Claude Platform on AWS e no Microsoft Foundry, entre workspaces dentro de uma organização.

Para a elegibilidade para 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(/* ... */);