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 em 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 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

{"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 "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 fazer várias perguntas sobre o livro enquanto utiliza o conteúdo em cache, resultando em respostas mais rápidas e eficiência melhorada.

Como o cache de prompt funciona

Quando você envia uma solicitação com o cache de prompt 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 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 com múltiplos turnos

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

O cache de prompt é um recurso poderoso que otimiza o uso da sua API permitindo retomar a partir de prefixos específicos em 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 de Mensagens usando um bloco cache_control:

{"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 "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 fazer várias perguntas sobre o livro enquanto utiliza o conteúdo em cache, resultando em respostas mais rápidas e eficiência melhorada.

Como o cache de prompt funciona

Quando você envia uma solicitação com o cache de prompt 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 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 com múltiplos turnos

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

O cache de prompt é um recurso poderoso que otimiza o uso da sua API permitindo retomar a partir de prefixos específicos em 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 de Mensagens usando um bloco cache_control:

{"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 "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 fazer várias perguntas sobre o livro enquanto utiliza o conteúdo em cache, resultando em respostas mais rápidas e eficiência melhorada.

Como o cache de prompt funciona

Quando você envia uma solicitação com o cache de prompt 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 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 com múltiplos turnos

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

Modelos suportados

O cache de prompt é atualmente suportado em:

• Claude Opus 4.5
• 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)

O cache de prompt é 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 prompt com a API de Mensagens usando um bloco cache_control:

{"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 "Pride and Prejudice" é armazenado em cache usando o parâmetro cache_control. Isso permite reutilizar esse texto grande em várias chamadas de API sem reprocessá-lo cada vez. Alterar apenas a mensagem do usuário permite fazer várias perguntas sobre o livro enquanto utiliza o conteúdo em cache, levando a respostas mais rápidas e eficiência melhorada.

Como o cache de prompt funciona

Quando você envia uma solicitação com o cache de prompt 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 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 com múltiplos turnos

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

Modelos suportados

O cache de prompt é atualmente suportado em:

• Claude Opus 4.5
• 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.

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 a sequência mais longa de blocos em cache correspondentes. 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 de 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 de sua conversa para maximizar suas chances de acertos de cache. Além disso, defina pontos de interrupção logo antes de blocos de conteúdo que possam 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.5, 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.

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.

Limitações de cache

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

• 1024 tokens para Claude Opus 4.5, 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.

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 do ponto 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% 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.

Limitações de cache

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

• 1024 tokens para Claude Opus 4.5, 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.

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 do ponto 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% 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.

Limitações de cache

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

• 1024 tokens para Claude Opus 4.5, 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.

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 do ponto 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% 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 prompt com citações efetivamente armazenando em cache os documentos que as citações referenciará.

• Blocos de texto vazios não podem ser armazenados em cache.

Limitações de cache

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

• 1024 tokens para Claude Opus 4.5, 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.

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 do ponto 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% 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 prompt com citações efetivamente 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

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.

Limitações de cache

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

• 1024 tokens para Claude Opus 4.5, 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.

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 do ponto 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% 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 prompt com citações efetivamente 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

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 (ou seja, tokens após o último ponto de interrupção de cache).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Limitações de cache

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

• 1024 tokens para Claude Opus 4.5, 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 este número de tokens será processada sem cache. Para ver se um prompt foi armazenado em cache, consulte os campos de uso da resposta.

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 um tempo de vida de 5 minutos.

Compreendendo 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 do que tokens de entrada base para TTL de 5 minutos)
• Leituras de cache: Quando conteúdo em cache é usado (10% do preço do 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 o mesmo valor 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 prompt 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

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 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 ou usados para criar um cache (ou seja, tokens após o último ponto de interrupção de cache).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

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 contexto, 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 de conversas e logo antes de conteúdo editável para maximizar 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 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 preenchimento automático 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 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 prompt você pode obter desempenho ainda melhor incluindo 20+ exemplos diversos de respostas de alta qualidade.
• Uso de ferramentas agêntico: Melhore o desempenho para cenários envolvendo múltiplas chamadas de ferramentas e alterações 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.

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 preenchimento automático 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 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 prompt você pode obter desempenho ainda melhor incluindo 20+ exemplos diversos de respostas de alta qualidade.
• Uso de ferramentas agêntico: Melhore o desempenho para cenários envolvendo múltiplas chamadas de ferramentas e alterações 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:

• 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 o 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 de 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

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 de API subsequentes com resultados de ferramentas. Isso geralmente acontece durante o uso de ferramentas quando você passa blocos de pensamento de volta para continuar a conversa.

Contagem de tokens de entrada: Quando blocos de pensamento são lidos do cache, eles contam como tokens de entrada 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 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, 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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

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: 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 tokens de saída: 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.

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 preenchimento automático 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 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 prompt você pode obter desempenho ainda melhor incluindo 20+ exemplos diversos de respostas de alta qualidade.
• Uso de ferramentas agêntico: Melhore o desempenho para cenários envolvendo múltiplas chamadas de ferramentas e alterações 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:

• 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 o 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 de 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

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 de API subsequentes com resultados de ferramentas. Isso geralmente acontece durante o uso de ferramentas quando você passa blocos de pensamento de volta para continuar a conversa.

Contagem de tokens de entrada: Quando blocos de pensamento são lidos do cache, eles contam como tokens de entrada 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 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, 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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

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: 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 tokens de saída: 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 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 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 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, pois acertos de cache não são deduzidos do seu limite de taxa.

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 preenchimento automático e perguntas e respostas sobre a base de código mantendo seções relevantes ou uma versão resumida da base de código no prompt.
• Processamento de documentos grandes: Incorpore material completo de 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 prompt você pode obter um desempenho ainda melhor incluindo 20+ exemplos diversos de respostas de alta qualidade.
• Uso de ferramentas agêntica: Melhore o desempenho para cenários envolvendo múltiplas chamadas de ferramentas e mudanças 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 a ele.

Resolvendo 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 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 nos 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

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 de API subsequentes com resultados de ferramentas. Isso geralmente acontece durante o uso de ferramentas quando você passa blocos de pensamento de volta para continuar a conversa.

Contagem de tokens de entrada: Quando blocos de pensamento são lidos do cache, eles contam como tokens de entrada 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 do usuário
• O cache é invalidado quando conteúdo de usuário que não é resultado de ferramenta é adicionado, causando que todos os blocos de pensamento anteriores sejam removidos
• Este comportamento de cache ocorre mesmo sem marcadores cache_control explícitos

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

Exemplo com uso de ferramentas:

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

Quando um bloco de usuário que 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: Os 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 prompt 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 prompt não fosse usado.

Duração de cache de 1 hora

Se você achar que 5 minutos é muito curto, a Anthropic também oferece uma duração de cache de 1 hora com custo adicional.

Para usar o cache estendido, inclua ttl na definição de cache_control assim:

"cache_control": {
    "type": "ephemeral",
    "ttl": "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 de 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 5 minutos, mas com mais frequência 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ê deseja melhorar sua utilização de limite de taxa, pois os 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: As 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 em 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 mostra os tokens de entrada de 3 solicitações, cada uma com diferentes acertos de cache 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 demonstram 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 deste recurso:

Perguntas Frequentes

Isso é importante para entender tanto os custos quanto os limites de taxa, pois input_tokens será tipicamente muito menor do que seu total de entrada ao usar cache efetivamente.

Isso é importante para entender tanto custos quanto limites de taxa, pois input_tokens será tipicamente muito menor do que seu total de entrada ao usar cache de forma eficaz.