Uso e Cobrança do Prompt Caching

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.

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 emModelos e Preços.

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.

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

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.

Comprimento mínimo para cache

Os valores abaixo vêm da documentação oficial da Anthropic (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:

第一次：写入缓存
第二次：命中缓存

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

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

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 dosLogs de Chamada, 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 emPreços e Cobrança.

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:

1
"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. 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:

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

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?

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