Guia de Custos de Prompt Caching: Cache Hits, Prefixos e Gastos Reais com API

O custo do prompt caching depende de três variáveis: quanto do seu prompt é um prefixo reutilizável, com que frequência esse prefixo se repete dentro da janela ativa do cache e como um determinado provedor precifica as gravações (writes) em cache versus os acertos (hits). Acerte esses três números e o caching pode reduzir significativamente sua conta de tokens de entrada em cargas de trabalho repetitivas; erre-os e você poderá pagar um prêmio de gravação por um cache que nunca é reutilizado.

Este guia separa o que os provedores documentam, o que você pode verificar nas superfícies de API públicas e o que você deve testar antes de comprometer gastos de produção com uma estratégia de caching.

Principais Pontos

• O custo do prompt caching tem dois componentes: um custo de gravação (geralmente cobrado quando uma nova entrada de cache é criada) e um custo de acerto (geralmente cobrado quando uma solicitação reutiliza essa entrada). A documentação da Anthropic descreve essa distinção entre gravação e acerto explicitamente; você deve confirmar os multiplicadores atuais na página de documentação antes de modelar os gastos.
• Os cache hits exigem uma correspondência de prefixo exata ou quase exata até um ponto de interrupção (breakpoint) definido. Reordenar instruções de sistema, definições de ferramentas ou exemplos de few-shot antes desse breakpoint invalida o cache e força uma nova gravação.
• As entradas de cache expiram após um tempo de vida (TTL) definido pelo provedor. Se o seu volume de solicitações para um determinado prefixo for muito esparso para cair dentro dessa janela, você pagará custos de gravação repetidos em vez de acumular economias por acertos.
• A documentação do OpenRouter observa que o comportamento e a precificação do prompt caching variam de acordo com o provedor e o modelo subjacente, portanto, uma estratégia de caching que economiza dinheiro em um backend não é transferida automaticamente para outro. Verifique o suporte por modelo antes de rotear o tráfego com base em economias presumidas.

Pelo que o Prompt Caching Realmente Cobra

O prompt caching permite que um provedor de API armazene a representação processada de um prefixo de prompt para que solicitações subsequentes que compartilham esse prefixo ignorem cálculos redundantes. O modelo de faturamento que decorre disso não é "tokens em cache são gratuitos". É mais próximo de "tokens em cache são mais baratos na reutilização, mas a primeira gravação custa mais do que um token de entrada padrão".

A documentação de prompt caching da Anthropic estabelece essa estrutura diretamente: uma solicitação que cria uma nova entrada de cache é faturada de forma diferente de uma solicitação que atinge uma existente. Os multiplicadores exatos mudam com o tempo e por modelo, portanto, trate qualquer número que você vir em uma postagem de blog, incluindo esta, como algo a ser verificado em relação à documentação atual, em vez de uma constante fixa.

A implicação prática é que o prompt caching é uma aposta na reutilização. Se o seu prompt de sistema, esquema de ferramenta ou bloco de contexto recuperado for enviado uma vez e nunca repetido, o caching adiciona um prêmio de gravação sem economias de acerto compensatórias. Se esse mesmo bloco for enviado centenas de vezes dentro da janela ativa do cache, as economias de acerto podem superar o custo de gravação por uma margem ampla.

Como Funcionam os Cache Hits: Prefixos, Prefixos e Breakpoints

Os cache hits são baseados em prefixo, não baseados em conteúdo em um sentido difuso. A parte armazenada em cache de um prompt deve corresponder à solicitação de entrada token por token até o ponto em que o limite do cache, às vezes chamado de breakpoint, é definido. A documentação da Anthropic descreve isso como um mecanismo explícito onde os desenvolvedores marcam qual parte do prompt é elegível para caching, normalmente as instruções de sistema estáveis, definições de ferramentas e documentos de referência longos que não mudam entre as chamadas.

