---
title: Cache de prompt
url: https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching
description: Armazene em cache prefixos de prompt com `cache_control` para reduzir custos e latência, usando cache automático ou breakpoints explícitos com TTLs de 5 minutos ou 1 hora.
featureMetadata:
  zdr:
    eligibility: eligible
    note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Seus prompts e as saídas do Claude não são armazenados. As representações do cache KV e os hashes criptográficos são mantidos na memória durante o TTL do cache e excluídos prontamente após a expiração.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: stable
    Amazon Bedrock: stable
    Amazon Bedrock (bedrock-runtime): stable
    Claude Platform on AWS: stable
    Claude Models on Google Cloud (Anthropic managed): stable
    Claude Models on Google Cloud (Google managed): stable
    Microsoft Foundry: stable
---

**Suporte da API**: O uso varia conforme o produto.

* **Messages API**: Ative com `cache_control`, no nível superior ou em blocos.
* **Managed Agents**: Sempre ativo. As entradas de cache usam um tempo de vida de 5 minutos por padrão, e as leituras e gravações de cache aparecem no uso da sessão.

O “prompt caching” (cache de prompt) otimiza o uso da API permitindo que a API retome a partir de prefixos específicos em seus prompts. Isso reduz significativamente o tempo de processamento e os custos para tarefas repetitivas ou prompts com elementos consistentes.

Há duas maneiras de habilitar o cache de prompt:

