TutoriaisAtualizado em 26 de setembro de 20264 min de leitura

Cache de prompt na API do Claude: pague menos pelo que se repete

Boa parte de um prompt se repete de uma requisição para a outra: o prompt de sistema, as definições de ferramentas, um documento longo, o histórico da conversa. O cache de prompt (prompt caching) guarda essa parte repetida, e nas requisições seguintes ela é lida do cache por uma fração do preço.

Neste guia você vê como ligar o cache com o Claude Opus 5, quanto ele economiza e como conferir se está funcionando.

Como o cache funciona

O cache é por prefixo. A API monta o prompt sempre na mesma ordem: ferramentas, depois o prompt de sistema, depois as mensagens. Você marca um ponto com cache_control, e tudo o que vem antes desse ponto fica guardado.

Na requisição seguinte, se o começo do prompt for idêntico, byte a byte, a API lê essa parte do cache. Se um único caractere mudar no começo, tudo o que vem depois deixa de ser aproveitado.

A regra prática: o que não muda vai no começo, o que muda vai no fim.

Quanto economiza

Os preços do Claude Opus 5, em dólar por milhão de tokens, segundo a página oficial da Anthropic em 26/09/2026:

Com o cache de 5 minutos, a conta já compensa na segunda requisição: gravar e ler uma vez custa 1,35× o preço de entrada, contra 2× sem cache. Da terceira em diante, cada leitura custa só 10%.

Cache automático: o jeito mais simples

Passe cache_control no nível da requisição e a API marca sozinha o último bloco que pode ir para o cache. Em conversas, o ponto de cache anda junto com o histórico:

import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_BASE_URL=https://api.open33.tech

resposta = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    cache_control={"type": "ephemeral"},  # cache automático, 5 minutos
    system="Você é o assistente técnico da empresa. <regras e documentação longas aqui>",
    messages=[{"role": "user", "content": "Como configuro o webhook de pagamento?"}],
)

print(resposta.usage)

É o indicado para chats e agentes, em que cada requisição repete a conversa anterior e acrescenta uma mensagem.

Cache manual: quando o fim do prompt sempre muda

Se toda requisição termina com algo diferente (a pergunta do usuário, dados buscados na hora), o cache automático marcaria justamente essa parte, que nunca se repete. Nesse caso, marque o fim da parte compartilhada:

resposta = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    system=[
        {
            "type": "text",
            "text": MANUAL_DO_PRODUTO,  # texto longo que não muda
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": pergunta_do_cliente}],  # muda sempre, fica fora do cache
)

Cada requisição pode ter até 4 pontos de cache.

5 minutos ou 1 hora?

O cache padrão dura 5 minutos, e cada leitura renova o prazo sem custo extra. Se as requisições que compartilham o prefixo chegam com menos de 5 minutos de intervalo, o cache fica sempre ativo e o padrão é o mais barato.

Se o intervalo costuma ficar entre 5 minutos e 1 hora (um usuário que responde depois de 20 minutos, por exemplo), use o cache de 1 hora:

cache_control={"type": "ephemeral", "ttl": "1h"}

A gravação custa o dobro da entrada normal, então só vale a pena se o mesmo prefixo for lido pelo menos duas vezes dentro da hora.

Como conferir se funcionou

O campo usage da resposta mostra o que aconteceu:

Faça duas requisições iguais em sequência. Na segunda, cache_read_input_tokens deve ser maior que zero. Se continuar zerado, alguma coisa está mudando no começo do prompt.

Atenção: input_tokens mostra só a parte sem cache. O tamanho total do prompt é a soma dos três campos.

O que quebra o cache sem avisar

• Data e hora no prompt de sistema. Um "hoje é 26/09, 14:32" no início muda o prefixo a cada requisição. Coloque informações que mudam no fim, na mensagem do usuário.
• IDs aleatórios (de sessão, de requisição) no começo do prompt.
• JSON com chaves em ordem variável. No Python, use json.dumps(dados, sort_keys=True) em tudo o que vai para o prompt.
• Trocar a lista de ferramentas no meio da conversa. As ferramentas ficam no começo do prompt; mudar uma invalida tudo.
• Trocar de modelo. O cache é separado por modelo.
• Prompt curto demais. No Claude Opus 5, o prefixo precisa ter pelo menos 512 tokens para ir para o cache. Abaixo disso, não dá erro: o cache simplesmente não acontece.