Cache de prompts

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

{"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}

​

Como funciona o cache de prompts

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, usa a versão em cache, reduzindo o tempo de processamento e custos.
3. Caso contrário, processa o prompt completo e armazena o prefixo em cache assim que a resposta começa.

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

​

Preços

​

Como implementar o cache de prompts

​

Modelos suportados

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

​

Estruturando seu prompt

​

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

• Quando você adiciona um ponto de interrupção cache_control, o sistema verifica automaticamente se há acertos de cache em todos os limites de bloco 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 vários pontos de interrupção apenas para ativar o cache - um no final é suficiente

​

Quando usar vários pontos de interrupção

• 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

​

Limitações de cache

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

​

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

• Escritas de cache: Quando novo conteúdo é escrito no cache (25% 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

​

O que pode ser armazenado em cache

• 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

​

O que não pode ser armazenado em cache

• 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 de forma eficaz armazenando em cache os documentos que as citações referenciará.
• Blocos de texto vazios não podem ser armazenados em cache.

​

O que invalida o cache

​

Rastreando o desempenho do cache

• 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 do cache ou usados para criar um cache.

​

Melhores práticas para cache eficaz

• 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.
• Analise regularmente as taxas de acerto de cache e ajuste sua estratégia conforme necessário.

​

Otimizando para diferentes casos de uso

• 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 de agente: 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

• Certifique-se de que as seções em cache são 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 se há 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 no início do 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

• 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

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

Solicitação 2:
Usuário: ["Qual é o tempo em Paris?"],
Assistente: [thinking_block_1] + [tool_use block 1],
Usuário: [tool_result_1, cache=True]
Resposta: [thinking_block_2] + [text block 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, tool_use block 1 e tool_result_1

Solicitação 3:
Usuário: ["Qual é o tempo em Paris?"],
Assistente: [thinking_block_1] + [tool_use block 1],
Usuário: [tool_result_1, cache=True],
Assistente: [thinking_block_2] + [text block 2],
Usuário: [Text response, 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

​

Armazenamento e compartilhamento de cache

• Isolamento de Organização: 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 requerem 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

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

{
    "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,
        }
    }
}

​

Quando usar o cache de 1 hora

• Quando você tem prompts que provavelmente são usados com menos frequência do que 5 minutos, mas mais frequentemente do que a cada hora. Por exemplo, quando um agente secundário de agente levará mais de 5 minutos, ou ao armazenar uma conversa 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

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.

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

​

Exemplos de cache de prompts

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-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?"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-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",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either celsius or fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # many more tools
        {
            "name": "get_time",
            "description": "Get the current time in a given time zone",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "The IANA time zone name, e.g. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather and time in New York?"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "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 would 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"}
                }
            ]
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-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"}
                }
            ]
        }
    ]
}'

​

Perguntas frequentes

python client.beta.prompt_caching.messages.create(...)

python client.messages.create(...)

client.beta.promptCaching.messages.create(...)

client.messages.create(...)