* **[Cache automático](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#automatic-caching):** Adicione um único campo `cache_control` no nível superior da sua solicitação. O sistema aplica automaticamente o “cache breakpoint” (ponto de interrupção de cache) ao último bloco armazenável em cache e o move para frente à medida que as conversas crescem. Ideal para conversas de vários turnos em que o histórico crescente de mensagens deve ser armazenado em cache automaticamente.
* **[Pontos de interrupção de cache explícitos](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#explicit-cache-breakpoints):** Coloque `cache_control` diretamente em blocos de conteúdo individuais para ter controle refinado sobre exatamente o que é armazenado em cache.

Uma maneira de começar é com o cache automático:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "cache_control": {"type": "ephemeral"},
      "system": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
      "messages": [
        {
          "role": "user",
          "content": "Analyze the major themes in Pride and Prejudice."
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  cache_control:
    type: ephemeral
  system: >-
    You are an AI assistant tasked with analyzing literary works. Your goal is
    to provide insightful commentary on themes, characters, and writing style.
  messages:
    - role: user
      content: Analyze the major themes in Pride and Prejudice.
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

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

  ```typescript TypeScript
  const client = new Anthropic();

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

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      CacheControl = new CacheControlEphemeral(),
      System = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
      Messages =
      [
          new UserMessageParam { Content = "Analyze the major themes in 'Pride and Prejudice'." }
      ]
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message.Usage);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:        anthropic.ModelClaudeOpus5_5,
  	MaxTokens:    1024,
  	CacheControl: anthropic.NewCacheControlEphemeralParam(),
  	System: []anthropic.TextBlockParam{
  		{Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."},
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in 'Pride and Prejudice'.")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.Usage.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.CacheControlEphemeral;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .cacheControl(CacheControlEphemeral.builder().build())
          .system("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.")
          .addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
          .build();

      Message message = client.messages().create(params);
      IO.println(message.usage());
  }
  ```

  ```php PHP
  use Anthropic\Messages\CacheControlEphemeral;
  use Anthropic\Messages\Model;
  // ...
  $client = new Client();

  $response = $client->messages->create(
      maxTokens: 1024,
      messages: [
          ['role' => 'user', 'content' => "Analyze the major themes in 'Pride and Prejudice'."]
      ],
      model: Model::CLAUDE_OPUS_5_5,
      cacheControl: CacheControlEphemeral::with(),
      system: 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.',
  );
  echo json_encode($response->usage);
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    cache_control: {type: "ephemeral"},
    system_: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages: [
      {
        role: "user",
        content: "Analyze the major themes in 'Pride and Prejudice'."
      }
    ]
  )
  puts response.usage
  ```
</CodeGroup>

Com o cache automático, o sistema armazena em cache todo o conteúdo até o último bloco armazenável em cache, inclusive. Em solicitações subsequentes com o mesmo prefixo, o conteúdo em cache é reutilizado automaticamente.

***

## Como o cache de prompt funciona

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

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

Isso é especialmente útil para:

* Prompts com muitos exemplos
* Grandes quantidades de contexto ou informações de base
* Tarefas repetitivas com instruções consistentes
* Conversas longas de vários turnos

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

O tempo de vida é medido a partir do início da solicitação que grava ou lê a entrada de cache, e não a partir do fim de sua resposta. O tempo gasto gerando uma resposta conta contra o tempo de vida: se uma resposta leva 4 minutos para fazer streaming, uma solicitação subsequente que reutilize o mesmo prefixo em cache deve começar em cerca de 1 minuto após a conclusão dessa resposta.

Se 5 minutos for muito pouco, você pode usar uma [duração de cache de 1 hora](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#1-hour-cache-duration) com custo adicional (consulte [Preços](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#pricing)).

O cache de prompt abrange o prefixo completo: `tools`, `system` e `messages` (nessa ordem), até o bloco designado com `cache_control`, inclusive.

***

## Preços

O cache de prompt tem preços próprios. A tabela a seguir mostra o preço por milhão de tokens para cada modelo suportado:

| Model                                                                                                                                                                     | Base input tokens | 5m cache writes | 1h cache writes | Cache hits and refreshes | Output tokens |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------- | :-------------- | :-------------- | :----------------------- | :------------ |
| Claude Fable 5.2                                                                                                                                                          | $8 / MTok         | $10 / MTok      | $16 / MTok      | $0.20 / MTok<sup>1</sup> | $40 / MTok    |
| Claude Mythos 5.2 ([limited availability](https://support.claude.com/en/articles/14604842))                                                                               | $8 / MTok         | $10 / MTok      | $16 / MTok      | $0.20 / MTok<sup>1</sup> | $40 / MTok    |
| Claude Fable 5.1                                                                                                                                                          | $10 / MTok        | $12.50 / MTok   | $20 / MTok      | $0.25 / MTok<sup>1</sup> | $50 / MTok    |
| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842))                                                                               | $10 / MTok        | $12.50 / MTok   | $20 / MTok      | $0.25 / MTok<sup>1</sup> | $50 / MTok    |
| Claude Fable 5                                                                                                                                                            | $10 / MTok        | $12.50 / MTok   | $20 / MTok      | $1 / MTok                | $50 / MTok    |
| Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842))                                                                                 | $10 / MTok        | $12.50 / MTok   | $20 / MTok      | $1 / MTok                | $50 / MTok    |
| Claude Opus 5.5                                                                                                                                                           | $4 / MTok         | $5 / MTok       | $8 / MTok       | $0.20 / MTok<sup>2</sup> | $20 / MTok    |
| Claude Opus 5                                                                                                                                                             | $5 / MTok         | $6.25 / MTok    | $10 / MTok      | $0.50 / MTok             | $25 / MTok    |
| Claude Opus 4.8                                                                                                                                                           | $5 / MTok         | $6.25 / MTok    | $10 / MTok      | $0.50 / MTok             | $25 / MTok    |
| Claude Opus 4.7                                                                                                                                                           | $5 / MTok         | $6.25 / MTok    | $10 / MTok      | $0.50 / MTok             | $25 / MTok    |
| Claude Opus 4.6                                                                                                                                                           | $5 / MTok         | $6.25 / MTok    | $10 / MTok      | $0.50 / MTok             | $25 / MTok    |
| Claude Opus 4.5                                                                                                                                                           | $5 / MTok         | $6.25 / MTok    | $10 / MTok      | $0.50 / MTok             | $25 / MTok    |
| Claude Opus 4.1 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | $15 / MTok        | $18.75 / MTok   | $30 / MTok      | $1.50 / MTok             | $75 / MTok    |
| Claude Opus 4 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations))               | $15 / MTok        | $18.75 / MTok   | $30 / MTok      | $1.50 / MTok             | $75 / MTok    |
| Claude Sonnet 5.5                                                                                                                                                         | $2 / MTok         | $2.50 / MTok    | $4 / MTok       | $0.10 / MTok<sup>2</sup> | $10 / MTok    |
| Claude Sonnet 5                                                                                                                                                           | $2 / MTok         | $2.50 / MTok    | $4 / MTok       | $0.20 / MTok             | $10 / MTok    |
| Claude Sonnet 4.6                                                                                                                                                         | $3 / MTok         | $3.75 / MTok    | $6 / MTok       | $0.30 / MTok             | $15 / MTok    |
| Claude Sonnet 4.5                                                                                                                                                         | $3 / MTok         | $3.75 / MTok    | $6 / MTok       | $0.30 / MTok             | $15 / MTok    |
| Claude Sonnet 4 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | $3 / MTok         | $3.75 / MTok    | $6 / MTok       | $0.30 / MTok             | $15 / MTok    |
| Claude Haiku 5.5 (for prompts up to 100,000 tokens)                                                                                                                       | $0.10 / MTok      | $0.125 / MTok   | $0.20 / MTok    | $0.01 / MTok             | $0.50 / MTok  |
| Claude Haiku 5.5 (for prompts over 100,000 tokens)                                                                                                                        | $0.50 / MTok      | $0.625 / MTok   | $1 / MTok       | $0.05 / MTok             | $2.50 / MTok  |
| Claude Haiku 4.5                                                                                                                                                          | $1 / MTok         | $1.25 / MTok    | $2 / MTok       | $0.10 / MTok             | $5 / MTok     |

*<sup>1 Cache hits and refreshes on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, and Claude Mythos 5.1 are priced at 0.025x the base input price.</sup>*

*<sup>2 Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.</sup>*

*<sup>All other models use the standard 0.1x multiplier.</sup>*

<Note>
  A tabela anterior reflete os seguintes multiplicadores de preço para o cache de prompt:

  * Tokens de gravação de cache com TTL de 5 minutos custam 1,25 vez o preço base dos tokens de entrada.
  * Tokens de gravação de cache com TTL de 1 hora custam 2 vezes o preço base dos tokens de entrada.
  * Tokens de leitura de cache custam 0,1 vez o preço base dos tokens de entrada (consulte a nota de rodapé da tabela para exceções por modelo).

  Esses multiplicadores se acumulam com outros modificadores de preço, como o desconto da Batch API, [preços de contexto longo](https://platform.claude.com/docs/pt-BR/about-claude/pricing#long-context-pricing) e residência de dados. Em um modelo com preço baseado no comprimento do prompt, leituras e gravações de cache contam para o comprimento do prompt de uma solicitação. Consulte [Preços](https://platform.claude.com/docs/pt-BR/about-claude/pricing) para detalhes completos.
</Note>

***

## Modelos suportados

O cache de prompt (tanto automático quanto explícito) é suportado em todos os [modelos Claude ativos](https://platform.claude.com/docs/pt-BR/models/overview).

***

## Cache automático

O cache automático habilita o cache de prompt com um único campo. Em vez de colocar `cache_control` em blocos de conteúdo individuais, adicione um único campo `cache_control` no nível superior do corpo da sua solicitação. O sistema aplica automaticamente o ponto de interrupção de cache ao último bloco armazenável em cache.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "cache_control": {"type": "ephemeral"},
      "system": "You are a helpful assistant that remembers our conversation.",
      "messages": [
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {"role": "assistant", "content": "Nice to meet you, Alex! How can I help with your ML work today?"},
        {"role": "user", "content": "What did I say I work on?"}
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  cache_control:
    type: ephemeral
  system: You are a helpful assistant that remembers our conversation.
  messages:
    - role: user
      content: My name is Alex. I work on machine learning.
    - role: assistant
      content: Nice to meet you, Alex! How can I help with your ML work today?
    - role: user
      content: What did I say I work on?
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      cache_control={"type": "ephemeral"},
      system="You are a helpful assistant that remembers our conversation.",
      messages=[
          {"role": "user", "content": "My name is Alex. I work on machine learning."},
          {
              "role": "assistant",
              "content": "Nice to meet you, Alex! How can I help with your ML work today?",
          },
          {"role": "user", "content": "What did I say I work on?"},
      ],
  )
  print(response.usage.model_dump_json())
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    cache_control: { type: "ephemeral" },
    system: "You are a helpful assistant that remembers our conversation.",
    messages: [
      { role: "user", content: "My name is Alex. I work on machine learning." },
      {
        role: "assistant",
        content: "Nice to meet you, Alex! How can I help with your ML work today?"
      },
      { role: "user", content: "What did I say I work on?" }
    ]
  });
  console.log(response.usage);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      CacheControl = new CacheControlEphemeral(),
      System = "You are a helpful assistant that remembers our conversation.",
      Messages =
      [
          new UserMessageParam { Content = "My name is Alex. I work on machine learning." },
          new AssistantMessageParam
          {
              Content = "Nice to meet you, Alex! How can I help with your ML work today?"
          },
          new UserMessageParam { Content = "What did I say I work on?" }
      ]
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message.Usage);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:        anthropic.ModelClaudeOpus5_5,
  	MaxTokens:    1024,
  	CacheControl: anthropic.NewCacheControlEphemeralParam(),
  	System: []anthropic.TextBlockParam{
  		{Text: "You are a helpful assistant that remembers our conversation."},
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("My name is Alex. I work on machine learning.")),
  		anthropic.NewAssistantMessage(anthropic.NewTextBlock("Nice to meet you, Alex! How can I help with your ML work today?")),
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What did I say I work on?")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.Usage.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.CacheControlEphemeral;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .cacheControl(CacheControlEphemeral.builder().build())
          .system("You are a helpful assistant that remembers our conversation.")
          .addUserMessage("My name is Alex. I work on machine learning.")
          .addAssistantMessage("Nice to meet you, Alex! How can I help with your ML work today?")
          .addUserMessage("What did I say I work on?")
          .build();

      Message message = client.messages().create(params);
      IO.println(message.usage());
  }
  ```

  ```php PHP
  use Anthropic\Messages\CacheControlEphemeral;
  use Anthropic\Messages\Model;
  // ...
  $client = new Client();

  $response = $client->messages->create(
      maxTokens: 1024,
      messages: [
          ['role' => 'user', 'content' => 'My name is Alex. I work on machine learning.'],
          ['role' => 'assistant', 'content' => 'Nice to meet you, Alex! How can I help with your ML work today?'],
          ['role' => 'user', 'content' => 'What did I say I work on?'],
      ],
      model: Model::CLAUDE_OPUS_5_5,
      cacheControl: CacheControlEphemeral::with(),
      system: 'You are a helpful assistant that remembers our conversation.',
  );
  echo json_encode($response->usage);
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    cache_control: {type: "ephemeral"},
    system_: "You are a helpful assistant that remembers our conversation.",
    messages: [
      {role: "user", content: "My name is Alex. I work on machine learning."},
      {role: "assistant", content: "Nice to meet you, Alex! How can I help with your ML work today?"},
      {role: "user", content: "What did I say I work on?"}
    ]
  )
  puts response.usage
  ```
</CodeGroup>

### Como o cache automático funciona em conversas de vários turnos

Com o cache automático, o ponto de cache avança automaticamente à medida que as conversas crescem. Cada nova solicitação armazena em cache tudo até o último bloco armazenável em cache, e o conteúdo anterior é lido do cache.

| Solicitação   | Conteúdo                                                                                                     | Comportamento do cache                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| Solicitação 1 | System<br />+ User(1) + Asst(1)<br />+ **User(2)** ◀ cache                                                   | Tudo gravado no cache                                                       |
| Solicitação 2 | System<br />+ User(1) + Asst(1)<br />+ User(2) + Asst(2)<br />+ **User(3)** ◀ cache                          | System até User(2) lidos do cache;<br />Asst(2) + User(3) gravados no cache |
| Solicitação 3 | System<br />+ User(1) + Asst(1)<br />+ User(2) + Asst(2)<br />+ User(3) + Asst(3)<br />+ **User(4)** ◀ cache | System até User(3) lidos do cache;<br />Asst(3) + User(4) gravados no cache |

O ponto de interrupção de cache se move automaticamente para o último bloco armazenável em cache em cada solicitação, então você não precisa atualizar nenhum marcador `cache_control` à medida que a conversa cresce.

### Suporte a TTL

Por padrão, o cache automático usa um TTL de 5 minutos. Você pode especificar um TTL de 1 hora a 2x o preço base dos tokens de entrada:

```json
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }
```

### Combinando com cache em nível de bloco

O cache automático é compatível com [pontos de interrupção de cache explícitos](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#explicit-cache-breakpoints). Quando usados juntos, o ponto de interrupção de cache automático usa um dos 4 slots de breakpoint disponíveis.

Isso permite combinar as duas abordagens. Por exemplo, use um breakpoint explícito para armazenar em cache seu prompt do sistema, enquanto o cache automático cuida da conversa:

```json
{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}
```

### O que permanece igual

O cache automático usa a mesma infraestrutura de cache subjacente. Preços, limites mínimos de tokens, requisitos de ordenação de contexto e a janela de retrospecção de 20 blocos se aplicam da mesma forma que com breakpoints explícitos.

### Casos extremos

* Se o último bloco já tiver um `cache_control` explícito com o mesmo TTL, o cache automático não tem efeito.
* Se o último bloco tiver um `cache_control` explícito com um TTL diferente, a API retorna um erro 400.
* Se já existirem 4 breakpoints explícitos em nível de bloco, a API retorna um erro 400 (não sobram slots para o cache automático).
* Se o último bloco não for elegível como alvo de ponto de interrupção de cache automático, o sistema retrocede silenciosamente para encontrar o bloco elegível mais próximo. Se nenhum for encontrado, o cache é ignorado.

<Note>
  O cache automático está disponível em todas as plataformas, exceto no [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-amazon-bedrock-legacy). Nele, a API retorna um erro 400 para um campo `cache_control` de nível superior, então use [pontos de interrupção de cache explícitos](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#explicit-cache-breakpoints) em vez disso.
</Note>

***

## Pontos de interrupção de cache explícitos

Para ter mais controle sobre o cache, você pode colocar `cache_control` diretamente em blocos de conteúdo individuais. Isso é útil quando você precisa armazenar em cache seções diferentes que mudam em frequências diferentes, ou precisa de controle refinado sobre exatamente o que é armazenado em cache.

### Estruturando seu prompt

Coloque o conteúdo estático (definições de ferramentas, instruções do sistema, contexto, exemplos) no início do seu prompt. Marque o fim do conteúdo reutilizável para cache usando o parâmetro `cache_control`.

Os prefixos de cache são criados na seguinte ordem: `tools`, `system` e depois `messages`. Essa ordem forma uma hierarquia em que cada nível se baseia nos anteriores.

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

Você pode usar apenas um ponto de interrupção de cache no fim do seu conteúdo estático, e o sistema encontra automaticamente o prefixo mais longo que uma solicitação anterior já gravou no cache. Entender como isso funciona ajuda você a otimizar sua estratégia de cache.

**Três princípios fundamentais:**

1. **Gravações de cache ocorrem apenas no seu breakpoint.** Marcar um bloco com `cache_control` grava exatamente uma entrada de cache: um hash do prefixo que termina nesse bloco. O sistema não grava entradas para nenhuma posição anterior. Como o hash é cumulativo, cobrindo tudo até o breakpoint, inclusive, alterar qualquer bloco no breakpoint ou antes dele produz um hash diferente na próxima solicitação.

2. **Leituras de cache procuram retroativamente entradas que solicitações anteriores gravaram.** Em cada solicitação, o sistema calcula o hash do prefixo no seu breakpoint e verifica se há uma entrada de cache correspondente. Se não existir nenhuma, ele retrocede um bloco por vez, verificando se o hash do prefixo em cada posição anterior corresponde a algo que já está no cache. Ele procura gravações anteriores, não conteúdo estável.

3. **A janela de retrospecção é de 20 blocos.** O sistema verifica no máximo 20 posições para cada breakpoint, contando o próprio breakpoint como a primeira. Se o sistema não encontrar nenhuma entrada correspondente nessa janela, a verificação para (ou é retomada a partir do próximo breakpoint explícito, se houver). Na Claude API, uma sequência de blocos `tool_use` consecutivos conta como uma posição, assim como uma sequência de blocos `tool_result` consecutivos, de modo que um turno com muitas chamadas de ferramentas paralelas não empurra sozinho a entrada da solicitação anterior para fora da janela.

**Exemplo: Retrospecção em uma conversa crescente**

Você adiciona novos blocos a cada turno e define `cache_control` no bloco final de cada solicitação:

* **Turno 1:** 10 blocos, breakpoint no bloco 10. Não existem entradas de cache anteriores. O sistema grava uma entrada no bloco 10.
* **Turno 2:** 15 blocos, breakpoint no bloco 15. O bloco 15 não tem entrada, então o sistema retrocede até o bloco 10 e encontra a entrada do turno 1. Acerto de cache no bloco 10. O sistema processa do zero apenas os blocos 11 a 15 e grava uma nova entrada no bloco 15.
* **Turno 3:** 35 blocos, breakpoint no bloco 35. O sistema verifica 20 posições (blocos 35 a 16) e não encontra nada. A entrada do turno 2 no bloco 15 está uma posição fora da janela, então não há acerto de cache. Adicionar um segundo breakpoint no bloco 15 inicia uma segunda janela de retrospecção ali, que encontra a entrada do turno 2.

**Erro comum: Breakpoint em conteúdo que muda a cada solicitação**

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

* **Solicitação 1:** Gravação de cache no bloco 6. O hash inclui o timestamp.
* **Solicitação 2:** O timestamp é diferente, então o hash do prefixo no bloco 6 é diferente. A retrospecção percorre os blocos 5, 4, 3, 2 e 1, mas o sistema nunca gravou uma entrada em nenhuma dessas posições. Nenhum acerto de cache. Você paga por uma nova gravação de cache em cada solicitação e nunca obtém uma leitura.

A retrospecção não encontra conteúdo estável atrás do seu breakpoint para armazená-lo em cache. Ela encontra entradas que solicitações anteriores já gravaram, e as gravações ocorrem apenas nos breakpoints. Mova `cache_control` para o bloco 5, o último bloco que permanece igual entre solicitações, e cada solicitação subsequente lerá o prefixo em cache. O [cache automático](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#automatic-caching) tem o mesmo problema: ele coloca o breakpoint no último bloco armazenável em cache, que nessa estrutura é aquele que muda a cada solicitação, então use um breakpoint explícito no bloco 5 em vez disso.

**Principal conclusão:** Coloque `cache_control` no último bloco cujo prefixo é idêntico entre as solicitações que você deseja que compartilhem um cache. Em uma conversa crescente, o bloco final funciona desde que cada turno adicione menos de 20 blocos: o conteúdo anterior nunca muda, então a retrospecção da próxima solicitação encontra a gravação anterior. Para um prompt com um sufixo variável (timestamps, contexto por solicitação, a mensagem recebida), coloque o breakpoint no fim do prefixo estático, não no bloco variável.

#### Quando usar múltiplos breakpoints

Você pode definir até 4 pontos de interrupção de cache se quiser:

* Armazenar em cache seções diferentes que mudam em frequências diferentes (por exemplo, as ferramentas raramente mudam, mas o contexto é atualizado diariamente)
* Ter mais controle sobre exatamente o que é armazenado em cache
* Garantir um acerto de cache quando uma conversa crescente empurra seu breakpoint 20 ou mais blocos além da última gravação de cache

<Note>
  **Limitação importante:** A retrospecção só pode encontrar entradas que solicitações anteriores já gravaram. Se uma conversa crescente empurrar seu breakpoint 20 ou mais blocos além da última gravação, a janela de retrospecção não a encontra. Adicione desde o início um segundo breakpoint mais próximo dessa posição para que uma gravação se acumule ali antes que você precise dela.
</Note>

### Entendendo os custos de cache breakpoints

**Os pontos de interrupção de cache em si não adicionam nenhum custo.** Você só é cobrado por:

* **Gravações de cache:** Quando novo conteúdo é gravado no cache (25% a mais que os tokens de entrada base para TTL de 5 minutos)
* **Leituras de cache:** Quando o conteúdo em cache é usado (10% do preço base dos tokens de entrada, com [exceções por modelo](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#pricing))
* **Tokens de entrada regulares:** Para qualquer conteúdo não armazenado em cache

Adicionar mais breakpoints `cache_control` não aumenta seus custos; você continua pagando o mesmo valor com base no conteúdo que é realmente armazenado e lido do cache. Os breakpoints dão a você controle sobre quais seções podem ser armazenadas em cache de forma independente.

***

## Estratégias e considerações de cache

### Limitações do cache

Na Claude API, na [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), em [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/google-managed) e no [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry), o comprimento mínimo de prompt armazenável em cache é:

* 512 tokens para Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/pt-BR/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/pt-BR/models/mythos-5-1/overview), Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/pt-BR/models/mythos-5/overview) e Claude Haiku 5.5
* 2.048 tokens para [Claude Mythos Preview](https://anthropic.com/glasswing) e Claude Opus 4.7
* 4.096 tokens para Claude Opus 4.6 e Claude Opus 4.5
* 1.024 tokens para Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 ([descontinuado](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)), Claude Opus 4.1 ([desativado, exceto em Claude Models on Google Cloud (Google managed) e no Bedrock](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)), Claude Opus 4 ([desativado, exceto em Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) e Claude Sonnet 4 ([desativado, exceto em Claude Models on Google Cloud (Google managed) e no Bedrock](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations))
* 4.096 tokens para Claude Haiku 4.5

Esses mínimos se aplicam em cada uma dessas plataformas onde o modelo está disponível.

Prompts mais curtos não podem ser armazenados em cache, mesmo se marcados com `cache_control`. Quaisquer solicitações para armazenar em cache menos que esse número de tokens são processadas sem cache, e nenhum erro é retornado. Para verificar se um prompt foi armazenado em cache, observe os [campos de uso da resposta](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#tracking-cache-performance): se tanto `cache_creation_input_tokens` quanto `cache_read_input_tokens` forem 0, o prompt não foi armazenado em cache (provavelmente porque não atendeu ao requisito de comprimento mínimo).

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

<Note>
  O [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-amazon-bedrock) é uma plataforma operada pela AWS. No Amazon Bedrock, consulte a [documentação de cache de prompt do Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) para os mínimos por modelo, o comportamento em caso de falha e os nomes dos campos de uso aplicáveis.
</Note>

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

`ephemeral` é o único tipo de cache suportado, que por padrão tem um tempo de vida de 5 minutos.

### O que pode ser armazenado em cache

A maioria dos blocos da solicitação pode ser armazenada em cache. Isso inclui:

* Ferramentas: definições de ferramentas no array `tools`
* Mensagens do sistema: blocos de conteúdo no array `system`
* Mensagens de texto: blocos de conteúdo no array `messages.content`, tanto em turnos do usuário quanto do assistente
* Imagens e documentos: blocos de conteúdo no array `messages.content`, em turnos do usuário
* Uso de ferramentas e resultados de ferramentas: blocos de conteúdo no array `messages.content`, tanto em turnos do usuário quanto do assistente

Cada um desses elementos pode ser armazenado em cache, automaticamente ou marcando-os com `cache_control`.

### O que não pode ser armazenado em cache

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

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

* Blocos de subconteúdo (como [citações](https://platform.claude.com/docs/pt-BR/build-with-claude/citations)) 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 as citações podem ser armazenados em cache. Isso permite que você use o cache de prompt com citações de forma eficaz, armazenando em cache os documentos que as citações referenciam.

* 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](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#structuring-your-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.

| O que muda                                                                          | Cache de ferramentas | Cache do sistema     | Cache de mensagens   | Impacto                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------------------- | -------------------- | -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Definições de ferramentas**                                                       | ✘                    | ✘                    | ✘                    | Modificar definições de ferramentas (nomes, descrições, parâmetros) invalida o cache inteiro                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Ativação da pesquisa na web**                                                     | ✓                    | ✘                    | ✘                    | Ativar/desativar a pesquisa na web modifica o prompt do sistema                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **Ativação de citações**                                                            | ✓                    | ✘                    | ✘                    | Ativar/desativar citações modifica o prompt do sistema                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **Configuração de velocidade**                                                      | ✓                    | ✘                    | ✘                    | Alternar entre [`speed: "fast"` e a velocidade padrão](https://platform.claude.com/docs/pt-BR/build-with-claude/fast-mode) invalida os caches do sistema e de mensagens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Escolha de ferramenta**                                                           | ✓                    | ✓                    | ✘                    | Alterações no parâmetro `tool_choice` afetam apenas os blocos de mensagens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **Imagens**                                                                         | ✓                    | ✓                    | ✘                    | Adicionar/remover imagens em qualquer lugar do prompt afeta os blocos de mensagens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **Parâmetros de pensamento**                                                        | Específico do modelo | Específico do modelo | ✘                    | A configuração de pensamento (modo e `budget_tokens` no modo estendido) é renderizada no prompt, então alterá-la sempre invalida os blocos de mensagens; os caches de ferramentas e do sistema também são invalidados em modelos que renderizam a configuração antes deles. Consulte [Pensamento e cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-prompt-caching).                                                                                                                                                                                                                                                                                                     |
| **Configuração de esforço**                                                         | Específico do modelo | Específico do modelo | ✘                    | Alterar o valor de [`output_config.effort`](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) pode invalidar os blocos de mensagens e, em alguns modelos, também os caches de ferramentas e do sistema (consulte [Pensamento e cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-prompt-caching)). Definir o esforço explicitamente como o padrão do modelo equivale a omiti-lo e não invalida. Em modelos que suportam [esforço por mensagem](https://platform.claude.com/docs/pt-BR/build-with-claude/effort-per-message), uma alteração de esforço transmitida em uma mensagem `role: "system"` dentro de `messages` mantém o prefixo em cache intacto. |
| **Resultados que não são de ferramentas passados para solicitações com pensamento** | ✓                    | ✓                    | Específico do modelo | No Claude Opus 4.5 e em modelos Opus posteriores, no Claude Sonnet 4.6 e em modelos Sonnet posteriores, no Claude Haiku 5.5 e em todos os modelos Claude Fable e Claude Mythos, os blocos de pensamento são preservados por padrão, então o cache permanece válido (✓). Em outros modelos, todos os blocos de pensamento previamente armazenados em cache são removidos do contexto, e quaisquer mensagens que sigam esses blocos de pensamento são removidas do cache (✘). Para mais detalhes, consulte [Cache com blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#caching-with-thinking-blocks).                                                                        |
| **Blocos de pensamento descartados**                                                | ✓                    | ✓                    | ✘                    | Quando a API descarta um bloco de pensamento que não é [preservado](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserved-thinking) naquela solicitação, o prefixo em cache muda a partir da posição desse bloco naquela solicitação. Blocos que o modelo receptor consegue ler, devolvidos sem alteração, mantêm o cache intacto.                                                                                                                                                                                                                                                                                                                                                                |

Em modelos que suportam [alterações de ferramentas no meio da conversa](https://platform.claude.com/docs/pt-BR/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), o cabeçalho beta `inline-tools-2026-09-15` permite adicionar uma ferramenta, ou alterar a definição de uma ferramenta, no meio de uma conversa sem editar `tools`. Envie a definição em um bloco `tool_addition` em uma mensagem do sistema no meio da conversa e mantenha `tools` exatamente como você o enviou inicialmente. O prefixo em cache continua correspondendo, então apenas a mensagem adicionada é processada como nova entrada. A única exceção é um array `tools` sem nenhuma ferramenta não adiada, em que a primeira ferramenta definida dessa forma custa uma falha de cache completa naquela solicitação. Consulte [Definir ferramentas em uma mensagem](https://platform.claude.com/docs/pt-BR/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta).

<Note>
  No Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/pt-BR/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/pt-BR/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/pt-BR/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5 e Claude Haiku 5.5, você pode adicionar uma nova instrução de sistema no meio de uma conversa sem invalidar os caches do sistema ou de mensagens. Adicione uma mensagem `{"role": "system"}` a `messages` em vez de editar o campo `system` de nível superior, para que o prefixo em cache permaneça inalterado. Este recurso não está disponível no Claude Sonnet 5. Use o campo `system` de nível superior em vez disso. Consulte [Mensagens do sistema e alterações de ferramentas no meio da conversa](https://platform.claude.com/docs/pt-BR/build-with-claude/mid-conversation-system-messages).
</Note>

### Acompanhando o desempenho do cache

Monitore o desempenho do cache usando estes campos de resposta da API, dentro de `usage` na resposta (ou no evento `message_start` se estiver usando [streaming](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming)):

* `cache_creation_input_tokens`: Número de tokens gravados no cache ao criar uma nova entrada
* `cache_read_input_tokens`: Número de tokens recuperados do cache para esta solicitação
* `input_tokens`: Número de tokens de entrada que não foram lidos do cache nem usados para criar um cache (ou seja, tokens após o último ponto de interrupção de cache)

<Note>
  **Entendendo a divisão de tokens**

  O campo `input_tokens` representa apenas os tokens que vêm **após o último ponto de interrupção de cache** na sua solicitação, não todos os tokens de entrada que você enviou.

  Para calcular o total de tokens de entrada:

  ```text wrap
  total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
  ```

  **Explicação espacial:**

  * `cache_read_input_tokens` = tokens antes do breakpoint já em cache (leituras)
  * `cache_creation_input_tokens` = tokens antes do breakpoint sendo armazenados em cache agora (gravações)
  * `input_tokens` = tokens após seu último breakpoint (não elegíveis para cache)

  **Exemplo:** Se você tem uma solicitação com 100.000 tokens de conteúdo em cache (lidos do cache), 0 tokens de novo conteúdo sendo armazenado em cache e 50 tokens na sua mensagem de usuário (após o ponto de interrupção de cache):

  * `cache_read_input_tokens`: 100.000
  * `cache_creation_input_tokens`: 0
  * `input_tokens`: 50
  * **Total de tokens de entrada processados:** 100.050 tokens

  Isso é importante para entender tanto os custos quanto os limites de taxa, pois `input_tokens` normalmente é muito menor que sua entrada total ao usar o cache de forma eficaz.
</Note>

### Cache com blocos de pensamento

Ao usar [pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) com cache de prompt, os blocos de pensamento têm um comportamento especial:

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

**Contagem de tokens de entrada:** Quando os blocos de pensamento são lidos do cache, eles contam como tokens de entrada nas suas métricas de uso. Isso é importante para o cálculo de custos e o orçamento de tokens.

**Padrões de invalidação do cache:**

* O cache permanece válido quando apenas resultados de ferramentas são fornecidos como mensagens do usuário.
* No Claude Opus 4.5 e em modelos Opus posteriores, no Claude Sonnet 4.6 e em modelos Sonnet posteriores, no Claude Haiku 5.5 e em todos os modelos Claude Fable e Claude Mythos, os blocos de pensamento são preservados por padrão mesmo quando conteúdo de usuário que não é resultado de ferramenta é adicionado, então o cache permanece válido.
* Em outros modelos, adicionar conteúdo de usuário que não é resultado de ferramenta invalida o cache e remove todos os blocos de pensamento anteriores do contexto.
* Esse comportamento de cache ocorre mesmo sem marcadores `cache_control` explícitos.

Para mais detalhes sobre a invalidação do cache, consulte [O que invalida o cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#what-invalidates-the-cache).

**Exemplo com uso de ferramentas:**

```text wrap
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]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)
```

Nos [modelos que mantêm o pensamento anterior](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#caching-with-thinking-blocks), os blocos de pensamento anteriores permanecem no contexto por padrão e continuam sendo parte do prefixo em cache. Em outros modelos, todos os blocos de pensamento anteriores são removidos do contexto neste ponto.

Para informações mais detalhadas, consulte [Pensamento e cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-prompt-caching).

### Armazenamento e compartilhamento de cache

<Warning>
  O cache de prompt usa isolamento em nível de [workspace](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces). Os caches são isolados por workspace, garantindo a separação de dados entre workspaces dentro da mesma organização. Isso se aplica à Claude API, à Claude Platform on AWS e ao Microsoft Foundry; Claude Models on Google Cloud (Google managed) e o Bedrock mantêm isolamento de cache em nível de organização. Se você usa múltiplos workspaces, revise sua estratégia de cache para levar em conta essa diferença.
</Warning>

* **Isolamento de organização e workspace:** Os caches são isolados entre organizações. Organizações diferentes nunca compartilham caches, mesmo que usem prompts idênticos. Os caches também são isolados por workspace dentro de uma organização na Claude API, na Claude Platform on AWS e no Microsoft Foundry; Claude Models on Google Cloud (Google managed) e o Bedrock usam apenas isolamento em nível de organização.

* **Correspondência exata:** Acertos de cache exigem segmentos de prompt 100% idênticos, incluindo todo o texto e as imagens até o bloco marcado com controle de cache, inclusive.

* **Geração de tokens de saída:** O cache de prompt não tem efeito na geração de tokens de saída. A resposta que você recebe é idêntica à que você obteria se o cache de prompt não fosse usado.

### Melhores práticas para um cache eficaz

Para otimizar o desempenho do cache de prompt:

* Comece com o [cache automático](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#automatic-caching) para conversas de vários turnos. Ele gerencia os breakpoints automaticamente.
* Use [breakpoints explícitos em nível de bloco](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#explicit-cache-breakpoints) quando precisar armazenar em cache seções diferentes com frequências de alteração diferentes.
* Armazene em cache conteúdo estável e reutilizável, como instruções do sistema, informações de base, contextos grandes ou definições de ferramentas frequentes.
* Coloque o conteúdo em cache no início do prompt para obter o melhor desempenho.
* Use pontos de interrupção de cache estrategicamente para separar diferentes seções de prefixo armazenáveis em cache.
* Coloque o breakpoint no último bloco que permanece idêntico entre solicitações. Para um prompt com um prefixo estático e um sufixo variável (timestamps, contexto por solicitação, a mensagem recebida), esse é o fim do prefixo, não o bloco variável.
* Analise regularmente as taxas de acerto de cache e ajuste sua estratégia conforme necessário.

### Otimizando para diferentes casos de uso

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

* Agentes conversacionais: Reduza o custo e a latência de conversas estendidas, especialmente aquelas com instruções longas ou documentos enviados.
* Assistentes de programação: Melhore o preenchimento automático e as 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 formato longo, incluindo imagens, em seu prompt sem aumentar a latência da resposta.
* Conjuntos de instruções detalhadas: Compartilhe listas extensas de instruções, procedimentos e exemplos para ajustar as respostas do Claude. Os desenvolvedores costumam incluir um ou dois exemplos no prompt, mas com o cache de prompt você pode obter um desempenho ainda melhor incluindo mais de 20 exemplos diversos de respostas de alta qualidade.
* Uso de ferramentas agêntico: Melhore o desempenho em cenários que envolvem múltiplas chamadas de ferramentas e alterações iterativas de código, em que cada etapa normalmente exige uma nova chamada à API.
* Livros, artigos, documentação, transcrições de podcasts e outros conteúdos de formato longo: Torne qualquer base de conhecimento interativa incorporando o(s) documento(s) inteiro(s) no prompt e permitindo que os usuários façam perguntas sobre ele.

### Solução de problemas comuns

Se você enfrentar um comportamento inesperado:

<Tip>
  O [diagnóstico de cache](https://platform.claude.com/docs/pt-BR/build-with-claude/cache-diagnostics) faz com que a API compare solicitações consecutivas e informe onde o prefixo do prompt divergiu, o que cuida automaticamente de muitas das etapas desta lista.
</Tip>

* Certifique-se de que as seções em cache sejam idênticas entre as chamadas. Para breakpoints explícitos, verifique se os marcadores `cache_control` estão nos mesmos locais.
* Verifique se as chamadas são feitas dentro do tempo de vida do cache (5 minutos por padrão).
* Verifique se `tool_choice`, o uso de imagens, a configuração de pensamento e `output_config.effort` permanecem consistentes entre as chamadas.
* Valide se você está armazenando em cache pelo menos o número mínimo de tokens para seu modelo e plataforma (consulte [Limitações do cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#cache-limitations)).
* Confirme se o seu breakpoint está em um bloco que permanece idêntico entre solicitações. Gravações de cache ocorrem apenas no breakpoint e, se esse bloco mudar (timestamps, contexto por solicitação, a mensagem recebida), o hash do prefixo nunca corresponde. A retrospecção não encontra conteúdo estável atrás do breakpoint; ela encontra apenas entradas que solicitações anteriores gravaram em seus próprios breakpoints.
* 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 para JSON, quebrando os caches.
* Use o [diagnóstico de cache](https://platform.claude.com/docs/pt-BR/build-with-claude/cache-diagnostics) para que a API compare solicitações consecutivas e informe qual parte do prompt divergiu.

<Note>
  Alterações em `tool_choice` ou na presença/ausência de imagens em qualquer lugar do prompt invalidam o cache, exigindo que uma nova entrada de cache seja criada. Para mais detalhes sobre a invalidação do cache, consulte [O que invalida o cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#what-invalidates-the-cache).
</Note>

***

## 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 com custo adicional (consulte [Preços](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#pricing)).

<Note>
  A duração de cache de 1 hora está disponível na Claude API, no [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-amazon-bedrock), no [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-amazon-bedrock-legacy), na [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), em [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/google-managed) e no [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry).
</Note>

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

```json
"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}
```

A resposta inclui informações detalhadas de cache como as seguintes:

```json Output
{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}
```

O campo `cache_creation_input_tokens` é igual à soma dos valores no objeto `cache_creation`.

Se você vir gravações `ephemeral_5m_input_tokens` que não solicitou ao usar ferramentas de servidor, como a pesquisa na web, consulte [Resultados de ferramentas de servidor são armazenados em cache automaticamente](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-use-with-prompt-caching#server-tool-results-are-cached-automatically).

### Quando usar o cache de 1 hora

Se você usa um prompt em uma cadência regular (por exemplo, um prompt do sistema que você envia com mais frequência do que a cada 5 minutos), continue usando o cache de 5 minutos, pois ele continua sendo renovado sem custo adicional.

O cache de 1 hora é mais bem utilizado nos seguintes cenários:

* Quando você tem prompts que provavelmente são usados com menos frequência do que a cada 5 minutos, mas com mais frequência do que a cada hora. Por exemplo, quando um agente secundário agêntico leva mais de 5 minutos, ou ao armazenar uma longa conversa de chat 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 após 5 minutos.
* Quando você deseja melhorar a utilização do seu limite de taxa, pois acertos de cache não são deduzidos do seu limite de taxa.

<Note>
  Os caches de 5 minutos e de 1 hora se comportam da mesma forma em relação à latência. Geralmente, você verá uma melhora no tempo até o primeiro token para documentos longos.
</Note>

### Combinando TTLs diferentes

Você pode usar controles de cache de 1 hora e de 5 minutos na mesma solicitação, mas com uma restrição importante: entradas de cache com TTL mais longo devem aparecer antes das com TTLs mais curtos (ou seja, uma entrada de cache de 1 hora deve aparecer antes de quaisquer entradas de cache de 5 minutos).

Ao combinar TTLs, a Claude API determina três locais de cobrança no seu prompt:

1. Posição `A`: A contagem de tokens no último acerto de cache no seu prompt (ou 0 se não houver acertos).

   * Um acerto em uma entrada armazenada em cache com TTL de 5 minutos não é aceito como acerto se um bloco `cache_control` com TTL de 1 hora, posicionado depois dessa entrada, for uma falha de cache.
   * Uma solicitação que lê uma entrada armazenada em cache com TTL de 5 minutos reinicia o tempo de vida de 5 minutos dessa entrada, mesmo que a solicitação atual defina `"ttl": "1h"`.

2. Posição `B`: A contagem de tokens no último bloco `cache_control` de 1 hora posicionado após `A` (ou igual a `A` se não existir nenhum).

3. Posição `C`: A contagem de tokens no último bloco `cache_control`.

<Note>
  Se `B` ou `C` for maior que `A`, trata-se necessariamente de uma falha de cache.
</Note>

Você é cobrado por:

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

Aqui estão três solicitações de exemplo, cada uma com diferentes acertos e falhas de cache. Cada uma tem um preço calculado diferente, mostrado nas caixas.

<Frame>
  ![Três solicitações com diferentes acertos e falhas de cache: A, B e C marcam onde terminam as leituras, as escritas de 1 hora e as escritas de 5 minutos](https://platform.claude.com/docs/pt-BR/images/prompt-cache-mixed-ttl.svg)
</Frame>

***

## Pré-aquecendo o cache

O pré-aquecimento do cache permite carregar seu prompt do sistema ou definições de ferramentas no cache de prompt antes que um usuário acione uma solicitação real. Isso pode reduzir a penalidade de latência por falha de cache na primeira interação do usuário, diminuindo o “time-to-first-token” (tempo até o primeiro token), ou TTFT, para aplicações sensíveis à latência.

### Como funciona

Defina `max_tokens: 0` na sua solicitação. A API lê seu prompt no modelo e escreve o cache em qualquer ponto de interrupção `cache_control`, e então retorna imediatamente sem gerar nenhuma saída. A resposta tem um array `content` vazio, `stop_reason: "max_tokens"` e um bloco `usage` totalmente preenchido.

Coloque o ponto de interrupção `cache_control` no último bloco compartilhado com a solicitação subsequente (normalmente seu prompt do sistema ou definições de ferramentas), não na mensagem de usuário de preenchimento. Caso contrário, a entrada de cache fica associada ao preenchimento e a solicitação subsequente não a acertará. Use também a mesma configuração de pensamento e o mesmo `output_config.effort` das suas solicitações subsequentes: esses valores são renderizados no prompt (consulte [O que invalida o cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#what-invalidates-the-cache)), portanto um pré-aquecimento com uma configuração diferente pode escrever uma entrada que seu tráfego real nunca acerta. Isso significa usar um [ponto de interrupção de cache explícito](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#explicit-cache-breakpoints) em vez do [cache automático](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#automatic-caching), porque o cache automático coloca o ponto de interrupção no último bloco, que aqui é o preenchimento. A mensagem de usuário de preenchimento pode ser qualquer string com conteúdo que não seja apenas espaços em branco (os exemplos aqui usam `"warmup"`); seu conteúdo é lido no modelo, mas nunca respondido.

<Note>
  Uma solicitação de pré-aquecimento incorre em uma cobrança de **escrita de cache** se o prefixo ainda não estiver em cache, assim como qualquer outra solicitação. Verifique `usage.cache_creation_input_tokens` na resposta para confirmar que uma escrita ocorreu. Zero tokens de saída são cobrados.
</Note>

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 0,
      "system": [
        {
          "type": "text",
          "text": "You are an expert software engineer with deep knowledge of distributed systems...",
          "cache_control": {"type": "ephemeral"}
        }
      ],
      "messages": [{"role": "user", "content": "warmup"}]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 0
  system:
    - type: text
      text: >-
        You are an expert software engineer with deep knowledge of
        distributed systems...
      cache_control:
        type: ephemeral
  messages:
    - role: user
      content: warmup
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  # Dispare isto antes da chegada dos usuários para aquecer o cache compartilhado do prompt do sistema.
  prewarm = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=0,
      system=[
          {
              "type": "text",
              "text": "You are an expert software engineer with deep knowledge of distributed systems...",
              "cache_control": {"type": "ephemeral"},
          }
      ],
      messages=[{"role": "user", "content": "warmup"}],
  )
  print(prewarm.stop_reason)  # "max_tokens"
  print(prewarm.content)  # []
  print(prewarm.usage)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // Dispare isto antes de os usuários chegarem para aquecer o cache compartilhado do prompt do sistema.
  const prewarm = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 0,
    system: [
      {
        type: "text",
        text: "You are an expert software engineer with deep knowledge of distributed systems...",
        cache_control: { type: "ephemeral" }
      }
    ],
    messages: [{ role: "user", content: "warmup" }]
  });
  console.log(prewarm.stop_reason); // "max_tokens"
  console.log(prewarm.content); // []
  console.log(prewarm.usage);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var prewarm = await client.Messages.Create(
      new()
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 0,
          System = new(
              [
                  new TextBlockParam
                  {
                      Text = "You are an expert software engineer with deep knowledge of distributed systems...",
                      CacheControl = new(),
                  },
              ]
          ),
          Messages = [new UserMessageParam { Content = "warmup" }],
      }
  );

  Console.WriteLine(prewarm.StopReason?.Raw()); // "max_tokens"
  Console.WriteLine(prewarm.Content.Count); // 0
  Console.WriteLine(prewarm.Usage);
  ```

  ```go Go
  client := anthropic.NewClient()

  prewarm, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 0,
  	System: []anthropic.TextBlockParam{
  		{
  			Text:         "You are an expert software engineer with deep knowledge of distributed systems...",
  			CacheControl: anthropic.NewCacheControlEphemeralParam(),
  		},
  	},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
  	},
  })
  if err != nil {
  	panic(err)
  }

  fmt.Println(prewarm.StopReason) // "max_tokens"
  fmt.Println(prewarm.Content)    // []
  fmt.Println(prewarm.Usage.RawJSON())
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  Message prewarm = client.messages().create(MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(0)
      .systemOfTextBlockParams(List.of(TextBlockParam.builder()
          .text("You are an expert software engineer with deep knowledge of distributed systems...")
          .cacheControl(CacheControlEphemeral.builder().build())
          .build()))
      .addUserMessage("warmup")
      .build());

  IO.println(prewarm.stopReason()); // Optional[max_tokens]
  IO.println(prewarm.content());    // []
  IO.println(prewarm.usage());
  ```

  ```php PHP
  $client = new Client();

  $prewarm = $client->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 0,
      system: [
          [
              'type' => 'text',
              'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
              'cache_control' => ['type' => 'ephemeral'],
          ],
      ],
      messages: [['role' => 'user', 'content' => 'warmup']],
  );

  echo $prewarm->stopReason, PHP_EOL; // "max_tokens"
  echo json_encode($prewarm->content), PHP_EOL; // []
  echo json_encode($prewarm->usage), PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  prewarm = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 0,
    system_: [
      {
        type: "text",
        text: "You are an expert software engineer with deep knowledge of distributed systems...",
        cache_control: {type: "ephemeral"}
      }
    ],
    messages: [{role: "user", content: "warmup"}]
  )

  puts prewarm.stop_reason # :max_tokens
  puts prewarm.content # []
  puts prewarm.usage
  ```
