Cache de prompt

O cache de prompt é um recurso poderoso que otimiza o uso da sua API permitindo retomar a partir de prefixos específicos nos seus prompts. Esta 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 prompt com a API Messages 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-opus-4-20250514",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Você é um assistente de IA encarregado de analisar obras literárias. Seu objetivo é fornecer comentários perspicazes sobre temas, personagens e estilo de escrita.\n"
      },
      {
        "type": "text",
        "text": "<todo o conteúdo de Orgulho e Preconceito>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analise os principais temas em Orgulho e Preconceito."
      }
    ]
  }'

# Chame o modelo novamente com as mesmas entradas até o ponto de verificação do cache
curl https://api.anthropic.com/v1/messages # resto da entrada

{"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, todo o texto de “Orgulho e Preconceito” é armazenado em cache usando o parâmetro cache_control. Isso permite a reutilização deste texto grande em múltiplas chamadas da 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 maior eficiência.

​

Como funciona o cache de prompt

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

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

Isso é especialmente útil para:

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

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

​

Preços

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

Nota:

• Tokens de escrita de cache de 5 minutos custam 1,25 vezes o preço base dos tokens de entrada
• Tokens de escrita de cache de 1 hora custam 2 vezes o preço base dos tokens de entrada
• Tokens de leitura de cache custam 0,1 vezes o preço base dos tokens de entrada
• Tokens de entrada e saída regulares são precificados às taxas padrão

​

Como implementar o cache de prompt

​

Modelos suportados

O cache de prompt é atualmente suportado em:

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

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 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, depois messages. Esta 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. Veja como funciona:

• Quando você adiciona um ponto de interrupção cache_control, o sistema verifica automaticamente acertos de cache em todos os limites de blocos de conteúdo anteriores (até aproximadamente 20 blocos antes do seu ponto de interrupção explícito)
• Se qualquer uma dessas posições anteriores corresponder ao conteúdo em cache de solicitações anteriores, o sistema usa o prefixo correspondente mais longo
• Isso significa que você não precisa de múltiplos pontos de interrupção apenas para habilitar o cache - um no final é suficiente

​

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 o cache para conteúdo mais de 20 blocos antes do seu ponto de interrupção final

​

Limitações do cache

O comprimento mínimo de prompt que pode ser armazenado em cache é:

• 1024 tokens para Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 e Claude Opus 3
• 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 que este número de tokens será processada sem cache. Para ver se um prompt foi armazenado em cache, veja os campos de uso da resposta.

Para solicitações concorrentes, note que uma entrada de cache só fica disponível após a primeira resposta começar. 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 um tempo de vida 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ê só é cobrado por:

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

Adicionar mais pontos de interrupção cache_control não aumenta seus custos - você ainda paga a mesma quantia baseada no conteúdo que é realmente armazenado em cache e lido. Os pontos de interrupção simplesmente 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 habilitar 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, 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 desta forma, eles CONTAM como tokens de entrada quando lidos do cache.

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

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

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

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

​

Rastreando 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 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 prompt:

• 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 o conteúdo em cache no início do prompt para melhor desempenho.
• Use pontos de interrupção de cache estrategicamente para separar diferentes seções de prefixo que podem ser armazenadas em cache.
• Analise regularmente as taxas de acerto de cache e ajuste sua estratégia conforme necessário.

​

Otimizando para diferentes casos de uso

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

• Agentes conversacionais: Reduza custo e latência para conversas estendidas, especialmente aquelas com instruções longas ou documentos carregados.
• Assistentes de codificação: Melhore o autocompletar e Q&A de base de código mantendo seções relevantes ou uma versão resumida da base de código no prompt.
• Processamento de documentos grandes: Incorpore material completo de formato longo incluindo imagens no seu prompt sem aumentar a latência de resposta.
• Conjuntos de instruções detalhadas: Compartilhe listas extensas de instruções, procedimentos e exemplos para ajustar as respostas do Claude. Desenvolvedores frequentemente incluem um exemplo ou dois no prompt, mas com cache de prompt você pode obter ainda melhor desempenho 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 mudanças iterativas de código, onde cada etapa tipicamente requer uma nova chamada da API.
• Conversar com livros, artigos, documentação, transcrições de podcast e outro conteúdo de formato longo: Dê vida a qualquer base de conhecimento incorporando o(s) documento(s) inteiro(s) no prompt, e deixando os usuários fazerem perguntas sobre ele.

​

Solucionando problemas comuns

Se estiver experimentando comportamento inesperado:

• Certifique-se de que as seções em cache são idênticas e marcadas com cache_control nos mesmos locais entre chamadas
• Verifique se as chamadas são feitas dentro do tempo de vida do cache (5 minutos por padrão)
• Verifique se tool_choice e uso de imagem 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

​

Cache com blocos de pensamento

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

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

Contagem de tokens de entrada: Quando blocos de pensamento são lidos do cache, eles contam como tokens de entrada nas suas métricas de uso. Isso é importante para cálculo de 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 a remoção de todos os blocos de pensamento anteriores
• Este comportamento de cache ocorre mesmo sem marcadores cache_control explícitos

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

Exemplo com uso de ferramenta:

Solicitação 1: Usuário: "Qual é o clima em Paris?"
Resposta: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1]

Solicitação 2: 
Usuário: ["Qual é o clima em Paris?"], 
Assistente: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1], 
Usuário: [resultado_ferramenta_1, cache=True]
Resposta: [bloco_de_pensamento_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, bloco_de_pensamento_1, bloco de uso de ferramenta 1, e resultado_ferramenta_1

Solicitação 3:
Usuário: ["Qual é o clima em Paris?"], 
Assistente: [bloco_de_pensamento_1] + [bloco de uso de ferramenta 1], 
Usuário: [resultado_ferramenta_1, cache=True], 
Assistente: [bloco_de_pensamento_2] + [bloco de texto 2], 
Usuário: [Resposta de texto, cache=True]
# Bloco de usuário não-resultado-de-ferramenta causa todos os blocos de pensamento a serem 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, veja a documentação de pensamento estendido.

​

Armazenamento e compartilhamento de cache

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

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

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

​

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.

O cache de 1 hora está atualmente em beta. Para usar o cache estendido, adicione extended-cache-ttl-2025-04-11 como um cabeçalho beta à sua solicitação, e então inclua ttl na definição cache_control assim:

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

A resposta incluirá informações detalhadas de cache como o 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,
        }
    }
}

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

​

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 mais frequentemente que a cada 5 minutos), continue a usar o cache de 5 minutos, já que este continuará a ser atualizado sem custo adicional.

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

• Quando você tem prompts que provavelmente são usados menos frequentemente que 5 minutos, mas mais frequentemente 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 cobrança no seu prompt:

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

Você será cobrado por:

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

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

​

Exemplos de cache de prompt

Para ajudá-lo a começar com o cache de prompt, preparamos um cookbook de cache de prompt com exemplos detalhados e melhores práticas.

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

​

FAQ