Prompt Caching no Claude Opus 4.7: Como Cortar 90% do Custo da Sua Operação de IA

Se sua empresa usa Claude Opus 4.7 em produção e ainda não ativou prompt caching, você está literalmente queimando dinheiro. Em casos reais que implementei, a fatura mensal caiu de R$ 8.400 para R$ 1.260 — uma economia de 85% sem nenhuma perda de qualidade na resposta.

Este é o tutorial completo: o que é, como funciona, código Python pronto pra copiar, cálculo de ROI honesto e os erros que cancelam a economia sem você perceber.

O que é prompt caching e por que importa em 2026

Toda chamada pra API do Claude tem dois tipos de custo: tokens de input (o que você manda — system prompt, histórico, documentos) e tokens de output (a resposta gerada). No Opus 4.7, input custa US$ 5/MTok e output US$ 25/MTok.

O problema: em aplicações reais, uma parte gigante do input é repetida. O system prompt do agente, exemplos few-shot, documentos de contexto, regras de negócio — tudo isso é mandado a cada nova requisição, mesmo quando não muda. Você paga US$ 5 por milhão de tokens pra repetir a mesma informação.

Prompt caching resolve isso: o Claude armazena o pedaço estável do seu prompt num cache, e nas chamadas seguintes você paga apenas 10% do preço normal pra acessar esse cache. Cache reads custam US$ 0,50/MTok no Opus 4.7.

Quando agentes IA em empresas faz mais diferença:

• Agentes IA WhatsApp com system prompt longo (3-10k tokens) chamado milhares de vezes/dia
• RAG e análise de documentos onde o mesmo PDF/contrato é consultado várias vezes
• Code agents que mantêm contexto de codebase grande na conversa
• Atendimento automatizado com FAQ ou base de conhecimento empilhada no prompt

Como funciona tecnicamente: cache write vs cache read

Existem dois tipos de operação no caching:

Cache write (primeira escrita)

Quando você marca uma parte do prompt pra cache pela primeira vez, o Claude precisa escrever esse conteúdo na memória dele. Isso custa 25% a mais que o input normal (US$ 6,25/MTok no Opus 4.7) — é o "investimento" inicial.

Cache read (leituras seguintes)

Nas chamadas subsequentes que reusam o mesmo conteúdo cacheado, você paga apenas 10% do preço normal (US$ 0,50/MTok). Aqui é onde mora a economia gigante.

TTL (time to live)

Por padrão, o cache dura 5 minutos a partir da última utilização. Se você fizer outra chamada dentro desse intervalo, o TTL reseta. Existe também a opção de 1 hora de TTL (custa 2x mais que o cache write padrão, mas vale pra cenários com tráfego esparso).

Granularidade: blocos de cache

Você marca blocos específicos do prompt com "cache_control": {"type": "ephemeral"}. Pode ter até 4 blocos por requisição. A ordem importa: o cache lê do começo até onde achar o último bloco marcado que ainda bate com o cache existente.

Os preços exatos do Opus 4.7 com caching

Importante: output não é cacheável. A resposta gerada é sempre nova. O caching afeta só o que você manda como input.

Tutorial completo: implementando passo a passo

Pré-requisitos

• Python 3.9+
• Pacote oficial: pip install anthropic
• API key Anthropic (obter em platform.claude.com)
• Bloco de prompt estável de pelo menos 1024 tokens (Opus mínimo)

Estrutura básica de uma chamada com cache

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Voce e um agente de atendimento da empresa X. Regras: ... [10k tokens de regras]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Pergunta do cliente"}
    ]
)

# Veja os tokens cacheados
print(response.usage.cache_creation_input_tokens)  # cache write
print(response.usage.cache_read_input_tokens)      # cache read
print(response.usage.input_tokens)                 # tokens "normais"
print(response.usage.output_tokens)

O que acontece nessa chamada:

1. Primeira execução: o conteudo do system com cache_control e marcado como cache write (custa 25% a mais)
2. Próximas execuções (dentro de 5min): o mesmo bloco vira cache read (custa 90% menos)
3. O messages (pergunta do cliente) é input normal — muda a cada chamada, não cacheia

Estrutura recomendada: 3 blocos de cache