</CodeGroup>

A API retorna um array `content` vazio:

```json Output
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}
```

### Padrão de uso típico

Faça uma solicitação de pré-aquecimento quando sua aplicação iniciar (ou em um intervalo programado) e, em seguida, envie solicitações reais de usuários após a conclusão do pré-aquecimento:

<CodeGroup>
  ```bash cURL
  # Aqueça o cache na inicialização do aplicativo ou em um intervalo agendado.
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 0,
      "system": [
        {
          "type": "text",
          "text": "You are an expert software engineer with deep knowledge of distributed systems...",
          "cache_control": {"type": "ephemeral"}
        }
      ],
      "messages": [{"role": "user", "content": "warmup"}]
    }'

  # Depois, quando o usuário enviar uma mensagem, o prefixo do prompt do sistema já estará em cache.
  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "system": [
        {
          "type": "text",
          "text": "You are an expert software engineer with deep knowledge of distributed systems...",
          "cache_control": {"type": "ephemeral"}
        }
      ],
      "messages": [{"role": "user", "content": "How do I implement a binary search tree?"}]
    }'
  ```

  ```bash CLI
  # Aqueça o cache na inicialização da aplicação ou em um intervalo agendado.
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 0
  system:
    - type: text
      text: >-
        You are an expert software engineer with deep knowledge of
        distributed systems...
      cache_control:
        type: ephemeral
  messages:
    - role: user
      content: warmup
  YAML

  # Depois, quando o usuário envia uma mensagem, o prefixo do prompt do sistema já está em cache.
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  system:
    - type: text
      text: >-
        You are an expert software engineer with deep knowledge of
        distributed systems...
      cache_control:
        type: ephemeral
  messages:
    - role: user
      content: How do I implement a binary search tree?
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  SYSTEM_PROMPT = [
      {
          "type": "text",
          "text": "You are an expert software engineer with deep knowledge of distributed systems...",
          "cache_control": {"type": "ephemeral"},
      }
  ]


  def prewarm_cache() -> None:
      """Call this at application startup or on a scheduled interval."""
      client.messages.create(
          model="claude-opus-5-5",
          max_tokens=0,
          system=SYSTEM_PROMPT,
          messages=[{"role": "user", "content": "warmup"}],
      )


  def respond(user_message: str) -> anthropic.types.Message:
      """The real user request; benefits from a warm cache."""
      return client.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          system=SYSTEM_PROMPT,
          messages=[{"role": "user", "content": user_message}],
      )


  # Aqueça o cache antes que chegue qualquer tráfego de usuários.
  prewarm_cache()

  # Depois, quando o usuário envia uma mensagem, o prefixo do prompt do sistema já está em cache.
  response = respond("How do I implement a binary search tree?")
  for block in response.content:
      if block.type == "text":
          print(block.text)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const SYSTEM_PROMPT: Anthropic.TextBlockParam[] = [
    {
      type: "text",
      text: "You are an expert software engineer with deep knowledge of distributed systems...",
      cache_control: { type: "ephemeral" }
    }
  ];

  // Chame isto na inicialização da aplicação ou em um intervalo agendado.
  async function prewarmCache(): Promise<void> {
    await client.messages.create({
      model: "claude-opus-5-5",
      max_tokens: 0,
      system: SYSTEM_PROMPT,
      messages: [{ role: "user", content: "warmup" }]
    });
  }

  // A requisição real do usuário; se beneficia de um cache já aquecido.
  async function respond(userMessage: string): Promise<Anthropic.Message> {
    return client.messages.create({
      model: "claude-opus-5-5",
      max_tokens: 1024,
      system: SYSTEM_PROMPT,
      messages: [{ role: "user", content: userMessage }]
    });
  }

  // Aqueça o cache antes que qualquer tráfego de usuários chegue.
  await prewarmCache();

  // Depois, quando o usuário enviar uma mensagem, o prefixo do prompt do sistema já estará em cache.
  const response = await respond("How do I implement a binary search tree?");
  const textBlock = response.content.find((block) => block.type === "text");
  console.log(textBlock?.text);
  ```

  ```csharp C#
  AnthropicClient client = new();

  List<TextBlockParam> systemPrompt =
  [
      new TextBlockParam
      {
          Text = "You are an expert software engineer with deep knowledge of distributed systems...",
          CacheControl = new(),
      },
  ];

  // Chame isto na inicialização da aplicação ou em um intervalo agendado.
  async Task PrewarmCache() =>
      await client.Messages.Create(
          new()
          {
              Model = Model.ClaudeOpus5_5,
              MaxTokens = 0,
              System = new(systemPrompt),
              Messages = [new UserMessageParam { Content = "warmup" }],
          }
      );

  // A solicitação real do usuário; se beneficia de um cache já aquecido.
  async Task<Message> Respond(string userMessage) =>
      await client.Messages.Create(
          new()
          {
              Model = Model.ClaudeOpus5_5,
              MaxTokens = 1024,
              System = new(systemPrompt),
              Messages = [new UserMessageParam { Content = userMessage }],
          }
      );

  // Aqueça o cache antes que qualquer tráfego de usuário chegue.
  await PrewarmCache();

  // Depois, quando o usuário enviar uma mensagem, o prefixo do prompt do sistema já estará em cache.
  var response = await Respond("How do I implement a binary search tree?");
  foreach (var block in response.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

  ```go Go
  var client = anthropic.NewClient()

  var systemPrompt = []anthropic.TextBlockParam{
  	{
  		Text:         "You are an expert software engineer with deep knowledge of distributed systems...",
  		CacheControl: anthropic.NewCacheControlEphemeralParam(),
  	},
  }

  // Chame isto na inicialização da aplicação ou em um intervalo agendado.
  func prewarmCache() error {
  	_, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  		Model:     anthropic.ModelClaudeOpus5_5,
  		MaxTokens: 0,
  		System:    systemPrompt,
  		Messages: []anthropic.MessageParam{
  			anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
  		},
  	})
  	return err
  }

  // A requisição real do usuário; beneficia-se de um cache aquecido.
  func respond(userMessage string) (*anthropic.Message, error) {
  	return client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  		Model:     anthropic.ModelClaudeOpus5_5,
  		MaxTokens: 1024,
  		System:    systemPrompt,
  		Messages: []anthropic.MessageParam{
  			anthropic.NewUserMessage(anthropic.NewTextBlock(userMessage)),
  		},
  	})
  }

  func main() {
  	// Aqueça o cache antes que chegue qualquer tráfego de usuários.
  	if err := prewarmCache(); err != nil {
  		log.Fatal(err)
  	}

  	// Depois, quando o usuário enviar uma mensagem, o prefixo do prompt do sistema já estará em cache.
  	response, err := respond("How do I implement a binary search tree?")
  	if err != nil {
  		log.Fatal(err)
  	}
  	for _, block := range response.Content {
  		if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
  			fmt.Println(textBlock.Text)
  		}
  	}
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  List<TextBlockParam> systemPrompt = List.of(TextBlockParam.builder()
      .text("You are an expert software engineer with deep knowledge of distributed systems...")
      .cacheControl(CacheControlEphemeral.builder().build())
      .build());

  // Chame isto na inicialização da aplicação ou em um intervalo agendado.
  void prewarmCache() {
      client.messages().create(MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(0)
          .systemOfTextBlockParams(systemPrompt)
          .addUserMessage("warmup")
          .build());
  }

  // A requisição real do usuário; se beneficia de um cache aquecido.
  Message respond(String userMessage) {
      return client.messages().create(MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024)
          .systemOfTextBlockParams(systemPrompt)
          .addUserMessage(userMessage)
          .build());
  }

  void main() {
      // Aqueça o cache antes que qualquer tráfego de usuários chegue.
      prewarmCache();

      // Depois, quando o usuário enviar uma mensagem, o prefixo do prompt do sistema já estará em cache.
      Message response = respond("How do I implement a binary search tree?");
      response.content().stream()
          .flatMap(block -> block.text().stream())
          .forEach(textBlock -> IO.println(textBlock.text()));
  }
  ```

  ```php PHP
  $client = new Client();

  $systemPrompt = [
      [
          'type' => 'text',
          'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
          'cache_control' => ['type' => 'ephemeral'],
      ],
  ];

  // Chame isto na inicialização da aplicação ou em um intervalo agendado.
  $prewarmCache = fn () => $client->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 0,
      system: $systemPrompt,
      messages: [['role' => 'user', 'content' => 'warmup']],
  );

  // A solicitação real do usuário; se beneficia de um cache aquecido.
  $respond = fn (string $userMessage) => $client->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 1024,
      system: $systemPrompt,
      messages: [['role' => 'user', 'content' => $userMessage]],
  );

  // Aqueça o cache antes que chegue qualquer tráfego de usuários.
  $prewarmCache();

  // Depois, quando o usuário enviar uma mensagem, o prefixo do prompt do sistema já estará em cache.
  $response = $respond('How do I implement a binary search tree?');
  foreach ($response->content as $block) {
      if ($block instanceof \Anthropic\Messages\TextBlock) {
          echo $block->text, PHP_EOL;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  SYSTEM_PROMPT = [
    {
      type: "text",
      text: "You are an expert software engineer with deep knowledge of distributed systems...",
      cache_control: {type: "ephemeral"}
    }
  ]

  # Chame isto na inicialização da aplicação ou em um intervalo agendado.
  def prewarm_cache(client)
    client.messages.create(
      model: Anthropic::Model::CLAUDE_OPUS_5_5,
      max_tokens: 0,
      system_: SYSTEM_PROMPT,
      messages: [{role: "user", content: "warmup"}]
    )
  end

  # A requisição real do usuário; beneficia-se de um cache já aquecido.
  def respond(client, user_message)
    client.messages.create(
      model: Anthropic::Model::CLAUDE_OPUS_5_5,
      max_tokens: 1024,
      system_: SYSTEM_PROMPT,
      messages: [{role: "user", content: user_message}]
    )
  end

  # Aqueça o cache antes que chegue qualquer tráfego de usuários.
  prewarm_cache(client)

  # Depois, quando o usuário enviar uma mensagem, o prefixo do prompt do sistema já estará em cache.
  response = respond(client, "How do I implement a binary search tree?")
  response.content.each do |block|
    puts block.text if block.is_a?(Anthropic::Models::TextBlock)
  end
  ```
</CodeGroup>

Lembre-se de que o TTL do cache ainda se aplica. Para o cache padrão de 5 minutos, envie uma nova solicitação de pré-aquecimento pelo menos a cada 5 minutos para manter o cache aquecido. Para intervalos mais longos entre solicitações de usuários, use a [duração de cache de 1 hora](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#1-hour-cache-duration) em vez disso.

### Limitações

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

* `stream: true`
* [Pensamento estendido](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking) (`thinking.type: "enabled"`)
* [Saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs) (`output_config.format`)
* `tool_choice` de `{"type": "tool", ...}` ou `{"type": "any"}`

`max_tokens: 0` também é rejeitado dentro de uma solicitação de [Message Batches](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing). O pré-aquecimento visa o time-to-first-token, que não se aplica ao processamento em lote, e uma entrada de cache escrita durante o processamento em lote provavelmente expiraria antes da execução da solicitação subsequente.

### Substituindo a solução alternativa `max_tokens=1`

Algumas aplicações enviam solicitações com `max_tokens: 1` para aquecer o cache. Prefira `max_tokens: 0` quando a solicitação permitir: nenhuma saída é produzida, portanto não há resposta de um único token para descartar, nenhum token de saída é cobrado e a intenção da solicitação é inequívoca.

***

## Exemplos de cache de prompt

Para ajudar você a começar com o “prompt caching” (cache de prompt), a [receita de cache de prompt](https://platform.claude.com/cookbook/misc-prompt-caching) no Claude Cookbook fornece exemplos detalhados e melhores práticas.

Os trechos de código a seguir demonstram vários padrões de cache de prompt. Esses exemplos mostram como implementar o cache em diferentes cenários, ajudando você a entender as aplicações práticas desse recurso:

<AccordionGroup>
  <Accordion title="Exemplo de cache de contexto grande">
    <CodeGroup>
      ```bash cURL
      curl https://api.anthropic.com/v1/messages \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2026-10-21" \
        -H "content-type: application/json" \
        -d '{
          "model": "claude-opus-5-5",
          "max_tokens": 1024,
          "system": [
            {
              "type": "text",
              "text": "You are an AI assistant tasked with analyzing legal documents."
            },
            {
              "type": "text",
              "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
              "cache_control": {"type": "ephemeral"}
            }
          ],
          "messages": [
            {
              "role": "user",
              "content": "What are the key terms and conditions in this agreement?"
            }
          ]
        }'
      ```

      ```bash CLI
      ant messages create <<'YAML'
      model: claude-opus-5-5
      max_tokens: 1024
      system:
        - type: text
          text: You are an AI assistant tasked with analyzing legal documents.
        - type: text
          text: >-
            Here is the full text of a complex legal agreement:
            [Insert full text of a 50-page legal agreement here]
          cache_control:
            type: ephemeral
      messages:
        - role: user
          content: What are the key terms and conditions in this agreement?
      YAML
      ```

      ```python Python
      client = anthropic.Anthropic()

      response = client.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          system=[
              {
                  "type": "text",
                  "text": "You are an AI assistant tasked with analyzing legal documents.",
              },
              {
                  "type": "text",
                  "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
                  "cache_control": {"type": "ephemeral"},
              },
          ],
          messages=[
              {
                  "role": "user",
                  "content": "What are the key terms and conditions in this agreement?",
              }
          ],
      )
      print(response.usage.model_dump_json())
      ```

      ```typescript TypeScript
      const client = new Anthropic();

      const response = await client.messages.create({
        model: "claude-opus-5-5",
        max_tokens: 1024,
        system: [
          {
            type: "text",
            text: "You are an AI assistant tasked with analyzing legal documents."
          },
          {
            type: "text",
            text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            cache_control: { type: "ephemeral" }
          }
        ],
        messages: [
          {
            role: "user",
            content: "What are the key terms and conditions in this agreement?"
          }
        ]
      });
      console.log(response.usage);
      ```

      ```csharp C#
      AnthropicClient client = new()
      {
          ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
      };

      var parameters = new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          System = new MessageCreateParamsSystem(new List<TextBlockParam>
          {
              new TextBlockParam()
              {
                  Text = "You are an AI assistant tasked with analyzing legal documents.",
              },
              new TextBlockParam()
              {
                  Text = "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
                  CacheControl = new CacheControlEphemeral(),
              },
          }),
          Messages =
          [
              new UserMessageParam
              {
                  Content = "What are the key terms and conditions in this agreement?"
              }
          ]
      };

      var message = await client.Messages.Create(parameters);
      Console.WriteLine(message.Usage);
      ```

      ```go Go
      client := anthropic.NewClient()

      response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
      	Model:     anthropic.ModelClaudeOpus5_5,
      	MaxTokens: 1024,
      	System: []anthropic.TextBlockParam{
      		{
      			Text: "You are an AI assistant tasked with analyzing legal documents.",
      		},
      		{
      			Text:         "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
      			CacheControl: anthropic.NewCacheControlEphemeralParam(),
      		},
      	},
      	Messages: []anthropic.MessageParam{
      		anthropic.NewUserMessage(anthropic.NewTextBlock("What are the key terms and conditions in this agreement?")),
      	},
      })
      if err != nil {
      	log.Fatal(err)
      }
      fmt.Println(response.Usage.RawJSON())
      ```

      ```java Java
      import com.anthropic.models.messages.CacheControlEphemeral;
      // ...
      void main() {
          AnthropicClient client = AnthropicOkHttpClient.fromEnv();

          MessageCreateParams params = MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(1024)
              .systemOfTextBlockParams(
                  List.of(
                      TextBlockParam.builder()
                          .text("You are an AI assistant tasked with analyzing legal documents.")
                          .build(),
                      TextBlockParam.builder()
                          .text(
                              "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]"
                          )
                          .cacheControl(CacheControlEphemeral.builder().build())
                          .build()
                  )
              )
              .addUserMessage("What are the key terms and conditions in this agreement?")
              .build();

          Message message = client.messages().create(params);
          IO.println(message.usage());
      }
      ```

      ```php PHP
      $client = new Client();

      $message = $client->messages->create(
          maxTokens: 1024,
          messages: [
              [
                  'role' => 'user',
                  'content' => 'What are the key terms and conditions in this agreement?'
              ]
          ],
          model: Model::CLAUDE_OPUS_5_5,
          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']
              ]
          ],
      );

      echo json_encode($message->usage), PHP_EOL;
      ```

      ```ruby Ruby
      client = Anthropic::Client.new

      message = client.messages.create(
        model: Anthropic::Model::CLAUDE_OPUS_5_5,
        max_tokens: 1024,
        system_: [
          {
            type: "text",
            text: "You are an AI assistant tasked with analyzing legal documents."
          },
          {
            type: "text",
            text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            cache_control: { type: "ephemeral" }
          }
        ],
        messages: [
          {
            role: "user",
            content: "What are the key terms and conditions in this agreement?"
          }
        ]
      )
      puts message.usage
      ```
    </CodeGroup>

    Este exemplo demonstra o uso básico do cache de prompt, armazenando em cache o texto completo do contrato jurídico como prefixo, enquanto mantém a instrução do usuário fora do cache.

    Para a primeira solicitação:

    * `input_tokens`: Número de tokens apenas na mensagem do usuário
    * `cache_creation_input_tokens`: Número de tokens em toda a mensagem do sistema, incluindo o documento jurídico
    * `cache_read_input_tokens`: 0 (nenhum acerto de cache na primeira solicitação)

    Para solicitações subsequentes dentro do tempo de vida do cache:

    * `input_tokens`: Número de tokens apenas na mensagem do usuário
    * `cache_creation_input_tokens`: 0 (nenhuma nova criação de cache)
    * `cache_read_input_tokens`: Número de tokens em toda a mensagem do sistema em cache
  </Accordion>

  <Accordion title="Armazenando definições de ferramentas em cache">
    As definições de ferramentas podem ser armazenadas em cache colocando `cache_control` na última ferramenta do seu array `tools`. Todas as ferramentas definidas antes dessa ferramenta, incluindo ela, são armazenadas em cache como um único prefixo.

    ```json
    {
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "tools": [
        {
          "name": "get_weather",
          "description": "Get the current weather in a given location",
          "input_schema": {
            "type": "object",
            "properties": { "location": { "type": "string" } },
            "required": ["location"]
          }
        },
        {
          "name": "get_time",
          "description": "Get the current time in a given time zone",
          "input_schema": {
            "type": "object",
            "properties": { "timezone": { "type": "string" } },
            "required": ["timezone"]
          },
          "cache_control": { "type": "ephemeral" }
        }
      ],
      "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
    }
    ```

    Na primeira solicitação, `cache_creation_input_tokens` reflete a contagem de tokens de todas as definições de ferramentas. Em solicitações subsequentes dentro do tempo de vida do cache, esses tokens aparecem em `cache_read_input_tokens` em vez disso.

    Para a interação detalhada entre definições de ferramentas, `defer_loading` e invalidação de cache, consulte [Uso de ferramentas com cache de prompt](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-use-with-prompt-caching).
  </Accordion>

  <Accordion title="Continuando uma conversa de múltiplos turnos">
    <CodeGroup>
      ```bash cURL
      curl https://api.anthropic.com/v1/messages \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2026-10-21" \
        -H "content-type: application/json" \
        -d '{
          "model": "claude-opus-5-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"}
                }
              ]
            }
          ]
        }'
      ```

      ```bash CLI
      ant messages create <<'YAML'
      model: claude-opus-5-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
      YAML
      ```

      ```python Python
      client = anthropic.Anthropic()

      response = client.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          system=[
              {
                  "type": "text",
                  "text": "...long system prompt",
                  "cache_control": {"type": "ephemeral"},
              }
          ],
          messages=[
              # ...conversa longa até agora
              {
                  "role": "user",
                  "content": [
                      {
                          "type": "text",
                          "text": "Hello, can you tell me more about the solar system?",
                      }
                  ],
              },
              {
                  "role": "assistant",
                  "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
              },
              {
                  "role": "user",
                  "content": [
                      {"type": "text", "text": "Good to know."},
                      {
                          "type": "text",
                          "text": "Tell me more about Mars.",
                          "cache_control": {"type": "ephemeral"},
                      },
                  ],
              },
          ],
      )
      print(response.usage.model_dump_json())
      ```

      ```typescript TypeScript
      const client = new Anthropic();

      const response = await client.messages.create({
        model: "claude-opus-5-5",
        max_tokens: 1024,
        system: [
          {
            type: "text",
            text: "...long system prompt",
            cache_control: { type: "ephemeral" }
          }
        ],
        messages: [
          // ...conversa longa até aqui
          {
            role: "user",
            content: [
              {
                type: "text",
                text: "Hello, can you tell me more about the solar system?"
              }
            ]
          },
          {
            role: "assistant",
            content:
              "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?"
          },
          {
            role: "user",
            content: [
              {
                type: "text",
                text: "Good to know."
              },
              {
                type: "text",
                text: "Tell me more about Mars.",
                cache_control: { type: "ephemeral" }
              }
            ]
          }
        ]
      });
      console.log(response.usage);
      ```

      ```csharp C#
      AnthropicClient client = new();

      var parameters = new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          System = new MessageCreateParamsSystem(new List<TextBlockParam>
          {
              new TextBlockParam()
              {
                  Text = "...long system prompt",
                  CacheControl = new CacheControlEphemeral(),
              },
          }),
          Messages =
          [
              new UserMessageParam
              {
                  Content = new List<ContentBlockParam>
                  {
                      new ContentBlockParam(new TextBlockParam("Hello, can you tell me more about the solar system?")),
                  },
              },
              new AssistantMessageParam
              {
                  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?"
              },
              new UserMessageParam
              {
                  Content = new List<ContentBlockParam>
                  {
                      new ContentBlockParam(new TextBlockParam("Good to know.")),
                      new ContentBlockParam(new TextBlockParam()
                      {
                          Text = "Tell me more about Mars.",
                          CacheControl = new CacheControlEphemeral(),
                      }),
                  }
              }
          ]
      };

      var message = await client.Messages.Create(parameters);
      Console.WriteLine(message.Usage);
      ```

      ```go Go
      client := anthropic.NewClient()

      response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
      	Model:     anthropic.ModelClaudeOpus5_5,
      	MaxTokens: 1024,
      	System: []anthropic.TextBlockParam{
      		{
      			Text:         "...long system prompt",
      			CacheControl: anthropic.NewCacheControlEphemeralParam(),
      		},
      	},
      	Messages: []anthropic.MessageParam{
      		anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, can you tell me more about the solar system?")),
      		anthropic.NewAssistantMessage(anthropic.NewTextBlock("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?")),
      		anthropic.NewUserMessage(
      			anthropic.NewTextBlock("Good to know."),
      			anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{
      				Text:         "Tell me more about Mars.",
      				CacheControl: anthropic.NewCacheControlEphemeralParam(),
      			}},
      		),
      	},
      })
      if err != nil {
      	log.Fatal(err)
      }
      fmt.Println(response.Usage.RawJSON())
      ```

      ```java Java
      import com.anthropic.models.messages.CacheControlEphemeral;
      // ...
      void main() {
          AnthropicClient client = AnthropicOkHttpClient.fromEnv();

          // Cria prompt do sistema efêmero
          TextBlockParam systemPrompt = TextBlockParam.builder()
              .text("...long system prompt")
              .cacheControl(CacheControlEphemeral.builder().build())
              .build();

          // Cria os parâmetros da mensagem
          MessageCreateParams params = MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(1024)
              .systemOfTextBlockParams(List.of(systemPrompt))
              // Primeira mensagem do usuário (sem controle de cache)
              .addUserMessage("Hello, can you tell me more about the solar system?")
              // Resposta do assistente
              .addAssistantMessage(
                  "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?"
              )
              // Segunda mensagem do usuário (com controle de cache)
              .addUserMessageOfContentBlockParams(
                  List.of(
                      ContentBlockParam.ofText(TextBlockParam.builder()
                          .text("Good to know.")
                          .build()),
                      ContentBlockParam.ofText(
                          TextBlockParam.builder()
                              .text("Tell me more about Mars.")
                              .cacheControl(CacheControlEphemeral.builder().build())
                              .build()
                      )
                  )
              )
              .build();

          Message message = client.messages().create(params);
          IO.println(message.usage());
      }
      ```

      ```php PHP
      $client = new Client();

      $message = $client->messages->create(
          maxTokens: 1024,
          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']
                      ]
                  ]
              ]
          ],
          model: Model::CLAUDE_OPUS_5_5,
          system: [
              [
                  'type' => 'text',
                  'text' => '...long system prompt',
                  'cache_control' => ['type' => 'ephemeral']
              ]
          ],
      );

      echo json_encode($message->usage), PHP_EOL;
      ```

      ```ruby Ruby
      client = Anthropic::Client.new

      message = client.messages.create(
        model: Anthropic::Model::CLAUDE_OPUS_5_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" }
              }
            ]
          }
        ]
      )
      puts message.usage
      ```
    </CodeGroup>

    Este exemplo demonstra como usar o cache de prompt em uma conversa de múltiplos turnos.

    Em cada turno, o bloco final da mensagem final é marcado com `cache_control` para que a conversa possa ser armazenada em cache de forma incremental. O sistema procura e usa automaticamente a sequência de blocos mais longa armazenada anteriormente em cache para mensagens subsequentes. Blocos que foram marcados com `cache_control` em um turno anterior não são marcados novamente, mas uma solicitação dentro de 5 minutos ainda os lê do cache e renova seu tempo de vida.

    O parâmetro `cache_control` também está na mensagem do sistema. Se a mensagem do sistema for removida do cache após mais de 5 minutos sem uso, a próxima solicitação a adiciona de volta.

    Essa abordagem é útil para manter o contexto em conversas contínuas sem processar repetidamente as mesmas informações.

    Quando isso está configurado corretamente, você deverá ver o seguinte na resposta de uso de cada solicitação:

    * `input_tokens`: Número de tokens na nova mensagem do usuário (mínimo)
    * `cache_creation_input_tokens`: Número de tokens nos novos turnos do assistente e do usuário
    * `cache_read_input_tokens`: Número de tokens na conversa até o turno anterior
  </Accordion>

  <Accordion title="Juntando tudo: múltiplos pontos de interrupção de cache">
    <CodeGroup>
      ```bash cURL
      curl https://api.anthropic.com/v1/messages \
        -H "x-api-key: $ANTHROPIC_API_KEY" \
        -H "anthropic-version: 2026-10-21" \
        -H "content-type: application/json" \
        -d '{
          "model": "claude-opus-5-5",
          "max_tokens": 1024,
          "tools": [
            {
              "name": "search_documents",
              "description": "Search through the knowledge base",
              "input_schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search query"
                  }
                },
                "required": ["query"]
              }
            },
            {
              "name": "get_document",
              "description": "Retrieve a specific document by ID",
              "input_schema": {
                "type": "object",
                "properties": {
                  "doc_id": {
                    "type": "string",
                    "description": "Document ID"
                  }
                },
                "required": ["doc_id"]
              },
              "cache_control": {"type": "ephemeral"}
            }
          ],
          "system": [
            {
              "type": "text",
              "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
              "cache_control": {"type": "ephemeral"}
            },
            {
              "type": "text",
              "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
              "cache_control": {"type": "ephemeral"}
            }
          ],
          "messages": [
            {
              "role": "user",
              "content": "Can you search for information about Mars rovers?"
            },
            {
              "role": "assistant",
              "content": [
                {
                  "type": "tool_use",
                  "id": "tool_1",
                  "name": "search_documents",
                  "input": {"query": "Mars rovers"}
                }
              ]
            },
            {
              "role": "user",
              "content": [
                {
                  "type": "tool_result",
                  "tool_use_id": "tool_1",
                  "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
                }
              ]
            },
            {
              "role": "assistant",
              "content": [
                {
                  "type": "text",
                  "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
                }
              ]
            },
            {
              "role": "user",
              "content": [
                {
                  "type": "text",
                  "text": "Yes, please tell me about the Perseverance rover specifically.",
                  "cache_control": {"type": "ephemeral"}
                }
              ]
            }
          ]
        }'
      ```

      ```bash CLI
      ant messages create <<'YAML'
      model: claude-opus-5-5
      max_tokens: 1024
      tools:
        - name: search_documents
          description: Search through the knowledge base
          input_schema:
            type: object
            properties:
              query:
                type: string
                description: Search query
            required: [query]
        - name: get_document
          description: Retrieve a specific document by ID
          input_schema:
            type: object
            properties:
              doc_id:
                type: string
                description: Document ID
            required: [doc_id]
          cache_control:
            type: ephemeral
      system:
        - type: text
          text: |-
            You are a helpful research assistant with access to a document knowledge base.

            # Instructions
            - Always search for relevant documents before answering
            - Provide citations for your sources
            - Be objective and accurate in your responses
            - If multiple documents contain relevant information, synthesize them
            - Acknowledge when information is not available in the knowledge base
          cache_control:
            type: ephemeral
        - type: text
          text: |-
            # Knowledge Base Context

            Here are the relevant documents for this conversation:

            ## Document 1: Solar System Overview
            The solar system consists of the Sun and all objects that orbit it...

            ## Document 2: Planetary Characteristics
            Each planet has unique features. Mercury is the smallest planet...

            ## Document 3: Mars Exploration
            Mars has been a target of exploration for decades...

            [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
      YAML
      ```

      ```python Python
      client = anthropic.Anthropic()

      response = client.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          tools=[
              {
                  "name": "search_documents",
                  "description": "Search through the knowledge base",
                  "input_schema": {
                      "type": "object",
                      "properties": {
                          "query": {"type": "string", "description": "Search query"}
                      },
                      "required": ["query"],
                  },
              },
              {
                  "name": "get_document",
                  "description": "Retrieve a specific document by ID",
                  "input_schema": {
                      "type": "object",
                      "properties": {
                          "doc_id": {"type": "string", "description": "Document ID"}
                      },
                      "required": ["doc_id"],
                  },
                  "cache_control": {"type": "ephemeral"},
              },
          ],
          system=[
              {
                  "type": "text",
                  "text": """You are a helpful research assistant with access to a document knowledge base.

      # Instructions
      - Always search for relevant documents before answering
      - Provide citations for your sources
      - Be objective and accurate in your responses
      - If multiple documents contain relevant information, synthesize them
      - Acknowledge when information is not available in the knowledge base""",
                  "cache_control": {"type": "ephemeral"},
              },
              {
                  "type": "text",
                  "text": """# Knowledge Base Context

      Here are the relevant documents for this conversation:

      ## Document 1: Solar System Overview
      The solar system consists of the Sun and all objects that orbit it...

      ## Document 2: Planetary Characteristics
      Each planet has unique features. Mercury is the smallest planet...

      ## Document 3: Mars Exploration
      Mars has been a target of exploration for decades...

      [Additional documents...]""",
                  "cache_control": {"type": "ephemeral"},
              },
          ],
          messages=[
              {
                  "role": "user",
                  "content": "Can you search for information about Mars rovers?",
              },
              {
                  "role": "assistant",
                  "content": [
                      {
                          "type": "tool_use",
                          "id": "tool_1",
                          "name": "search_documents",
                          "input": {"query": "Mars rovers"},
                      }
                  ],
              },
              {
                  "role": "user",
                  "content": [
                      {
                          "type": "tool_result",
                          "tool_use_id": "tool_1",
                          "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
                      }
                  ],
              },
              {
                  "role": "assistant",
                  "content": [
                      {
                          "type": "text",
                          "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
                      }
                  ],
              },
              {
                  "role": "user",
                  "content": [
                      {
                          "type": "text",
                          "text": "Yes, please tell me about the Perseverance rover specifically.",
                          "cache_control": {"type": "ephemeral"},
                      }
                  ],
              },
          ],
      )
      print(response.usage.model_dump_json())
      ```

      ```typescript TypeScript
      const client = new Anthropic();

      const response = await client.messages.create({
        model: "claude-opus-5-5",
        max_tokens: 1024,
        tools: [
          {
            name: "search_documents",
            description: "Search through the knowledge base",
            input_schema: {
              type: "object",
              properties: {
                query: {
                  type: "string",
                  description: "Search query"
                }
              },
              required: ["query"]
            }
          },
          {
            name: "get_document",
            description: "Retrieve a specific document by ID",
            input_schema: {
              type: "object",
              properties: {
                doc_id: {
                  type: "string",
                  description: "Document ID"
                }
              },
              required: ["doc_id"]
            },
            cache_control: { type: "ephemeral" }
          }
        ],
        system: [
          {
            type: "text",
            text: `You are a helpful research assistant with access to a document knowledge base.

      # Instructions
      - Always search for relevant documents before answering
      - Provide citations for your sources
      - Be objective and accurate in your responses
      - If multiple documents contain relevant information, synthesize them
      - Acknowledge when information is not available in the knowledge base`,
            cache_control: { type: "ephemeral" }
          },
          {
            type: "text",
            text: `# Knowledge Base Context

      Here are the relevant documents for this conversation:

      ## Document 1: Solar System Overview
      The solar system consists of the Sun and all objects that orbit it...

      ## Document 2: Planetary Characteristics
      Each planet has unique features. Mercury is the smallest planet...

      ## Document 3: Mars Exploration
      Mars has been a target of exploration for decades...

      [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" }
              }
            ]
          }
        ]
      });
      console.log(response.usage);
      ```

      ```csharp C#
      AnthropicClient client = new()
      {
          ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
      };

      var parameters = new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Tools =
          [
              new ToolUnion(new Tool()
              {
                  Name = "search_documents",
                  Description = "Search through the knowledge base",
                  InputSchema = new InputSchema()
                  {
                      Properties = new Dictionary<string, JsonElement>
                      {
                          ["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Search query" }),
                      },
                      Required = ["query"],
                  },
              }),
              new ToolUnion(new Tool()
              {
                  Name = "get_document",
                  Description = "Retrieve a specific document by ID",
                  InputSchema = new InputSchema()
                  {
                      Properties = new Dictionary<string, JsonElement>
                      {
                          ["doc_id"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Document ID" }),
                      },
                      Required = ["doc_id"],
                  },
                  CacheControl = new CacheControlEphemeral(),
              }),
          ],
          System = new MessageCreateParamsSystem(new List<TextBlockParam>
          {
              new TextBlockParam()
              {
                  Text = """
                      You are a helpful research assistant with access to a document knowledge base.

                      # Instructions
                      - Always search for relevant documents before answering
                      - Provide citations for your sources
                      - Be objective and accurate in your responses
                      - If multiple documents contain relevant information, synthesize them
                      - Acknowledge when information is not available in the knowledge base
                      """,
                  CacheControl = new CacheControlEphemeral(),
              },
              new TextBlockParam()
              {
                  Text = """
                      # Knowledge Base Context

                      Here are the relevant documents for this conversation:

                      ## Document 1: Solar System Overview
                      The solar system consists of the Sun and all objects that orbit it...

                      ## Document 2: Planetary Characteristics
                      Each planet has unique features. Mercury is the smallest planet...

                      ## Document 3: Mars Exploration
                      Mars has been a target of exploration for decades...

                      [Additional documents...]
                      """,
                  CacheControl = new CacheControlEphemeral(),
              },
          }),
          Messages =
          [
              new UserMessageParam { Content = "Can you search for information about Mars rovers?" },
              new AssistantMessageParam
              {
                  Content = new List<ContentBlockParam>
                  {
                      new ContentBlockParam(new ToolUseBlockParam()
                      {
                          ID = "tool_1",
                          Name = "search_documents",
                          Input = new Dictionary<string, JsonElement>
                          {
                              ["query"] = JsonSerializer.SerializeToElement("Mars rovers"),
                          },
                      }),
                  },
              },
              new UserMessageParam
              {
                  Content = new List<ContentBlockParam>
                  {
                      new ContentBlockParam(new ToolResultBlockParam()
                      {
                          ToolUseID = "tool_1",
                          Content = "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
                      }),
                  },
              },
              new AssistantMessageParam
              {
                  Content = "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
              },
              new UserMessageParam
              {
                  Content = new List<ContentBlockParam>
                  {
                      new ContentBlockParam(new TextBlockParam()
                      {
                          Text = "Yes, please tell me about the Perseverance rover specifically.",
                          CacheControl = new CacheControlEphemeral(),
                      }),
                  },
              },
          ]
      };

      var message = await client.Messages.Create(parameters);
      Console.WriteLine(message.Usage);
      ```

      ```go Go
      	client := anthropic.NewClient()

      	response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
      		Model:     anthropic.ModelClaudeOpus5_5,
      		MaxTokens: 1024,
      		Tools: []anthropic.ToolUnionParam{
      			{OfTool: &anthropic.ToolParam{
      				Name:        "search_documents",
      				Description: anthropic.String("Search through the knowledge base"),
      				InputSchema: anthropic.ToolInputSchemaParam{
      					Properties: map[string]any{
      						"query": map[string]any{
      							"type":        "string",
      							"description": "Search query",
      						},
      					},
      					Required: []string{"query"},
      				},
      			}},
      			{OfTool: &anthropic.ToolParam{
      				Name:        "get_document",
      				Description: anthropic.String("Retrieve a specific document by ID"),
      				InputSchema: anthropic.ToolInputSchemaParam{
      					Properties: map[string]any{
      						"doc_id": map[string]any{
      							"type":        "string",
      							"description": "Document ID",
      						},
      					},
      					Required: []string{"doc_id"},
      				},
      				CacheControl: anthropic.NewCacheControlEphemeralParam(),
      			}},
      		},
      		System: []anthropic.TextBlockParam{
      			{
      				Text: `You are a helpful research assistant with access to a document knowledge base.

      # Instructions
      - Always search for relevant documents before answering
      - Provide citations for your sources
      - Be objective and accurate in your responses
      - If multiple documents contain relevant information, synthesize them
      - Acknowledge when information is not available in the knowledge base`,
      				CacheControl: anthropic.NewCacheControlEphemeralParam(),
      			},
      			{
      				Text: `# Knowledge Base Context

      Here are the relevant documents for this conversation:

      ## Document 1: Solar System Overview
      The solar system consists of the Sun and all objects that orbit it...

      ## Document 2: Planetary Characteristics
      Each planet has unique features. Mercury is the smallest planet...

      ## Document 3: Mars Exploration
      Mars has been a target of exploration for decades...

      [Additional documents...]`,
      				CacheControl: anthropic.NewCacheControlEphemeralParam(),
      			},
      		},
      		Messages: []anthropic.MessageParam{
      			anthropic.NewUserMessage(anthropic.NewTextBlock("Can you search for information about Mars rovers?")),
      			anthropic.NewAssistantMessage(anthropic.NewToolUseBlock(
      				"tool_1",
      				map[string]any{"query": "Mars rovers"},
      				"search_documents",
      			)),
      			anthropic.NewUserMessage(anthropic.NewToolResultBlock(
      				"tool_1",
      				"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
      				false,
      			)),
      			anthropic.NewAssistantMessage(anthropic.NewTextBlock("I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.")),
      			anthropic.NewUserMessage(anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{
      				Text:         "Yes, please tell me about the Perseverance rover specifically.",
      				CacheControl: anthropic.NewCacheControlEphemeralParam(),
      			}}),
      		},
      	})
      	if err != nil {
      		log.Fatal(err)
      	}
      	fmt.Println(response.Usage.RawJSON())
      ```

      ```java Java
      import com.anthropic.models.messages.CacheControlEphemeral;
      // ...
      void main() {
          AnthropicClient client = AnthropicOkHttpClient.fromEnv();

          // Schema da ferramenta de busca
          InputSchema searchSchema = InputSchema.builder()
              .properties(
                  JsonValue.from(
                      Map.of("query", Map.of("type", "string", "description", "Search query"))
                  )
              )
              .putAdditionalProperty("required", JsonValue.from(List.of("query")))
              .build();

          // Schema da ferramenta de obter documento
          InputSchema getDocSchema = InputSchema.builder()
              .properties(
                  JsonValue.from(
                      Map.of("doc_id", Map.of("type", "string", "description", "Document ID"))
                  )
              )
              .putAdditionalProperty("required", JsonValue.from(List.of("doc_id")))
              .build();

          MessageCreateParams params = MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(1024)
              // Ferramentas com cache control na última
              .addTool(
                  Tool.builder()
                      .name("search_documents")
                      .description("Search through the knowledge base")
                      .inputSchema(searchSchema)
                      .build()
              )
              .addTool(
                  Tool.builder()
                      .name("get_document")
                      .description("Retrieve a specific document by ID")
                      .inputSchema(getDocSchema)
                      .cacheControl(CacheControlEphemeral.builder().build())
                      .build()
              )
              // Prompts do sistema com cache control separado em instruções e contexto
              .systemOfTextBlockParams(
                  List.of(
                      TextBlockParam.builder()
                          .text(
                              """
                              You are a helpful research assistant with access to a document knowledge base.

                              # Instructions
                              - Always search for relevant documents before answering
                              - Provide citations for your sources
                              - Be objective and accurate in your responses
                              - If multiple documents contain relevant information, synthesize them
                              - Acknowledge when information is not available in the knowledge base"""
                          )
                          .cacheControl(CacheControlEphemeral.builder().build())
                          .build(),
                      TextBlockParam.builder()
                          .text(
                              """
                              # Knowledge Base Context

                              Here are the relevant documents for this conversation:

                              ## Document 1: Solar System Overview
                              The solar system consists of the Sun and all objects that orbit it...

                              ## Document 2: Planetary Characteristics
                              Each planet has unique features. Mercury is the smallest planet...

                              ## Document 3: Mars Exploration
                              Mars has been a target of exploration for decades...

                              [Additional documents...]"""
                          )
                          .cacheControl(CacheControlEphemeral.builder().build())
                          .build()
                  )
              )
              // Histórico da conversa
              .addUserMessage("Can you search for information about Mars rovers?")
              .addAssistantMessageOfContentBlockParams(
                  List.of(
                      ContentBlockParam.ofToolUse(
                          ToolUseBlockParam.builder()
                              .id("tool_1")
                              .name("search_documents")
                              .input(JsonValue.from(Map.of("query", "Mars rovers")))
                              .build()
                      )
                  )
              )
              .addUserMessageOfContentBlockParams(
                  List.of(
                      ContentBlockParam.ofToolResult(
                          ToolResultBlockParam.builder()
                              .toolUseId("tool_1")
                              .content(
                                  "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
                              )
                              .build()
                      )
                  )
              )
              .addAssistantMessageOfContentBlockParams(
                  List.of(
                      ContentBlockParam.ofText(
                          TextBlockParam.builder()
                              .text(
                                  "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
                              )
                              .build()
                      )
                  )
              )
              .addUserMessageOfContentBlockParams(
                  List.of(
                      ContentBlockParam.ofText(
                          TextBlockParam.builder()
                              .text("Yes, please tell me about the Perseverance rover specifically.")
                              .cacheControl(CacheControlEphemeral.builder().build())
                              .build()
                      )
                  )
              )
              .build();

          Message message = client.messages().create(params);
          IO.println(message.usage());
      }
      ```

      ```php PHP
      $client = new Client();

      $message = $client->messages->create(
          maxTokens: 1024,
          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']
                      ]
                  ]
              ]
          ],
          model: Model::CLAUDE_OPUS_5_5,
          system: [
              [
                  'type' => 'text',
                  'text' => <<<'TEXT'
                      You are a helpful research assistant with access to a document knowledge base.

                      # Instructions
                      - Always search for relevant documents before answering
                      - Provide citations for your sources
                      - Be objective and accurate in your responses
                      - If multiple documents contain relevant information, synthesize them
                      - Acknowledge when information is not available in the knowledge base
                      TEXT,
                  'cache_control' => ['type' => 'ephemeral']
              ],
              [
                  'type' => 'text',
                  'text' => <<<'TEXT'
                      # Knowledge Base Context

                      Here are the relevant documents for this conversation:

                      ## Document 1: Solar System Overview
                      The solar system consists of the Sun and all objects that orbit it...

                      ## Document 2: Planetary Characteristics
                      Each planet has unique features. Mercury is the smallest planet...

                      ## Document 3: Mars Exploration
                      Mars has been a target of exploration for decades...

                      [Additional documents...]
                      TEXT,
                  'cache_control' => ['type' => 'ephemeral']
              ]
          ],
          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']
              ]
          ],
      );

      echo json_encode($message->usage), PHP_EOL;
      ```

      ```ruby Ruby
      client = Anthropic::Client.new

      message = client.messages.create(
        model: Anthropic::Model::CLAUDE_OPUS_5_5,
        max_tokens: 1024,
        tools: [
          {
            name: "search_documents",
            description: "Search through the knowledge base",
            input_schema: {
              type: "object",
              properties: {
                query: {
                  type: "string",
                  description: "Search query"
                }
              },
              required: ["query"]
            }
          },
          {
            name: "get_document",
            description: "Retrieve a specific document by ID",
            input_schema: {
              type: "object",
              properties: {
                doc_id: {
                  type: "string",
                  description: "Document ID"
                }
              },
              required: ["doc_id"]
            },
            cache_control: { type: "ephemeral" }
          }
        ],
        system_: [
          {
            type: "text",
            text: <<~TEXT.chomp,
              You are a helpful research assistant with access to a document knowledge base.

              # Instructions
              - Always search for relevant documents before answering
              - Provide citations for your sources
              - Be objective and accurate in your responses
              - If multiple documents contain relevant information, synthesize them
              - Acknowledge when information is not available in the knowledge base
            TEXT
            cache_control: { type: "ephemeral" }
          },
          {
            type: "text",
            text: <<~TEXT.chomp,
              # Knowledge Base Context

              Here are the relevant documents for this conversation:

              ## Document 1: Solar System Overview
              The solar system consists of the Sun and all objects that orbit it...

              ## Document 2: Planetary Characteristics
              Each planet has unique features. Mercury is the smallest planet...

              ## Document 3: Mars Exploration
              Mars has been a target of exploration for decades...

              [Additional documents...]
            TEXT
            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" }
              }
            ]
          }
        ]
      )
      puts message.usage
      ```
    </CodeGroup>

    Este exemplo abrangente demonstra como usar todos os 4 pontos de interrupção de cache disponíveis para otimizar diferentes partes do seu prompt:

    1. **Cache de ferramentas** (ponto de interrupção de cache 1): O parâmetro `cache_control` na última definição de ferramenta armazena em cache todas as definições de ferramentas.

    2. **Cache de instruções reutilizáveis** (ponto de interrupção de cache 2): As instruções estáticas no prompt do sistema são armazenadas em cache separadamente. Essas instruções raramente mudam entre solicitações.

    3. **Cache de contexto RAG** (ponto de interrupção de cache 3): Os documentos da base de conhecimento são armazenados em cache de forma independente, permitindo que você atualize os documentos RAG sem invalidar o cache de ferramentas ou de instruções.

    4. **Cache do histórico da conversa** (ponto de interrupção de cache 4): A mensagem final do usuário é marcada com `cache_control` para permitir o cache incremental da conversa à medida que ela avança.

    Essa abordagem oferece máxima flexibilidade:

    * Se você acrescentar um novo turno à conversa sem alterar o conteúdo anterior, todos os quatro segmentos de cache são reutilizados.
    * Se você atualizar os documentos RAG, mas mantiver as mesmas ferramentas e instruções, os dois primeiros segmentos de cache são reutilizados.
    * Se você alterar a conversa, mas mantiver as mesmas ferramentas, instruções e documentos, os três primeiros segmentos são reutilizados.
    * Alterações em qualquer ponto de interrupção invalidam aquele segmento e tudo o que vem depois dele, enquanto os segmentos anteriores em cache permanecem válidos.

    Para a primeira solicitação:

    * `input_tokens`: Mínimo (tokens após o ponto de interrupção de cache final, próximo de 0 neste exemplo)
    * `cache_creation_input_tokens`: Tokens em todos os segmentos em cache (ferramentas + instruções + documentos RAG + histórico da conversa)
    * `cache_read_input_tokens`: 0 (nenhum acerto de cache)

    Para solicitações subsequentes com apenas uma nova mensagem do usuário (e o quarto ponto de interrupção movido para essa nova mensagem final, como no exemplo):

    * `input_tokens`: Mínimo (tokens após o ponto de interrupção de cache final, próximo de 0 neste exemplo)
    * `cache_creation_input_tokens`: Tokens na nova mensagem do usuário e no turno anterior do assistente (o novo segmento da conversa sendo armazenado em cache)
    * `cache_read_input_tokens`: Todos os tokens armazenados anteriormente em cache (ferramentas + instruções + documentos RAG + conversa anterior)

    Esse padrão é especialmente poderoso para:

    * Aplicações RAG com grandes contextos de documentos
    * Sistemas de agentes que usam múltiplas ferramentas
    * Conversas de longa duração que precisam manter o contexto
    * Aplicações que precisam otimizar diferentes partes do prompt de forma independente
  </Accordion>
</AccordionGroup>

## Retenção de dados

O cache de prompt (tanto automático quanto explícito) é elegível para ZDR. A Anthropic não armazena o texto bruto dos seus prompts nem das respostas do Claude.

As representações do cache KV (chave-valor) e os hashes criptográficos do conteúdo em cache são mantidos apenas na memória e não são armazenados em repouso. As entradas em cache têm um tempo de vida mínimo de 5 minutos (padrão) ou 1 hora (estendido), após o qual são excluídas prontamente, embora não imediatamente. As entradas de cache são isoladas entre organizações e, na Claude API, na Claude Platform on AWS e no Microsoft Foundry, entre workspaces dentro de uma organização.

***

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Preciso de múltiplos pontos de interrupção de cache ou um no final é suficiente?">
    **Na maioria dos casos, um único ponto de interrupção de cache no final do seu conteúdo estático é suficiente.** As escritas de cache ocorrem apenas no bloco que você marca. Coloque-o no último bloco que permanece idêntico entre as solicitações, e cada solicitação subsequente lê essa mesma entrada. Se um bloco posterior varia a cada solicitação (um timestamp, a mensagem recebida), mantenha o ponto de interrupção antes dele, no último bloco estável.

    Você só precisa de múltiplos pontos de interrupção se:

    * Uma conversa crescente empurra seu ponto de interrupção 20 ou mais blocos além da última escrita de cache, colocando a entrada anterior fora da janela de busca retroativa
    * Você deseja armazenar em cache, de forma independente, seções que são atualizadas em frequências diferentes
    * Você precisa de controle explícito sobre o que é armazenado em cache para otimização de custos

    Exemplo: se você tem instruções do sistema (raramente mudam) e contexto RAG (muda diariamente), pode usar dois pontos de interrupção para armazená-los em cache separadamente.
  </Accordion>

  <Accordion title="Os pontos de interrupção de cache adicionam custo extra?">
    Não, os pontos de interrupção de cache em si são gratuitos. Você paga apenas por:

    * Escrever conteúdo no cache (25 por cento a mais que os tokens de entrada base para TTL de 5 minutos)
    * Ler do cache ([uma fração do preço base do token de entrada](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#pricing))
    * Tokens de entrada regulares para conteúdo não armazenado em cache

    O número de pontos de interrupção não afeta o preço; apenas a quantidade de conteúdo armazenado em cache e lido importa.
  </Accordion>

  <Accordion title="Como calculo o total de tokens de entrada a partir dos campos de uso?">
    A resposta de uso inclui três campos separados de tokens de entrada que, juntos, representam sua entrada total:

    ```text wrap
    total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
    ```

    * `cache_read_input_tokens`: Tokens recuperados do cache (tudo antes dos pontos de interrupção de cache que foi armazenado em cache)
    * `cache_creation_input_tokens`: Novos tokens sendo escritos no cache (nos pontos de interrupção de cache)
    * `input_tokens`: Tokens **após o último ponto de interrupção de cache** que não estão em cache

    **Importante:** `input_tokens` NÃO representa todos os tokens de entrada, apenas a parte após seu último ponto de interrupção de cache. Se você tiver conteúdo em cache, `input_tokens` normalmente é muito menor que sua entrada total.

    **Exemplo:** com um documento de 200 mil tokens em cache e uma pergunta do usuário de 50 tokens:

    * `cache_read_input_tokens`: 200.000
    * `cache_creation_input_tokens`: 0
    * `input_tokens`: 50
    * **Total:** 200.050 tokens

    Essa divisão é fundamental para entender tanto seus custos quanto o uso do “rate limit” (limite de taxa). Consulte [Acompanhando o desempenho do cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#tracking-cache-performance) para mais detalhes.
  </Accordion>

  <Accordion title="Qual é o tempo de vida do cache?">
    O tempo de vida mínimo padrão do cache (TTL) é de 5 minutos. Esse tempo de vida é renovado cada vez que o conteúdo em cache é usado.

    Se você achar que 5 minutos é muito pouco, a Anthropic também oferece um [TTL de cache de 1 hora](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#1-hour-cache-duration).
  </Accordion>

  <Accordion title="Quando começa o tempo de vida do cache?">
    O tempo de vida é medido a partir do início da solicitação que escreve ou lê a entrada de cache, não a partir do fim da sua resposta. O tempo gasto gerando uma resposta conta contra o tempo de vida, portanto a janela para uma solicitação subsequente reutilizar o cache é o tempo de vida menos o tempo de geração.

    Se suas solicitações produzem respostas longas e a próxima solicitação pode não começar antes de o tempo de vida expirar, use o [TTL de cache de 1 hora](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#1-hour-cache-duration).
  </Accordion>

  <Accordion title="Quantos pontos de interrupção de cache posso usar?">
    Você pode definir até 4 pontos de interrupção de cache (usando parâmetros `cache_control`) no seu prompt.
  </Accordion>

  <Accordion title="O cache de prompt está disponível para todos os modelos?">
    O cache de prompt é compatível com todos os [modelos Claude ativos](https://platform.claude.com/docs/pt-BR/models/overview).
  </Accordion>

  <Accordion title="Como o cache de prompt funciona com o pensamento?">
    Alterar os parâmetros de pensamento (trocar de modo ou alterar o orçamento no modo estendido) invalida os prefixos de mensagens em cache e também pode invalidar prompts do sistema e ferramentas em cache, porque a configuração de pensamento é renderizada no prompt. Alterar o valor [`output_config.effort`](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) pode ter o mesmo efeito.

    Para mais detalhes sobre invalidação de cache, consulte [O que invalida o cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#what-invalidates-the-cache).

    Para saber mais sobre o pensamento, incluindo sua interação com o uso de ferramentas e o cache de prompt, consulte [Pensamento e cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-prompt-caching).
  </Accordion>

  <Accordion title="Como habilito o cache de prompt?">
    A maneira mais fácil é adicionar `"cache_control": {"type": "ephemeral"}` no nível superior do corpo da sua solicitação ([cache automático](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#automatic-caching)). Como alternativa, inclua pelo menos um ponto de interrupção `cache_control` em blocos de conteúdo individuais ([pontos de interrupção de cache explícitos](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#explicit-cache-breakpoints)).
  </Accordion>

  <Accordion title="Posso usar o cache de prompt com outros recursos da API?">
    Sim, o cache de prompt pode ser usado junto com outros recursos da API, como uso de ferramentas e capacidades de visão. No entanto, alterar se há imagens em um prompt ou modificar as configurações de uso de ferramentas quebra o cache.

    Para mais detalhes sobre invalidação de cache, consulte [O que invalida o cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#what-invalidates-the-cache).
  </Accordion>

  <Accordion title="Como o cache de prompt afeta os preços?">
    O cache de prompt tem preços próprios: escritas de cache de 5 minutos custam 25 por cento a mais que os tokens de entrada base, escritas de cache de 1 hora custam 2x os tokens de entrada base, e acertos de cache custam [uma fração do preço base do token de entrada](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#pricing), com um multiplicador para cada modelo.
  </Accordion>

  <Accordion title="Posso limpar o cache manualmente?">
    Não há como limpar o cache manualmente. Os prefixos em cache expiram automaticamente após um mínimo de 5 minutos de inatividade.
  </Accordion>

  <Accordion title="Como posso acompanhar a eficácia da minha estratégia de cache?">
    Você pode monitorar o desempenho do cache usando os campos `cache_creation_input_tokens` e `cache_read_input_tokens` na resposta da API.
  </Accordion>

  <Accordion title="O que pode quebrar o cache?">
    Consulte [O que invalida o cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#what-invalidates-the-cache) para mais detalhes sobre invalidação de cache, incluindo uma lista de alterações que exigem a criação de uma nova entrada de cache.
  </Accordion>

  <Accordion title="Como o cache de prompt lida com privacidade e separação de dados?">
    O cache de prompt foi projetado com fortes medidas de privacidade e separação de dados:

    1. As chaves de cache são geradas usando um hash criptográfico dos prompts até o ponto de controle de cache. Isso significa que apenas solicitações com prompts idênticos podem acessar um cache específico.

    2. Na Claude API, na Claude Platform on AWS e no Microsoft Foundry, os caches são isolados por workspace dentro de uma organização. No Claude Models on Google Cloud (Google managed) e no Bedrock, os caches são isolados por organização. Em todos os casos, os caches nunca são compartilhados entre organizações, mesmo para prompts idênticos. Consulte [Armazenamento e compartilhamento de cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#cache-storage-and-sharing) para mais detalhes.

    3. O mecanismo de cache foi projetado para manter a integridade e a privacidade de cada conversa ou contexto único.

    4. É seguro usar `cache_control` em qualquer lugar dos seus prompts. Para que o cache produza leituras, coloque o ponto de interrupção no final de um prefixo estável: colocá-lo em um bloco que muda a cada solicitação (como um timestamp ou a entrada arbitrária do usuário) escreve uma nova entrada a cada vez e nunca gera acertos.

    Essas medidas garantem que o cache de prompt mantenha a privacidade e a segurança dos dados, ao mesmo tempo em que oferece benefícios de desempenho.
  </Accordion>

  <Accordion title="Posso usar o cache de prompt com a Message Batches API?">
    Sim, você pode usar o cache de prompt com suas solicitações da [Message Batches API](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing). No entanto, como as solicitações em lote assíncronas podem ser processadas simultaneamente e em qualquer ordem, os acertos de cache são fornecidos com base no melhor esforço.

    O [cache de 1 hora](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#1-hour-cache-duration) pode ajudar a melhorar seus acertos de cache. A forma mais econômica de usá-lo é a seguinte:

    * Reúna um conjunto de solicitações de mensagens que tenham um prefixo compartilhado.
    * Envie uma solicitação em lote com uma única solicitação que tenha esse prefixo compartilhado e um bloco de cache de 1 hora. Isso escreve o prefixo no cache de 1 hora.
    * Assim que isso for concluído, envie o restante das solicitações. Você precisa monitorar o job para saber quando ele é concluído.

    Isso normalmente é melhor do que usar o cache de 5 minutos, porque é comum que solicitações em lote levem entre 5 minutos e 1 hora para serem concluídas.
  </Accordion>

  <Accordion title="Por que estou vendo o erro `AttributeError: 'Beta' object has no attribute 'prompt_caching'` em Python?">
    Esse erro normalmente aparece quando você atualizou seu SDK ou está usando exemplos de código desatualizados. O cache de prompt está disponível em `client.messages`, sem o prefixo beta. Em vez de:

    <CodeGroup exclude="shell:cURL, shell:CLI, typescript, csharp, go, java, php, ruby">
      ```python Python
      client.beta.prompt_caching.messages.create(**params)
      ```
    </CodeGroup>

    Use:

    <CodeGroup exclude="shell:cURL, shell:CLI, typescript, csharp, go, java, php, ruby">
      ```python Python
      client.messages.create(**params)
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Por que estou vendo ‘TypeError: Cannot read properties of undefined (reading ‘messages’)’?">
    Esse erro normalmente aparece quando você atualizou seu SDK ou está usando exemplos de código desatualizados. O cache de prompt está disponível em `client.messages`, sem o prefixo beta. Em vez de:

    ```typescript TypeScript
    client.beta.promptCaching.messages.create(/* ... */);
    ```

    Use:

    ```typescript
    client.messages.create(/* ... */);
    ```
  </Accordion>
</AccordionGroup>

## Disponibilidade

Cache de prompt está disponível ou em beta, conforme a API, e é elegível para retenção zero de dados e prontidão para HIPAA.

### Suporte da API

#### [Messages API](https://platform.claude.com/docs/pt-BR/build-with-claude/working-with-messages)

* Disponibilidade: Disponível
* Uso: Ative com `cache_control`, no nível superior ou em blocos.

| Status     | Plataformas de nuvem             | Modelos                                                                    |
| ---------- | -------------------------------- | -------------------------------------------------------------------------- |
| Disponível | Todas as plataformas compatíveis | [Todos os modelos](https://platform.claude.com/docs/pt-BR/models/overview) |

#### [Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview)

* Disponibilidade: Sempre ativo
* Uso: As entradas de cache usam um tempo de vida de 5 minutos por padrão, e as leituras e gravações de cache aparecem no uso da sessão.

| Status | Plataformas de nuvem             | Modelos                                                                    |
| ------ | -------------------------------- | -------------------------------------------------------------------------- |
| Beta   | Todas as plataformas compatíveis | [Todos os modelos](https://platform.claude.com/docs/pt-BR/models/overview) |

### Tratamento de dados

[Visão geral do tratamento de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#feature-eligibility)

| Item     | Retenção zero de dados                                                                                                                                                                                                                                                                                         | HIPAA    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Status   | Elegível (exclui [Modelos cobertos](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#model-specific-data-retention-requirements))                                                                                                                                                   | Elegível |
| Detalhes | Seus prompts e as saídas do Claude não são armazenados. As representações do cache KV e os hashes criptográficos são mantidos na memória durante o TTL do cache e excluídos prontamente após a expiração. [Saiba mais](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#data-retention) | —        |

Endpoints aplicáveis:

* `/v1/messages`
