Cache de prompts da Claude — tarifas, objeto de uso e por que as taxas de acerto caem atrás de um gateway

O cache de prompts é a maior alavanca individual na fatura de um agente e a que tem maior probabilidade de não estar funcionando silenciosamente. Quando marcado corretamente, o trecho repetido da sua solicitação é cobrado a um décimo da tarifa de entrada. Quando marcado incorretamente — ou encaminhado por algo que reescreve seu prefixo — ele é cobrado acima da tarifa comum, porque você paga para gravar entradas de cache que ninguém lê.

O mecanismo está bem documentado em outros lugares. O que não está documentado em lugar algum é o que muda quando a solicitação passa por um gateway, que é a situação da maioria das pessoas que leem isto. Ambos são apresentados abaixo.

O mecanismo, brevemente

Você marca um prefixo estável — um prompt do sistema, um esquema de ferramenta, um documento — e o provedor armazena sua forma processada. A próxima solicitação cujo prefixo corresponda exatamente o lê de volta em vez de processá-lo novamente.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

Duas propriedades fazem todo o trabalho e causam todos os problemas. A correspondência ocorre em um prefixo, portanto qualquer alteração no início invalida tudo o que vem depois. E uma entrada tem uma vida útil, portanto uma conversa com longos intervalos entre turnos é reconstruída em vez de lida.

Quanto custa

A terceira coluna é a proporção padrão: uma leitura custa um décimo da entrada. A quarta também é padrão — uma gravação de cache custa 1,25× a entrada, o multiplicador que a Anthropic informa para uma entrada de cinco minutos — e, como ambas as proporções se aplicam ao preço de entrada da Kunavo, cada uma mantém o mesmo desconto em relação à tabela da Anthropic que a entrada do modelo. Onde a Kunavo diverge da Anthropic é na entrada de uma hora: a Anthropic lista essa gravação a 2× a entrada, e a Kunavo a cobra à mesma taxa de 1,25×. Isso importa especificamente para cargas de trabalho que são reconstruídas com frequência — agentes de longa duração, conversas lentas, qualquer situação em que o prefixo mude — porque são as cargas em que as gravações, e não as leituras, dominam a linha de cache da fatura.

Ambos os valores são lidos do catálogo no momento da renderização, a mesma fonte que a tabela de preços e a calculadora do Claude leem — não há tarifas digitadas manualmente nesta página.

Lendo o objeto de uso

Não deduza o comportamento do cache pela fatura; cada resposta informa isso diretamente, e as três contagens de tokens são todo o diagnóstico.

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

Por que as taxas de acerto caem atrás de um gateway

Um cache vive no upstream que o criou, e a correspondência do prefixo é exata. Esses dois fatos juntos produzem três modos de falha que nunca ocorrem quando você chama diretamente um único provedor:

O roteamento mudou. Se solicitações consecutivas chegarem a upstreams diferentes, a segunda não encontrará cache — a entrada gravada pela primeira não é visível de onde a segunda foi executada. Isso é invisível nos seus próprios logs e aparece somente como uma contagem de criação de cache que deveria ter sido uma leitura. É a causa mais comum e é por isso que um gateway que redireciona livremente entre upstreams pode ser mais barato por token e mais caro por sessão.

Algo foi injetado antes do seu prefixo. Uma camada que reescreve a mensagem do sistema, normaliza as definições de ferramentas ou reordena campos produz um prefixo diferente, e um prefixo diferente é uma falha de acerto. Nada apresenta erro; a fatura apenas aumenta.

O intervalo excedeu a vida útil da entrada. Um agente que pensa por vários minutos entre os turnos pode reconstruir o cache todas as vezes. Isso é uma propriedade da sua carga de trabalho, não do gateway, mas interage mal com o primeiro caso: uma reconstrução também é uma oportunidade de novo roteamento.

O diagnóstico para os três casos é o mesmo — observe cache_creation_input_tokens durante uma sessão. Um valor constante e alto significa que você está reconstruindo. Um valor alto uma vez e zero depois significa que está funcionando. Na Kunavo, o custo no nível da solicitação e as contagens de tokens armazenados em cache estão na visão de uso, e a referência de cache traz os detalhes no nível do endpoint.

O que fazer a respeito

Mantenha o prefixo armazenado em cache genuinamente estável — coloque tudo o que muda por solicitação depois do bloco marcado, nunca antes dele. Agrupe os turnos de um agente mais próximos quando puder, pois o tempo ocioso é inimigo de uma entrada de curta duração. E meça uma sessão de ponta a ponta, não uma solicitação: o cache é uma propriedade de uma sequência, e uma estimativa por solicitação não consegue percebê-lo. A calculadora de custo de tokens do Claude tem um campo de tokens armazenados em cache exatamente por esse motivo — defina-o como a fração do seu prompt que realmente se repete e o valor mensal deixará de ser fictício.

Perguntas frequentes