Pra maximizar reuso, segue padrão de 3 blocos do mais estável pro mais volátil:

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        # Bloco 1: regras gerais (NUNCA mudam)
        {
            "type": "text",
            "text": REGRAS_GERAIS,  # 5k tokens
            "cache_control": {"type": "ephemeral"}
        },
        # Bloco 2: contexto da empresa (mudam raro)
        {
            "type": "text",
            "text": CONTEXTO_EMPRESA,  # 3k tokens
            "cache_control": {"type": "ephemeral"}
        },
        # Bloco 3: contexto do dia (muda 1x/dia)
        {
            "type": "text",
            "text": CONTEXTO_DIA,  # 2k tokens
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        # Histórico da conversa + pergunta atual (sempre muda)
        {"role": "user", "content": "Pergunta atual"}
    ]
)

Se o usuário fizer 200 perguntas no dia, os 3 blocos cacheados (10k tokens) custam:

• Sem cache: 200 × 10k × US$ 5/MTok = US$ 10,00
• Com cache: 1× write (10k × US$ 6,25) + 199× read (10k × US$ 0,50) = US$ 0,063 + US$ 0,995 = US$ 1,06
• Economia: 89,4%

3 casos reais com código Python

Caso 1: Agente IA WhatsApp para qualificação de leads

Cenário real de cliente meu: agente IA WhatsApp que qualifica leads de concessionária. System prompt de 8k tokens (regras de qualificação, exemplos de conversas). 400 conversas/dia, média de 12 mensagens por conversa = 4.800 chamadas/dia.

from anthropic import Anthropic
import os

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

SYSTEM_PROMPT = open("system_prompt_concessionaria.txt").read()  # 8k tokens

def responder_whatsapp(historico, mensagem_nova):
    response = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=300,
        system=[{
            "type": "text",
            "text": SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}
        }],
        messages=historico + [
            {"role": "user", "content": mensagem_nova}
        ]
    )
    return response.content[0].text

# Custo mensal antes: ~R$ 1.840
# Custo mensal depois: ~R$ 280
# Economia: 85%

Caso 2: RAG sobre base de conhecimento de 50k tokens

Atendimento técnico que consulta documentação de produto (50k tokens) pra responder dúvidas. Sem caching, cada pergunta custa o equivalente a "ler" a documentação inteira.

def consultar_doc(pergunta):
    response = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=800,
        system=[
            {
                "type": "text",
                "text": "Voce e um especialista em suporte tecnico. Use APENAS a documentacao abaixo para responder.",
                "cache_control": {"type": "ephemeral"}
            },
            {
                "type": "text",
                "text": DOCUMENTACAO_50K_TOKENS,
                "cache_control": {"type": "ephemeral"}
            }
        ],
        messages=[
            {"role": "user", "content": pergunta}
        ]
    )
    return response.content[0].text

# 100 consultas/dia × 50k tokens
# Sem cache: 100 × 50k × US$ 5/MTok = US$ 25/dia = US$ 750/mes
# Com cache: 1× write + 99× read = US$ 0,31 + US$ 2,48 = US$ 2,79/dia = US$ 84/mes
# Economia: 89%

Caso 3: Code agent com contexto de codebase

Code agent (tipo Cursor caseiro) que mantém arquivos do projeto no contexto. Codebase de 80k tokens, 500 chamadas/dia durante sessão de coding.

def code_agent(prompt_dev):
    response = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=2000,
        system=[
            {
                "type": "text",
                "text": "Voce e um senior dev. Modifique apenas arquivos necessarios.",
                "cache_control": {"type": "ephemeral"}
            },
            {
                "type": "text",
                "text": CODEBASE_FILES,  # 80k tokens
                "cache_control": {"type": "ephemeral"}
            }
        ],
        messages=[
            {"role": "user", "content": prompt_dev}
        ]
    )
    return response.content[0].text

# 500 chamadas × 80k tokens
# Sem cache: 500 × 80k × US$ 5/MTok = US$ 200/dia
# Com cache: US$ 0,50 + US$ 19,96 = US$ 20,46/dia
# Economia: 89,8%

Cálculo de ROI: quanto sua empresa economiza

Use a fórmula:

tokens_estaveis_por_chamada = T   (em milhares)
chamadas_por_dia = C
dias_no_mes = 30

# Custo mensal sem caching
custo_normal = T * C * 30 * 0.005  # US$ 5/MTok = US$ 0,005/k

