Cache de prompts

O cache de prompts é um recurso poderoso que otimiza seu uso da API permitindo retomar a partir de prefixos específicos em seus prompts. Essa abordagem reduz significativamente o tempo de processamento e os custos para tarefas repetitivas ou prompts com elementos consistentes.

Aqui está um exemplo de como implementar o cache de prompts com a API de Mensagens usando um bloco cache_control:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input

import anthropic

client = anthropic.Anthropic()

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

# Call the model again with the same inputs up to the cache checkpoint
response = client.messages.create(.....)
print(response.usage.model_dump_json())

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
    },
    {
      type: "text",
      text: "<the entire contents of 'Pride and Prejudice'>",
      cache_control: { type: "ephemeral" }
    }
  ],
  messages: [
    {
      role: "user",
      content: "Analyze the major themes in 'Pride and Prejudice'."
    }
  ]
});
console.log(response.usage);

// Call the model again with the same inputs up to the cache checkpoint
const new_response = await client.messages.create(...)
console.log(new_response.usage);

import java.util.List;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.TextBlockParam;

public class PromptCachingExample {

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
                .model(Model.CLAUDE_OPUS_4_20250514)
                .maxTokens(1024)
                .systemOfTextBlockParams(List.of(
                        TextBlockParam.builder()
 .text("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n")
 .build(),
                        TextBlockParam.builder()
 .text("<the entire contents of 'Pride and Prejudice'>")
 .cacheControl(CacheControlEphemeral.builder().build())
 .build()
                ))
                .addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
                .build();

        Message message = client.messages().create(params);
        System.out.println(message.usage());
    }
}

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

Neste exemplo, o texto completo de "Pride and Prejudice" é armazenado em cache usando o parâmetro cache_control. Isso permite a reutilização deste texto grande em várias chamadas de API sem reprocessá-lo a cada vez. Alterar apenas a mensagem do usuário permite que você faça várias perguntas sobre o livro enquanto utiliza o conteúdo em cache, levando a respostas mais rápidas e eficiência melhorada.

Como funciona o cache de prompts

Quando você envia uma solicitação com o cache de prompts ativado:

1. O sistema verifica se um prefixo de prompt, até um ponto de interrupção de cache especificado, já está em cache de uma consulta recente.
2. Se encontrado, ele usa a versão em cache, reduzindo o tempo de processamento e os custos.
3. Caso contrário, ele processa o prompt completo e armazena em cache o prefixo 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 com múltiplas voltas

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

Preços

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

Como implementar o cache de prompts

Modelos suportados

O cache de prompts é atualmente suportado em:

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Haiku 4.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (descontinuado)

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 final 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 onde cada nível se baseia nos anteriores.

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

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

Três princípios principais:

1. As chaves de cache são cumulativas: Quando você armazena explicitamente um bloco em cache com cache_control, a chave de hash do cache é gerada fazendo hash de todos os blocos anteriores na conversa sequencialmente. Isso significa que o cache para cada bloco depende de todo o conteúdo que veio antes dele.

2. Verificação sequencial para trás: O sistema verifica se há acertos de cache trabalhando para trás a partir do seu ponto de interrupção explícito, verificando cada bloco anterior em ordem reversa. Isso garante que você obtenha o acerto de cache mais longo possível.

3. Janela de lookback de 20 blocos: O sistema verifica apenas até 20 blocos antes de cada ponto de interrupção cache_control explícito. Após verificar 20 blocos sem uma correspondência, ele para de verificar e passa para o próximo ponto de interrupção explícito (se houver).

Exemplo: Entendendo a janela de lookback

Considere uma conversa com 30 blocos de conteúdo onde você define cache_control apenas no bloco 30:

• Se você enviar o bloco 31 sem alterações nos blocos anteriores: O sistema verifica o bloco 30 (correspondência!). Você obtém um acerto de cache no bloco 30, e apenas o bloco 31 precisa de processamento.

• Se você modificar o bloco 25 e enviar o bloco 31: O sistema verifica para trás do bloco 30 → 29 → 28... → 25 (sem correspondência) → 24 (correspondência!). Como o bloco 24 não foi alterado, você obtém um acerto de cache no bloco 24, e apenas os blocos 25-30 precisam ser reprocessados.