Isso tem uma consequência de engenharia direta: qualquer coisa que você colocar antes do breakpoint de cache deve ser idêntica byte a byte entre as solicitações, incluindo espaços em branco e ordenação. Um erro comum é intercalar variáveis por solicitação (como um carimbo de data/hora ou um ID de usuário) no prompt do sistema antes do limite do cache. Essa única variável derrota o cache para todo o prefixo, e você paga custos de gravação em cada chamada em vez de acumular acertos.

A correção é direta: mantenha conteúdo genuinamente estático (definições de ferramentas, instruções de estilo da casa, documentos de referência grandes) no prefixo em cache e envie qualquer coisa específica da solicitação para o sufixo não armazenado em cache, normalmente a mensagem do usuário.

O tempo de vida do cache importa tanto quanto o design do prefixo. A documentação da Anthropic descreve uma duração de cache padrão medida em minutos, com uma opção de duração mais longa disponível para cargas de trabalho que precisam dela. Se o seu padrão de tráfego envia um prefixo compartilhado uma vez a cada poucos minutos, um cache de curta duração pode expirar antes que a próxima solicitação chegue, e você acaba pagando custos de gravação repetidamente. Cargas de trabalho de alta frequência (sessões de chat, loops de agentes, pipelines em lote executados em sequência) são candidatos muito melhores do que chamadas esporádicas de baixa frequência.

Modelando Gastos Reais com API: Uma Abordagem Prática

Em vez de afirmar uma porcentagem de economia, modele sua própria carga de trabalho com o seguinte formato. Este exemplo ilustra a estrutura da solicitação conceitualmente; verifique os nomes exatos dos campos e a precificação atual na documentação do provedor antes de implementá-la.

