Referência de Opções de TTL de Cache e Preços
Uma referência rápida para as duas janelas de TTL (tempo de vida) de cache que o Claude suporta, quanto cada uma custa em relação a um token de entrada normal e como selecionar uma no bloco cache_control.
Como Usar Esta Referência
- Use esta página para decidir entre o TTL padrão de 5 minutos e o TTL estendido de 1 hora para uma determinada carga de trabalho.
- Trate o comportamento de precificação descrito aqui como qualitativo e relativo - sempre confirme os multiplicadores exatos atuais em platform.claude.com/docs antes de orçar, pois os preços se movem independentemente desta página.
- Emparelhe esta referência com
usage.cache_read_input_tokenseusage.cache_creation_input_tokensem respostas reais para validar suas suposições contra o tráfego real. - Revise sua escolha de TTL sempre que sua cadência de solicitação mudar - uma carga de trabalho que costumava disparar a cada poucos segundos e agora dispara a cada poucos minutos pode precisar de um TTL mais longo para continuar atingindo o cache.
Opções de TTL em Resumo
| TTL | Valor do cache_control | Tempo de vida do cache | Custo de gravação do cache | Melhor ajuste |
|---|---|---|---|---|
| Padrão (5 minutos) | {"type": "ephemeral"} | Atualizado a cada hit; expira 5 minutos após o último acesso | Multiplicador base de gravação de cache sobre um token de entrada normal | Sessões interativas, UIs de chat, rajadas de requisições dentro de alguns minutos umas das outras |
| Estendido (1 hora) | {"type": "ephemeral", "ttl": "1h"} | Atualizado a cada hit; expira 1 hora após o último acesso | Multiplicador de gravação de cache mais alto que o padrão de 5 minutos | Sessões de agente de longa duração, trabalhos em lote distribuídos ao longo de uma hora, cargas de trabalho infrequentes, mas recorrentes |
- Ambos os TTLs são efêmeros: a expiração da entrada do cache é redefinida a cada hit de cache, então um fluxo constante de requisições dentro da janela mantém a entrada viva indefinidamente.
- Uma leitura de cache (
cache_read_input_tokens) é sempre cobrada a uma taxa menor do que um token de entrada normal, independentemente de qual TTL escreveu a entrada. - Uma gravação de cache (
cache_creation_input_tokens) custa mais do que um token de entrada normal em ambos os TTLs - o multiplicador de gravação do TTL de 1 hora é maior que o multiplicador de gravação do TTL de 5 minutos, já que você está pagando por uma garantia de maior duração. - Multiplicadores exatos variam por modelo e mudam com o tempo; esta página evita intencionalmente citar valores fixos em dinheiro.
Configurando o TTL em Python
import anthropic
client = anthropic.Anthropic()
# TTL padrão de 5 minutos - omita "ttl" completamente ou defina-o explicitamente.
system_5m = [
{
"type": "text",
"text": "Você é o assistente de suporte da Acme Corp." * 50,
"cache_control": {"type": "ephemeral"},
}
]
# TTL estendido de 1 hora - chave "ttl" explícita.
system_1h = [
{
"type": "text",
"text": "Você é o assistente de suporte da Acme Corp." * 50,
"cache_control": {"type": "ephemeral", "ttl": "1h"},
}
]
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=200,
system=system_1h,
messages=[{"role": "user", "content": "Qual é a sua janela de reembolso?"}],
)Decidindo Entre os Dois
- Estime sua cadência de requisições. Se requisições consecutivas compartilhando um prefixo estiverem tipicamente a segundos ou alguns minutos de distância, o padrão de 5 minutos geralmente é suficiente e mais barato para gravar.
- Estime a duração da sessão. Se uma única sessão de usuário ou agente puder ter lacunas de 10 minutos ou mais entre chamadas que reutilizam o mesmo prefixo - longas sessões de pesquisa, revisão com intervenção humana, pipelines de lote lentos - o TTL de 1 hora evita comer repetidamente o custo de gravação do cache.
- Pondere o custo de gravação contra a contagem de hits esperada. Um multiplicador de gravação mais alto se paga assim que você obtém leituras de cache suficientes contra essa gravação; um prefixo reutilizado apenas uma ou duas vezes não recupera o custo de gravação de nenhum dos TTLs.
- Use o padrão de 5 minutos, a menos que você tenha um motivo específico. É a gravação mais barata e se adapta à maioria das cargas de trabalho interativas e de rajada; use 1 hora deliberadamente, não por padrão.
- Reavalie após medir, não antes. Instrumente
usage.cache_read_input_tokenseusage.cache_creation_input_tokensem produção e revise a escolha do TTL com base nas taxas de acerto observadas, em vez de um palpite.
Verificando Qual TTL Realmente se Aplicou
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=200,
system=system_1h,
messages=[{"role": "user", "content": "Qual é a sua janela de reembolso?"}],
)
usage = response.usage
print(f"tokens de gravação de cache: {usage.cache_creation_input_tokens}")
print(f"tokens de leitura de cache: {usage.cache_read_input_tokens}")
print(f"tokens de entrada normais: {usage.input_tokens}")- Um
cache_creation_input_tokensnão zero comcache_read_input_tokenszero significa que esta chamada gravou o cache pela primeira vez (ou após expirar). - Um
cache_read_input_tokensnão zero significa que a requisição atingiu uma entrada existente sob qualquer TTL que a escreveu. - A resposta não ecoa diretamente qual TTL foi usado - rastreie isso do seu lado, já que você o definiu na requisição.
FAQs
Quais são as duas opções de TTL para cache de prompt?
Uma janela padrão de 5 minutos e uma janela estendida de 1 hora, ambas definidas através do bloco cache_control em conteúdo cacheadável.
Como seleciono o TTL de 1 hora em vez do padrão?
Adicione "ttl": "1h" dentro do dicionário cache_control: {"type": "ephemeral", "ttl": "1h"}. Omitir ttl usa o padrão de 5 minutos.
O cache expira exatamente 5 minutos (ou 1 hora) depois que eu o gravo pela primeira vez?
Não - ambos os TTLs são efêmeros e são atualizados a cada hit de cache, então o relógio de expiração é redefinido cada vez que a entrada é lida, não apenas quando foi escrita.
Qual TTL é mais barato para gravar?
O padrão de 5 minutos tem um multiplicador de custo de gravação de cache menor do que o TTL estendido de 1 hora. As leituras são cobradas à mesma taxa menor, independentemente de qual TTL escreveu a entrada.
Devo sempre usar o TTL de 1 hora para ter segurança?
Não - use o TTL de 5 minutos por padrão, a menos que você tenha um motivo concreto (lacunas de sessão maiores que alguns minutos) para pagar o custo de gravação mais alto para a janela de 1 hora.
Onde encontro os multiplicadores de preço exatos atuais para gravações e leituras de cache?
Em platform.claude.com/docs. Esta página descreve deliberadamente o comportamento de custo qualitativamente porque os multiplicadores exatos mudam com o tempo e variam por modelo.
Posso misturar TTLs dentro da mesma requisição, por exemplo, 1 hora em ferramentas e 5 minutos no sistema?
O TTL é definido por bloco cache_control, então diferentes pontos de interrupção na mesma requisição podem usar TTLs diferentes se sua carga de trabalho realmente precisar dessa divisão.
Como posso saber qual TTL uma determinada resposta usou?
A resposta não a ecoa diretamente - você já sabe, pois definiu ttl na requisição. Rastreie isso do seu lado junto com os campos de uso, se precisar nos logs.
Uma leitura de cache redefine o relógio do TTL, ou apenas uma gravação de cache?
Uma leitura de cache também atualiza a expiração - é isso que significa "efêmero, atualizado no hit". Um fluxo constante de hits dentro da janela mantém a entrada viva bem além de seu TTL original.
Uma leitura de cache é sempre mais barata que um token de entrada normal?
Sim, as leituras de cache são cobradas a uma taxa menor do que os tokens de entrada normais em ambos os TTLs; a escolha do TTL afeta o custo de gravação, não o desconto de leitura.
Relacionados
- Como o Match de Prefixo do Cache de Prompt Realmente Funciona - o mecanismo que esses TTLs governam.
- Noções Básicas de Cache de Prompt - defina seu primeiro TTL em uma requisição funcional.
- Verificando Hits de Cache com cache_read_input_tokens - confirme qual TTL está realmente valendo a pena.
- ROI de Cache de Prompt - Quando as Gravações de Cache Realmente Valem a Pena - a matemática de custo-benefício em mais detalhes.
Versões da pilha: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial
anthropicpara Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.