Claude · API · Performance

Prompt caching no Claude: como funciona?

Um sistema que custa 25% a mais pra escrever e 90% a menos pra ler. Vale a pena quando você lê mais do que escreve.

Quando você manda a mesma instrução do sistema, ou o mesmo trecho de documento, várias vezes em chamadas seguidas pra API do Claude, está pagando token de input toda vez. Prompt caching deixa você marcar esses pedaços e o Claude guarda em cache do lado dele. Nas próximas chamadas, em vez de processar tudo de novo, ele lê o cache — muito mais rápido, muito mais barato.

TL;DR Cache write custa 1,25× o preço normal do input. Cache read custa 0,1×. TTL padrão é 5 minutos, renovado a cada hit. Vale a pena se o mesmo prefixo é reutilizado em mais de uma ou duas requisições dentro da janela.

Como funciona

Você marca o ponto onde quer "fechar" um pedaço cacheável no prompt. Tudo antes daquele ponto entra no cache; tudo depois é variável e processa normalmente. A unidade é o cache breakpoint.

Você paga mais caro pra escrever uma vez e mais barato a cada leitura subsequente.

Quando o cache é escrito

Na primeira chamada que inclui o breakpoint. O Claude processa tudo normalmente e armazena os tokens anteriores ao breakpoint. Você é cobrado a 1,25× o preço de input naquele trecho. Se o prefixo for curto demais (abaixo do mínimo do modelo), o cache não é gravado e você paga o preço normal — sem bônus, sem ônus.

Quando o cache é lido

Em qualquer chamada subsequente que comece com exatamente o mesmo prefixo e chegue antes do TTL expirar. O Claude reusa o estado, você paga 0,1× input nesse trecho e a latência despenca.

TTL e renovação

O TTL padrão é de 5 minutos, contado a partir do último hit. Ou seja: enquanto você bate o cache regularmente, ele permanece quente. Se você sumir por mais de 5 minutos, na próxima chamada o Claude reescreve (e você paga write de novo).

Insight Pense no cache como uma aposta: você paga 25% a mais agora apostando que vai reler esse prefixo em breve. Se ler uma vez, empata aos 50% do segundo input (a economia paga o sobrepreço). A partir da terceira leitura você está lucrando bem.

Quanto economiza, na prática

Considere um prefixo de 10.000 tokens (instrução + documentos de contexto) reutilizado N vezes.

Requisições	Sem cache (input)	Com cache (input)	Economia
1	10.000	12.500 (write)	−25%
2	20.000	13.500	+32,5%
5	50.000	16.500	+67%
10	100.000	21.500	+78,5%

Tokens equivalentes de input, ignorando output (que é cobrado normal). O ponto de breakeven é a segunda requisição.

Como marcar no código

Python · anthropic SDK

import anthropic

client = anthropic.Anthropic()

resposta = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": INSTRUCOES_LONGAS + "\n\n" + DOCUMENTOS_DE_REFERENCIA,
            "cache_control": {"type": "ephemeral"},  # ← breakpoint
        },
    ],
    messages=[
        {"role": "user", "content": "Quais conceitos aparecem na seção 3?"}
    ],
)

print(resposta.usage)
# cache_creation_input_tokens: 9842   (primeira chamada)
# cache_read_input_tokens:     0
# input_tokens:                18    (só a pergunta do user)

Da segunda chamada em diante, se o prefixo for idêntico, cache_creation_input_tokens cai pra zero e cache_read_input_tokens sobe pros mesmos 9.842 — agora pagos a 10%.

Pegadinhas

Atenção

Qualquer diferença no prefixo invalida o cache. Um espaço extra, uma vírgula a mais, um campo de metadado dinâmico — e você paga write de novo.

Cuidado com timestamps e IDs. Se você joga "agora são 14:32" no system prompt, o cache nunca bate. Mova essas coisas pro fim ou pro lado variável da mensagem.

O TTL conta do último hit, não da escrita. Em apps com tráfego constante o cache pode viver muito mais que 5 minutos na prática.

Quando vale a pena

Chatbots com instrução longa — system prompt grande, perguntas curtas variando. Caso clássico.
RAG com poucos documentos hot — se o usuário faz 3 perguntas sobre o mesmo PDF em 5 minutos, cacheia o PDF.
Agentes multi-step — ferramentas, exemplos, contexto. Cada loop reutiliza o mesmo prefixo.
Few-shot learning extenso — você tem 50 exemplos no prompt e quer rodar em batch.

Quando não vale:

Chamadas únicas, sem reuso previsível.
Prefixos que mudam toda chamada (mesmo que minimamente).
Tráfego esparso (mais de 5 min entre chamadas) sem TTL estendido.

Esta página é um estudo gerado em conversa com o Claude e pode ser atualizada à medida que eu aprendo mais. Se algo aqui estiver desatualizado em relação à documentação oficial, a documentação ganha.