---
title: "Uso e Cobrança do Prompt Caching"
description: "Usando Claude Prompt Caching na 1折AI: como ativar, comprimento mínimo, como confirmar o acerto, como é cobrado após o acerto, e o comportamento de cache do Claude Code."
headingIds: {"Conclusão primeiro":"section-1","Como ativar":"section-2","Comprimento mínimo para cache":"section-3","Como confirmar o acerto":"section-4","Como é cobrado":"section-5","Cache de 1 hora":"section-6","Cache do Claude Code":"section-7","A interface compatível com OpenAI pode usar cache?":"section-8","Perguntas frequentes":"section-9"}
---

<aside className="docs-publication" data-pagefind-ignore>

Documentação mantida por [1ZheAI](https://1zheai.com/en/editorial/#publisher). [Fontes e correções](https://1zheai.com/en/editorial/).

Encontrou um erro? [Contate o suporte](mailto:support@1zheai.com) com o endereço da página e uma descrição. Não envie chaves de API ou credenciais de conta.

</aside>
O Prompt Caching faz com que prefixos longos reenviados (prompt de sistema, definições de ferramentas, documentos longos, histórico de conversa) sejam cobrados apenas na primeira vez como escrita, e depois como leitura. Neste site, a leitura e a escrita de cache são cobradas pelo preço oficial original, sem aplicar o desconto de entrada/saída. Os preços unitários de cache de cada modelo estão em[Modelos e Preços](https://1zheai.com/en/pricing/).

## Conclusão primeiro

- **O Claude Code já vem com o cache ativado por padrão**, basta conectar e funciona.
- Ao chamar por código próprio, adicione `cache_control` no bloco de conteúdo que deseja cachear, usando `/v1/messages` nativo. A interface compatível com OpenAI atualmente não faz cache.
- Para saber se houve acerto, verifique apenas se `usage.cache_read_input_tokens` na resposta é maior que 0.
- O cache dura 5 minutos por padrão, e cada acerto reinicia o cronômetro. Também é possível usar `"ttl": "1h"` para gravar cache de 1 hora, com preço de escrita mais alto.

## Como ativar

Adicione `"cache_control": {"type": "ephemeral"}` no bloco de conteúdo de system, tools ou messages; esse bloco e o conteúdo anterior a ele serão cacheados. Uma requisição aceita no máximo 4 pontos de quebra de cache.

```bash
curl https://1zheai.com/v1/messages \
  -H "x-api-key: $ONEZHE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 256,
    "system": [
      {
        "type": "text",
        "text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}]
  }'
```

<Note>

Quando o prefixo a ser cacheado é muito curto, a requisição é processada normalmente, apenas não é cacheada e não gera erro. O comprimento mínimo varia por modelo, veja a tabela abaixo.

</Note>

## Comprimento mínimo para cache

Os valores abaixo vêm da [documentação oficial da Anthropic](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) (2026-10-14):

| Mínimo de tokens | Modelo |
|---|---|
| 512 | Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5, Haiku 5.5 |
| 1,024 | Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5 |
| 2,048 | Opus 4.7 |
| 4,096 | Opus 4.6, Opus 4.5, Haiku 4.5 |

## Como confirmar o acerto

Envie a mesma requisição duas vezes seguidas (intervalo não superior a 5 minutos) e compare os `usage` das duas. Abaixo estão os resultados medidos em 2026-10-15 com `claude-sonnet-5-5`, com cerca de 18 mil tokens de texto fixo no system:

<CodeGroup>
```json title="第一次：写入缓存"
{
  "input_tokens": 23,
  "cache_creation_input_tokens": 17920,
  "cache_read_input_tokens": 0,
  "cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}
```
```json title="第二次：命中缓存"
{
  "input_tokens": 23,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 17920,
  "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 4
}
```
</CodeGroup>

Se o `cache_read_input_tokens` da segunda vez for maior que 0, o cache está sendo lido. Os tokens de escrita e leitura de cache de cada chamada também aparecem na coluna Token dos[Logs de Chamada](/pt/docs/usage-logs/), com a leitura registrada como "cache↓" e a escrita como "↑".

## Como é cobrado

| Tipo | Preço unitário oficial | Preço unitário na 1折AI |
|---|---|---|
| Escrita de cache (5 minutos) | Preço de entrada × 1.25 | Preço oficial original, sem desconto |
| Escrita de cache (1 hora) | Preço de entrada × 2 | Preço oficial original, sem desconto |
| Leitura de cache | Preço de entrada × 0.1 (Opus 5.5, Sonnet 5.5 = 0.05; Fable 5.1 = 0.025) | Preço oficial original, sem desconto |

O preço oficial da escrita de cache de 5 minutos geralmente é 1.25 vezes o preço oficial de entrada. Neste site a entrada tem desconto e o cache não, portanto não é possível usar o multiplicador oficial para concluir que uma única leitura de cache já compensa; é preciso comparar considerando o desconto do modelo, o custo de escrita e o número de leituras repetidas. Exemplos completos de cálculo em[Preços e Cobrança](/pt/docs/pricing-explained/).

### Cache de 1 hora

Adicione `"ttl": "1h"` em `cache_control`, e o cache será mantido por 1 hora, adequado para prefixos com intervalo superior a 5 minutos, mas ainda usados repetidamente:

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

A escrita é cobrada a 2 vezes o preço oficial de entrada, sem usar o preço de entrada com desconto; a leitura é igual à do cache de 5 minutos. Os tokens de escrita na resposta aparecem em `cache_creation.ephemeral_1h_input_tokens`. A escolha do cache de 1 hora deve considerar o intervalo entre as duas requisições, o custo de escrita e o número de leituras repetidas.

## Cache do Claude Code

O Claude Code aplica automaticamente pontos de quebra de cache no prompt de sistema, definições de ferramentas e histórico de conversa, [a explicação oficial está aqui](https://code.claude.com/docs/zh-CN/prompt-caching). Para melhorar o acerto:

- Trabalhe continuamente em uma sessão, sem longas pausas no meio. O cache expira após 5 minutos sem uso.
- Requisições seguintes na mesma sessão leem o cache. Em teste em 2026-10-15, em uma tarefa do Claude Code com dois turnos, o segundo turno leu 31.440 tokens de cache e escreveu 115 tokens. Ao abrir uma nova sessão, o primeiro turno pode precisar regravar todo o prefixo (cerca de 30 mil tokens medidos), e essa cobrança será mais cara que as seguintes.
- Evite alterar `CLAUDE.md` no meio da sessão, trocar servidores MCP ou mudar de modelo; tudo isso altera o prefixo.
- Não defina `DISABLE_PROMPT_CACHING=1`, essa variável de ambiente desativa o cache de todos os modelos.

## A interface compatível com OpenAI pode usar cache?

Atualmente, não. Em teste em 2026-10-15, colocando cerca de 3.100 tokens de texto fixo na mensagem system de `/v1/chat/completions` e enviando duas vezes seguidas, independentemente de adicionar ou não `cache_control` no bloco de conteúdo, os dois `usage` foram:

```json
{"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171}
```

Sem `prompt_tokens_details.cached_tokens`, a leitura e a escrita de cache nos logs de chamada também foram 0, e tudo foi cobrado pelo preço de entrada. Para cenários que precisam de cache, use `/v1/messages` (Anthropic SDK ou Claude Code).

## Perguntas frequentes

<AccordionGroup>
<Accordion title="Por que só aparece cache_creation e nunca cache_read?">

O cache foi gravado, mas não foi lido na próxima vez. Verifique nesta ordem: as duas requisições ultrapassaram 5 minutos? O conteúdo antes do ponto de quebra é idêntico ao caractere (timestamps e IDs aleatórios no system fazem cada vez ser diferente)? O modelo foi trocado? O prefixo atingiu o comprimento mínimo acima?

</Accordion>
<Accordion title="Dá para ver a taxa de acerto de cache?">

Os tokens de leitura e escrita de cache de cada chamada estão nos logs de chamada, e você pode calcular: leitura de cache ÷ (entrada + escrita de cache + leitura de cache).

</Accordion>
</AccordionGroup>