• Se você modificar o bloco 5 e enviar o bloco 31: O sistema verifica para trás do bloco 30 → 29 → 28... → 11 (verificação #20). Após 20 verificações sem encontrar uma correspondência, ele para de procurar. Como o bloco 5 está além da janela de 20 blocos, nenhum acerto de cache ocorre e todos os blocos precisam ser reprocessados. No entanto, se você tivesse definido um ponto de interrupção cache_control explícito no bloco 5, o sistema continuaria verificando a partir desse ponto de interrupção: bloco 5 (sem correspondência) → bloco 4 (correspondência!). Isso permite um acerto de cache no bloco 4, demonstrando por que você deve colocar pontos de interrupção antes do conteúdo editável.

Conclusão principal: Sempre defina um ponto de interrupção de cache explícito no final da sua conversa para maximizar suas chances de acertos de cache. Além disso, defina pontos de interrupção logo antes dos blocos de conteúdo que podem ser editáveis para garantir que essas seções possam ser armazenadas em cache independentemente.

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 cache para conteúdo mais de 20 blocos antes do seu ponto de interrupção final
• Colocar pontos de interrupção antes do conteúdo editável para garantir acertos de cache mesmo quando ocorrem alterações além da janela de 20 blocos

Limitações de cache

O comprimento mínimo de prompt armazenável em cache é:

• 1024 tokens para Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (descontinuado) e Claude Opus 3 (descontinuado)
• 4096 tokens para Claude Haiku 4.5
• 2048 tokens para Claude Haiku 3.5 e Claude Haiku 3

Prompts mais curtos não podem ser armazenados em cache, mesmo se marcados com cache_control. Qualquer solicitação para armazenar em cache menos do que esse número de tokens será processada sem cache. Para ver se um prompt foi armazenado em cache, consulte os campos de uso da resposta fields.

Para solicitações simultâneas, observe que uma entrada de cache só fica disponível após o início da primeira resposta. Se você precisar de acertos de cache para solicitações paralelas, aguarde a primeira resposta antes de enviar solicitações subsequentes.

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

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:

• Escritas de cache: Quando novo conteúdo é escrito no cache (25% a mais do que tokens de entrada base para TTL de 5 minutos)
• Leituras de cache: Quando conteúdo em cache é usado (10% do preço de token de entrada base)
• 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 a mesma quantidade com base no que é realmente armazenado em cache e lido. Os pontos de interrupção simplesmente lhe dão controle sobre quais seções podem ser armazenadas em cache independentemente.

O que pode ser armazenado em cache

A maioria dos blocos na solicitação pode ser designada para cache com cache_control. 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, para turnos de usuário e 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, em turnos de usuário e assistente

Cada um desses elementos pode ser marcado com cache_control para ativar o cache para essa parte da solicitação.

O que não pode ser armazenado em cache

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

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

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

  No caso de citações, os blocos de conteúdo de documento de nível superior que servem como material de origem para citações podem ser armazenados em cache. Isso permite que você use cache de prompts com citações efetivamente 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.

Rastreando o desempenho do cache

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

• cache_creation_input_tokens: Número de tokens escritos no cache ao criar uma nova entrada.
• cache_read_input_tokens: Número de tokens recuperados do cache para esta solicitação.
• input_tokens: Número de tokens de entrada que não foram lidos ou usados para criar um cache.

Melhores práticas para cache eficaz

Para otimizar o desempenho do cache de prompts:

• Armazene em cache conteúdo estável e reutilizável, como instruções do sistema, informações de fundo, contextos grandes ou definições de ferramentas frequentes.
• Coloque conteúdo em cache no início do prompt para melhor desempenho.
• Use pontos de interrupção de cache estrategicamente para separar diferentes seções de prefixo armazenável em cache.
• Defina pontos de interrupção de cache no final das conversas e logo antes do conteúdo editável para maximizar as taxas de acerto de cache, especialmente ao trabalhar com prompts que têm mais de 20 blocos de conteúdo.
• 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 prompts ao seu cenário:

• Agentes conversacionais: Reduza custo e latência para conversas estendidas, especialmente aquelas com instruções longas ou documentos carregados.
• Assistentes de codificação: Melhore o preenchimento automático e perguntas sobre 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 longa forma, incluindo imagens em seu prompt sem aumentar a latência de resposta.
• Conjuntos de instruções detalhadas: Compartilhe listas extensas de instruções, procedimentos e exemplos para ajustar as respostas do Claude. Os desenvolvedores geralmente incluem um ou dois exemplos no prompt, mas com cache de prompts você pode obter desempenho ainda melhor incluindo 20+ exemplos diversos de respostas de alta qualidade.
• Uso de ferramentas agênticas: Melhore o desempenho para cenários envolvendo múltiplas chamadas de ferramentas e alterações de código iterativas, onde cada etapa normalmente requer uma nova chamada de API.
• Converse com livros, artigos, documentação, transcrições de podcasts e outro conteúdo de longa forma: Traga qualquer base de conhecimento à vida incorporando o(s) documento(s) inteiro(s) no prompt e deixando os usuários fazerem perguntas.

Resolvendo problemas comuns

Se experimentar comportamento inesperado:

• Garanta que as seções em cache sejam idênticas e marcadas com cache_control nos mesmos locais em todas as chamadas
• Verifique se as chamadas são feitas dentro da vida útil do cache (5 minutos por padrão)
• Verifique se tool_choice e o uso de imagens permanecem consistentes entre chamadas
• Valide que você está armazenando em cache pelo menos o número mínimo de tokens
• O sistema verifica automaticamente acertos de cache em limites de blocos de conteúdo anteriores (até ~20 blocos antes do seu ponto de interrupção). Para prompts com mais de 20 blocos de conteúdo, você pode precisar de parâmetros cache_control adicionais mais cedo no prompt para garantir que todo o conteúdo possa ser armazenado em cache
• Verifique se as chaves em seus blocos de conteúdo tool_use têm ordenação estável, pois algumas linguagens (por exemplo, Swift, Go) randomizam a ordem das chaves durante a conversão JSON, quebrando caches

Cache com blocos de pensamento

Ao usar pensamento estendido com cache de prompts, 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 solicitação quando você faz chamadas de API subsequentes com resultados de ferramentas. Isso ocorre comumente 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 em suas métricas de uso. Isso é importante para cálculo de custo 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
• O cache é invalidado quando conteúdo de usuário não-resultado-de-ferramenta é adicionado, causando que todos os blocos de pensamento anteriores sejam removidos
• 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:

Solicitação 1: Usuário: "Qual é o tempo em Paris?"
Resposta: [thinking_block_1] + [bloco tool_use 1]

Solicitação 2:
Usuário: ["Qual é o tempo em Paris?"],
Assistente: [thinking_block_1] + [bloco tool_use 1],
Usuário: [tool_result_1, cache=True]
Resposta: [thinking_block_2] + [bloco de texto 2]
# Solicitação 2 armazena em cache seu conteúdo de solicitação (não a resposta)
# O cache inclui: mensagem do usuário, thinking_block_1, bloco tool_use 1 e tool_result_1

Solicitação 3:
Usuário: ["Qual é o tempo em Paris?"],
Assistente: [thinking_block_1] + [bloco tool_use 1],
Usuário: [tool_result_1, cache=True],
Assistente: [thinking_block_2] + [bloco de texto 2],
Usuário: [Resposta de texto, cache=True]
# Bloco de usuário não-resultado-de-ferramenta causa que todos os blocos de pensamento sejam ignorados
# Esta solicitação é processada como se blocos de pensamento nunca estivessem presentes

Quando um bloco de usuário não-resultado-de-ferramenta é incluído, ele designa um novo loop de assistente e todos os blocos de pensamento anteriores são removidos do contexto.

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

Armazenamento e compartilhamento de cache

• Isolamento de Organização: Os caches são isolados entre organizações. Diferentes organizações nunca compartilham caches, mesmo que usem prompts idênticos.

• 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 Token de Saída: O cache de prompts não tem efeito na geração de token de saída. A resposta que você recebe será idêntica ao que você obteria se o cache de prompts não fosse usado.

Duração de cache de 1 hora

Se você achar que 5 minutos é muito curto, 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 cache_control assim:

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

A resposta incluirá informações detalhadas de cache como a seguinte:

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,

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

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

Quando usar o cache de 1 hora

Se você tiver 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 isso continuará sendo atualizado sem custo adicional.

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

• Quando você tem prompts que provavelmente são usados com menos frequência do que a cada 5 minutos, mas mais frequentemente do que a cada hora. Por exemplo, quando um agente lateral agêntico levará mais de 5 minutos, ou ao armazenar uma conversa de chat longa 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 sua utilização de limite de taxa, já que acertos de cache não são deduzidos do seu limite de taxa.

Misturando diferentes TTLs

Você pode usar controles de cache de 1 hora e 5 minutos na mesma solicitaçã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, determinamos três locais de faturamento em seu prompt:

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

Você será cobrado por:

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

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

Exemplos de cache de prompts

Para ajudá-lo a começar com cache de prompts, preparamos um livro de receitas de cache de prompts com exemplos detalhados e melhores práticas.

Abaixo, incluímos vários trechos de código que demonstram vários padrões de cache de prompts. Esses exemplos demonstram como implementar cache em diferentes cenários, ajudando você a entender as aplicações práticas desse recurso:

Perguntas frequentes