{
  "model": "claude-sonnet-5",
  "system": [
    {
      "type": "text",
      "text": "You are a support agent. Full policy document follows...",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the refund window for order 48213?" }
  ]
}

O marcador cache_control no bloco de sistema sinaliza que este conteúdo é um candidato a caching. A primeira chamada em uma sessão paga o custo de gravação para esse bloco. Cada chamada subsequente dentro da janela ativa do cache que reutiliza o prefixo idêntico paga a taxa de acerto em vez da taxa de entrada total para esses tokens.

Para estimar se vale a pena implementar isso para o seu serviço, reúna quatro números dos seus próprios logs:

1. Tamanho do prefixo: a contagem de tokens do conteúdo estável que você pretende armazenar em cache (prompt do sistema, esquema de ferramenta, documento de referência).
2. Frequência de chamadas dentro da janela TTL: quantas solicitações reutilizam exatamente esse prefixo dentro da duração ativa do cache.
3. Taxas de gravação e acerto: extraídas da documentação atual do provedor, não presumidas de memória.
4. Variabilidade do sufixo: se a parte não armazenada em cache do seu prompt é pequena em relação à parte armazenada em cache, já que as economias aumentam com o quanto do prompt total fica atrás do breakpoint do cache.

Se o seu prefixo for grande, sua frequência de chamadas dentro da janela TTL for alta e seu sufixo for pequeno, o caching provavelmente reduzirá os gastos. Se qualquer uma dessas três condições for fraca, execute uma comparação de custos lado a lado antes de lançar o caching amplamente. O guia da TokenLab sobre como reduzir custos de API de IA percorre um conjunto mais amplo de alavancas além do caching, incluindo seleção de modelos e processamento em lote, em /blog/cut-ai-api-costs-30-percent.

Tabela de Decisão: Quando o Prompt Caching Compensa

Padrão de carga de trabalho	Cache provavelmente ajuda	Notas
Prompt de sistema longo ou esquema de ferramenta reutilizado em muitas chamadas em uma sessão	Sim	Caso clássico; custo de gravação é amortizado em acertos
Grande documento recuperado reutilizado em uma curta rajada de perguntas de acompanhamento	Sim, se as chamadas caírem dentro do TTL	Confirme o TTL com a documentação atual antes de presumir a janela de reutilização
Prompts únicos sem tráfego de repetição	Não	Prêmio de gravação sem acerto para compensá-lo
Prompts de alta variabilidade onde a seção "estável" continua mudando	Não	Qualquer alteração antes do breakpoint invalida o cache
Loops de agentes com definições de ferramentas repetidas em muitos turnos	Sim	Esquemas de ferramentas são candidatos principais para caching
Trabalhos em lote de baixa frequência espaçados além do TTL do cache	Não	O cache expira antes da reutilização; pague o custo de gravação toda vez
Roteamento entre provedores onde apenas alguns backends suportam caching	Verifique por modelo	Não presuma que o suporte a caching é transferido entre provedores

Use esta tabela como uma lista de verificação inicial, não como uma resposta final. Confirme o TTL, a precificação de gravação/acerto e a mecânica do breakpoint na documentação do provedor para o modelo específico que você planeja usar, já que esses detalhes mudam e variam de acordo com a família do modelo.

Diferenças entre Provedores que Você Deve Verificar Antes de se Comprometer

O prompt caching não é implementado de forma idêntica em todos os lugares, e isso importa se você rotear tráfego entre vários provedores ou modelos. A documentação do OpenRouter sobre as melhores práticas de prompt caching observa que o suporte e o comportamento do caching diferem de acordo com o provedor subjacente, o que significa que uma estratégia ajustada para a mecânica de cache de um modelo não se aplica automaticamente quando você muda de modelo ou roteia através de um backend diferente.

Se a sua arquitetura usa roteamento de modelo para controlar custos (por exemplo, enviando tarefas de classificação de rotina para um modelo de custo mais baixo como DeepSeek V4 Flash, GLM-5.2 ou Gemini 3.5 Flash, enquanto reserva Claude Sonnet 5 ou GPT-5.5 para tarefas de raciocínio mais difíceis), você precisa verificar o suporte a caching independentemente para cada modelo nessa tabela de roteamento. Uma estratégia de caching validada em relação à documentação de um modelo não é uma suposição segura para outro. A página de classificações da TokenLab rastreia diferenças de nível de modelo que você pode usar como ponto de referência inicial em /models/rankings, e a análise de benchmark de roteamento em /blog/ai-model-routing-benchmark-cost-per-task aborda como as decisões de roteamento interagem com o custo por tarefa, o que se soma às decisões de caching em vez de substituí-las.

Limitações desta Análise

Este guia descreve a mecânica geral do prompt caching conforme documentado pela Anthropic e referenciado pelo OpenRouter nas datas observadas acima. Ele não inclui multiplicadores exatos de gravação/acerto, durações exatas de TTL ou precificação por modelo, porque esses números mudam e diferem por modelo. Antes de criar um modelo de custo para tráfego de produção, extraia os números atuais diretamente da documentação do provedor vinculada acima, em vez de confiar em qualquer figura fixa citada em conteúdo de terceiros, incluindo este artigo. O comportamento de caching para modelos orientados a raciocínio, prompts multimodais e janelas de contexto muito longas também pode diferir do padrão geral de prefix-caching descrito aqui; verifique a documentação do modelo específico que você planeja usar.

FAQ

O prompt caching sempre reduz os gastos com API? Não. Ele reduz os gastos apenas quando um prefixo estável é reutilizado com frequência suficiente dentro da janela ativa do cache para compensar o custo de gravação. Prompts esporádicos ou altamente variáveis geralmente custam mais com o caching ativado do que sem ele.

O que quebra um cache hit? Qualquer alteração no conteúdo do prompt antes do breakpoint do cache, incluindo espaços em branco, ordem dos tokens ou uma única variável inserida em um prompt de sistema que, de outra forma, seria estático. A correspondência deve ser exata até o breakpoint.

O prompt caching é implementado da mesma maneira em todos os provedores? Não. A Anthropic documenta um mecanismo explícito de cache-control com precificação definida de gravação e acerto. A documentação do OpenRouter observa que o suporte e a precificação do caching variam de acordo com o provedor e o modelo subjacente, portanto, você deve verificar o suporte por modelo em vez de presumir que ele é transferido.

Se você está avaliando se o prompt caching, o roteamento de modelo ou uma combinação de ambos se ajusta ao seu padrão de tráfego, comece com a TokenLab para comparar opções de modelos e estrutura de custos antes de comprometer gastos de produção.