A nova API de prompt-caching do Claude Opus 5 reduz drasticamente as faturas de tokens para aplicativos de chat, permitindo que o modelo pule a releitura de textos inalterados. A primeira requisição paga um prêmio modesto; cada acesso subsequente custa aproximadamente um décimo da taxa base, transformando uma despesa recorrente em uma cobrança única.

Por que os desenvolvedores pagam duas vezes pelas mesmas palavras

A maioria das interfaces conversacionais reconstrói o prompt completo em cada turno: um prompt de sistema de 8.000 tokens, PDFs anexados e todo o histórico de diálogo são enviados juntos ao modelo cada vez que um usuário faz uma pergunta de acompanhamento. O modelo reprocessa cada token, embora a maior parte desse texto nunca mude. Com os preços atuais, essa redundância pode dominar o custo de um bot movimentado.

Como o cache muda os cálculos

A API cria uma entrada de cache para cada "bloco" de tokens até um breakpoint definido. Quando a próxima requisição contém o mesmo bloco no início, o serviço o lê do cache em vez de tokenizá-lo novamente. A divisão de preços reflete o trabalho economizado:

  • Escrita de cache – TTL de 5 minutos: 1,25 × preço base
  • Escrita de cache – TTL de 1 hora: 2 × preço base
  • Leitura de cache (hit): 0,1 × preço base

Na prática, a primeira chamada a um novo bloco custa um pouco mais do que uma requisição normal. Cada chamada posterior que atinge o cache é 90% mais barata, de modo que o gasto líquido cai drasticamente à medida que a conversa se aprofunda.

A "regra de ouro" para estruturar prompts

A eficácia do cache depende de onde você coloca o conteúdo estático versus o dinâmico. Coloque tudo o que permanece igual no início e empurre as partes que mudam constantemente para o final. Uma ordenação confiável é assim:

  1. Tools – definições de quaisquer funções externas que o modelo possa chamar.
  2. System instructions – o comportamento de alto nível que você deseja que o modelo siga.
  3. Documents – contextos longos, como PDFs, bases de conhecimento ou trechos de políticas.
  4. User questions – a consulta em tempo real que varia a cada turno.

Se você modificar qualquer token antes de um breakpoint, a entrada de cache é invalidada e o modelo deve reprocessar tudo o que vem a seguir.

Limites ocultos que você precisa respeitar

  • Tamanho mínimo do bloco – o Opus 5 só faz cache de blocos que contenham pelo menos 512 tokens. Qualquer coisa menor não entra no cache.
  • Bug do timestamp – inserir um timestamp variável dentro de um bloco em cache garante uma falha (miss), porque o texto do bloco nunca corresponderá exatamente.
  • Look-back de 20 blocos – o serviço verifica apenas os últimos 20 blocos em busca de uma correspondência. Sessões longas que avançam rapidamente podem ultrapassar a janela do cache.
  • Requisições paralelas – disparar várias requisições idênticas no mesmo instante resultará em falhas para todas, pois o cache é populado apenas após a conclusão da primeira requisição. "Aqueça" o cache com uma única chamada e, em seguida, envie as demais.

Visualizando a economia em sua resposta de API

Cada resposta reporta três contadores de tokens:

  • cache_read_input_tokens – tokens que vieram de um acerto (hit) no cache.
  • cache_creation_input_tokens – tokens gravados no cache nesta requisição.
  • input_tokens – os novos tokens que não foram colocados em cache.

Some os três números para obter o total de tokens que o modelo considerou para aquele turno. Se ambos os campos de cache forem zero, a requisição não utilizou o cache; verifique o tamanho do seu bloco e o posicionamento do breakpoint.

Resumo: Ao priorizar o contexto imutável no início e deixar que a API de prompt-caching do Claude Opus 5 faça o trabalho pesado, você transforma uma despesa recorrente de tokens em uma cobrança única. O resultado é uma redução drástica de custos para qualquer chatbot que faça referência repetida ao mesmo prompt de sistema ou conjunto de documentos — desde que você respeite o limite mínimo de tokens, evite marcadores mutáveis dentro de blocos em cache e mantenha seu conteúdo elegível para o cache dentro do horizonte de 20 blocos.