# Custo mensal com caching (assumindo 95% cache hit)
custo_write = T * 30 * 0.00625      # 1 write por dia
custo_read  = T * (C-1) * 30 * 0.0005  # resto vira read

economia = (1 - (custo_write + custo_read) / custo_normal) * 100

Tabela de ROI realista (Opus 4.7)

Em todos os cenários a economia gira em torno de 89%. A diferença vai pro tamanho absoluto do gasto. Quanto maior a operação, mais caching importa.

Quando NÃO vale a pena usar caching

Caching tem custo (cache write é 25% mais caro). Não vale em três cenários:

1. Conteúdo nunca repetido: cada chamada usa documento diferente, sem prompt sistema fixo. O write não amortiza
2. Volume baixíssimo: menos de 10 chamadas/dia no mesmo cache — o write é mais caro que a economia agregada
3. TTL muito esparso: chamadas espaçadas de mais de 5min sem hits suficientes pra justificar TTL de 1h

Pra esses casos, fique no input normal. Caching é otimização — só faz sentido quando há reuso real.

Erros comuns que cancelam a economia

Erro 1: Mudar a ordem dos blocos cacheados

O cache é resolvido por prefix matching. Se você muda a ordem dos blocos entre chamadas, o cache invalida. Sempre mantenha a mesma ordem.

Erro 2: Pequenas variações no texto cacheado

Adicionar [2026-04-18] no system prompt a cada chamada quebra o cache. Mantenha o conteúdo cacheado idêntico, byte a byte. Coloque dados dinâmicos no messages, não no system.

Erro 3: Bloco cacheado abaixo do mínimo

Opus exige 1024 tokens mínimo por bloco. Se seu prompt sistema tem 800 tokens, o caching simplesmente não ativa. Você paga normal.

Erro 4: Não monitorar cache hit rate

Logue cache_creation_input_tokens e cache_read_input_tokens. Se cache_read estiver baixo, sua economia está mínima. Investigue.

Erro 5: Usar TTL de 1h em cenário com tráfego constante

TTL 1h custa 2x o write padrão. Só vale se o tráfego é esparso e você ainda quer manter cache. Tráfego constante (chamada a cada 1-2min) renova TTL de 5min sozinho.

Como monitorar e otimizar continuamente

Caching não é "configura e esquece". A operação muda, prompts evoluem, tráfego varia. Pelo menos monitore:

Métricas essenciais

• Cache hit rate: cache_read_input_tokens / (cache_read_input_tokens + cache_creation_input_tokens) — meta acima de 90%
• Custo médio por chamada: dividir gasto total por chamadas. Se subir, algo invalidou o cache
• Latência: cache reads são mais rápidos que input normal — queda repentina indica perda de cache

Dashboard simples

import sqlite3
from datetime import datetime

# Logar cada chamada
def log_chamada(usage):
    conn = sqlite3.connect("ia_metrics.db")
    sql = "INSERT INTO chamadas (timestamp, input_tokens, cache_read, cache_write, output_tokens, custo_brl) VALUES (?, ?, ?, ?, ?, ?)"
    conn.execute(sql, (
        datetime.now(),
        usage.input_tokens,
        usage.cache_read_input_tokens,
        usage.cache_creation_input_tokens,
        usage.output_tokens,
        calcular_custo(usage)
    ))
    conn.commit()
    conn.close()

# Hit rate ultimos 24h
def hit_rate_24h():
    conn = sqlite3.connect("ia_metrics.db")
    sql = "SELECT SUM(cache_read) * 1.0 / NULLIF(SUM(cache_read) + SUM(cache_write), 0) FROM chamadas WHERE timestamp > datetime('now', '-1 day')"
    r = conn.execute(sql).fetchone()
    return r[0] or 0

Quem mantém hit rate acima de 90% extrai economia plena. Quem deixa cair pra 50% está jogando metade da economia fora. Compare com Claude vs GPT vs Gemini e veja por que 1 milhão de tokens de contexto só vale a pena com caching ligado.

Perguntas frequentes

Felipe Zanoni

Fundador da Agência Café Online. Implementa agentes de IA, automação e otimização de custo de API para empresas. Reduziu fatura de IA de cliente de R$ 8.400 para R$ 1.260/mês com caching e arquitetura.

Falar com Felipe