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

O custo do cache de prompt depende de a sua segunda requisição ser exatamente igual à primeira, e não do desconto anunciado. Em nossa estimativa para um prompt de sistema de 20.000 tokens no claude-sonnet-5, 1.000 requisições custam cerca de US$ 18,18 sem cache e cerca de US$ 2,00 quando cada requisição após a primeira atinge o cache. O mesmo prompt custa mais do que a linha de base sem cache se o prefixo mudar a cada chamada. Este guia utiliza os preços da TokenLab observados em 03/10/2026 para mostrar onde essa linha se situa, e marca o que não conseguimos confirmar na documentação.

Principais Conclusões

• Nos cinco modelos que verificamos, uma leitura de cache custa de 2% a 10% do preço normal de entrada. Dois dos cinco não listam preço de escrita em cache.
• Onde existe um preço de escrita, ele é igual ao de entrada (deepseek-v4.1-flash) ou 1,25 vezes o de entrada (claude-sonnet-5, claude-sonnet-5-5).
• Pelos nossos cálculos, um hit de cache por escrita compensa o prêmio de escrita de 1,25x. Isso pressupõe que a entrada no cache ainda esteja ativa, e o tempo de vida do cache não está documentado nas evidências que lemos.
• O cache reduz apenas o lado de entrada da fatura. Os tokens de saída são precificados como antes.
• A documentação da API da TokenLab que lemos não nomeia um campo de tokens em cache em usage. Registre o objeto bruto do seu próprio teste e reconcilie-o com o Usage.

Custo de cache de prompt por modelo: preços de leitura, escrita e entrada

Lemos a API de modelo ao vivo para cada modelo abaixo em 03/10/2026. Todos os cinco listam prompt-cache em suas capacidades, e a precificação foi atualizada pela última vez em 02/10/2026T16:53:30.068Z. Os preços estão em USD por 1 milhão de tokens.

Modelo	Entrada	Leitura de cache	Escrita de cache	Leitura como parte da entrada	Escrita vs entrada
claude-sonnet-5	0,90	0,09	1,125	10%	1,25x
claude-sonnet-5-5	0,60	0,06	0,75	10%	1,25x
gpt-5.5	1,50	0,15	nenhum listado	10%	não listado
deepseek-v4.1-flash (fora de pico)	0,15	0,003	0,15	2%	1,0x
deepseek-v4.1-flash (pico)	0,30	0,006	0,30	2%	1,0x
gemini-3.8-flash	0,375	0,0375	nenhum listado	10%	não listado

As duas colunas de porcentagem são nossa própria divisão dos preços listados.

Fontes, todas observadas em 03/10/2026:

• claude-sonnet-5 (página do modelo: /models/claude-5/claude-sonnet-5)
• claude-sonnet-5-5 (página do modelo: /models/claude-5/claude-sonnet-5-5)
• gpt-5.5 (página do modelo: /models/gpt-5-5/gpt-5.5)
• deepseek-v4.1-flash (página do modelo: /models/deepseek-v4/deepseek-v4.1-flash)
• gemini-3.8-flash (página do modelo: /models/gemini-3/gemini-3.8-flash)

Três detalhes são importantes ao ler esta tabela.

Primeiro, gpt-5.5 e gemini-3.8-flash listam um preço de leitura de cache e nenhum preço de escrita de cache. Não podemos dizer a partir desses dados como um prefixo de primeira vez é cobrado nesses dois. A evidência não diz que é gratuito, e não diz que é cobrado à taxa de entrada. Verifique o Usage após uma primeira requisição antes de criar uma previsão baseada em qualquer uma das suposições.

Segundo, quando lemos deepseek-v4.1-flash, encontramos duas entradas de preço. A entrada off-peak (seletor offPeak: true) e a entrada peak (offPeak: false) diferem por um fator de dois em cada linha. Suas economias de cache por token são a mesma porcentagem, mas os dólares absolutos dobram no pico.

Terceiro, estes são preços públicos da TokenLab. O guia de faturamento (observado em 03/10/2026) diz que uma requisição concluída é cobrada uma vez pela opção de entrega que a produziu. Official segue o preço público do fabricante do modelo, portanto, confirme qual opção atendeu sua requisição antes de comparar com uma tabela de preços do fabricante.

A referência Get a Model mostra gpt-5.6-terra com prompt-cache entre suas capacidades. Sua resposta de exemplo não contém preços, então deixamos esse modelo de fora da tabela. Não verificamos os outros modelos no catálogo.

Um exemplo prático de custo de cache de prompt: um longo prompt de sistema

Aqui está o cenário, com cada entrada declarada para que você possa substituir pelos seus próprios números. Estas são nossas suposições, não medições.

• Um prompt de sistema e bloco de ferramentas de 20.000 tokens, idêntico em cada requisição.
• Uma mensagem de usuário de 200 tokens que muda a cada requisição.
• 1.000 requisições, com o cache permanecendo ativo durante toda a execução, portanto, há uma escrita e 999 leituras.
• Tokens de saída ignorados, porque custam o mesmo com ou sem cache.

claude-sonnet-5 a 0,90 de entrada, 0,09 de leitura e 1,125 de escrita por 1 milhão de tokens:

• Sem cache: 1.000 × 20.200 = 20.200.000 tokens × US$ 0,90/1M = US$ 18,18
• Escrita de cache: 20.000 × US$ 1,125/1M = US$ 0,0225
• Leituras de cache: 999 × 20.000 = 19.980.000 × US$ 0,09/1M = US$ 1,7982
• Sufixos sem cache: 1.000 × 200 = 200.000 × US$ 0,90/1M = US$ 0,18
• Com cache: 0,0225 + 1,7982 + 0,18 = cerca de US$ 2,00, aproximadamente 89% abaixo do valor sem cache

Agora o caso de falha, com o prefixo mudando ligeiramente a cada chamada, de modo que cada requisição paga uma escrita e nunca lê. Isso custa 1.000 × 20.000 × US$ 1,125/1M = US$ 22,50 para prefixos, mais os mesmos US$ 0,18 para sufixos. O total é cerca de US$ 22,68, que é US$ 4,50 (25%) acima dos US$ 18,18 sem cache.

O ponto de equilíbrio segue os mesmos preços. Por 1 milhão de tokens de prefixo, uma escrita custa US$ 0,225 a mais do que a entrada simples, e cada leitura economiza US$ 0,81. Um hit compensa a escrita com sobra (0,225 ÷ 0,81 ≈ 0,28 leituras por escrita).

O mesmo cenário nos outros modelos:

Modelo	Sem cache	Com cache (estimativa)	Suposição para a primeira requisição
claude-sonnet-5	US$ 18,18	US$ 2,00	preço de escrita listado
claude-sonnet-5-5	US$ 12,12	US$ 1,33	preço de escrita listado
deepseek-v4.1-flash fora de pico	US$ 3,03	US$ 0,09	preço de escrita listado
deepseek-v4.1-flash pico	US$ 6,06	US$ 0,19	preço de escrita listado
gpt-5.5	US$ 30,30	US$ 3,33	sem preço de escrita listado; cobramos 20.000 tokens à taxa de entrada
gemini-3.8-flash	US$ 7,58	US$ 0,83	sem preço de escrita listado; cobramos 20.000 tokens à taxa de entrada

Para gpt-5.5, o cálculo é 20.000 × US$ 1,50/1M = US$ 0,03, mais 19.980.000 × US$ 0,15/1M = US$ 2,997, mais 200.000 × US$ 1,50/1M = US$ 0,30. As duas linhas sinalizadas baseiam-se em uma suposição que a evidência não suporta, portanto, trate-as como aproximadas.

Tornando um prompt armazenável em cache: o que a documentação confirma

A evidência suporta uma curta lista de requisitos.

1. Escolha um modelo que liste prompt-cache. O array capabilities de Get a Model (observado em 03/10/2026) é a verificação. Um modelo sem isso não lhe dá base para esperar um desconto.
2. Mantenha o conteúdo compartilhado em uma posição estável. No endpoint Messages, system é um campo de nível superior e aceita uma string ou um array de blocos de conteúdo. Em Chat Completions, as instruções de sistema vão em messages. De qualquer forma, o material repetido deve vir primeiro.
3. Envie bytes idênticos até o limite. Esta é a regra de prefixo exato da versão original deste artigo, e corresponde a como os preços da tabela funcionam. Um preço de leitura aplica-se apenas à parte do prompt que correspondeu.

Request A: [ System Prompt + Tool Definitions ] [ User Query A ]
           ▲───────────── CACHED PREFIX ────────▲ ▲── SUFFIX ──▲

Request B: [ System Prompt + Tool Definitions ] [ User Query B ]
           ▲─────────── CACHE HIT (READ) ───────▲ ▲── SUFFIX ──▲

Três hábitos quebram a reutilização com mais frequência:

• Timestamps, IDs de usuário ou IDs de sessão no topo de um prompt de sistema.
• Definições de ferramentas ou chaves JSON reordenadas entre requisições.
• Alterações de indentação ou quebra de linha no texto compartilhado.

Um formato de requisição que a referência Create Message documenta:

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "system": [
    {
      "type": "text",
      "text": "You are a support assistant. The following policy governs all responses: [Full Policy Text]"
    }
  ],
  "messages": [
    { "role": "user", "content": "What is the return period for damaged items?" }
  ]
}

Um rascunho anterior deste artigo colocava um marcador cache_control do tipo ephemeral naquele bloco de sistema. A referência Create Message que lemos em 03/10/2026 não lista esse campo, então o removemos do exemplo. O mesmo vale para o comprimento mínimo do prefixo e o tempo de vida do cache. Não encontramos nenhum valor para nenhum dos dois na documentação da TokenLab que lemos. Antes de confiar em um marcador explícito ou um TTL, teste seu modelo escolhido e compare as contagens de tokens em cache em duas chamadas idênticas.

Lendo preços de cache e confirmando tokens em cache

Não copie a tabela acima para o código. O guia de faturamento diz para ler o preço atual quando sua aplicação precisar dele. Duas rotas documentadas:

curl "https://api.tokenlab.sh/v1/models/claude-sonnet-5"
curl "https://api.tokenlab.sh/v1/pricing?provider=openai&tag=chat"

O primeiro retorna as capacidades, limites e preços de um modelo. Um ID de modelo desconhecido retorna 404 model_not_found. O segundo é um endpoint público que não precisa de chave de API. Sua resposta de exemplo documentada mostra input_per_1m_tokens e output_per_1m_tokens para gpt-4o e nenhum campo de cache. Seu updated_at nesse exemplo é 20/04/2026, que são dados de exemplo, não preços atuais. Para preços de cache, usamos o endpoint por modelo.

Para confirmar que o cache funcionou, os objetos usage documentados são mais finos do que você poderia esperar. Chat Completions lista prompt_tokens, completion_tokens e total_tokens. Messages lista input_tokens e output_tokens. Nenhuma referência nomeia um campo de tokens em cache. O guia de custo de agente de codificação (observado em 03/10/2026) diz para confirmar o uso de tokens em cache na resposta ou no Usage, e registrar tokens de entrada, saída e em cache por tarefa.

Um teste que executaríamos:

1. Envie a mesma requisição de prefixo longo duas vezes, com alguns segundos de intervalo, com apenas a mensagem final do usuário alterada.
2. Registre o objeto usage bruto completo de ambas as respostas, mais billing_transaction_id se presente.
3. Compare a cobrança da segunda requisição no Usage com a aritmética acima. Um hit de cache deve ficar próximo do valor "com cache", não do valor sem cache.
4. Repita com uma primeira linha deliberadamente alterada para ver o custo da perda.

Para Chat Completions via streaming, defina stream_options.include_usage: true para receber o uso nos chunks do stream. Um cabeçalho de faturamento pode estar ausente em streams, então use o Usage para a cobrança final. O guia de solução de problemas também descreve GET /v1/management/api-keys/{keyId}/usage, que filtra por model, startDate e endDate para reconciliação no lado do servidor.

Quando o custo do cache de prompt não compensa

O cache é uma aposta no tráfego repetido. Ele perde nestas situações:

• O prefixo nunca se repete. Um documento único de 20.000 tokens paga qualquer prêmio de escrita e não ganha nada de volta.
• As requisições chegam muito lentamente. Se o intervalo entre requisições correspondentes exceder o tempo de vida do cache, cada chamada é uma nova escrita. Não encontramos esse tempo de vida na evidência, então meça seu próprio intervalo em relação ao que a página do modelo declara.
• O prefixo muda antes do limite. O gasto excessivo de 25% no caso de falha acima vem exatamente desse padrão.
• O prefixo é pequeno. As economias escalam com tokens de prefixo. Algumas centenas de tokens economizam frações de centavo por chamada, e o tamanho mínimo armazenável em cache não está na evidência.
• A saída domina a fatura. O cache reduz apenas a entrada. Se as respostas forem longas, a linha de cache move uma pequena parte do total.
• O modelo não lista preço de cache. O guia de faturamento diz que um traço na coluna de preço da TokenLab significa que não há oferta Verificada, não que é gratuito. Verifique os detalhes de preço de um modelo antes de contar com qualquer desconto.

Padrão de carga de trabalho	Viabilidade de cache	Por que
Loops de ferramentas multi-turn	Alta	Instruções e definições de ferramentas permanecem fixas entre as etapas.
Muitos usuários consultando um documento grande	Alta	Rajadas de tráfego amortizam a escrita rapidamente.
Trabalhos em segundo plano infrequentes	Baixa	Intervalos maiores que o tempo de vida do cache forçam escritas repetidas.
Prompts de sistema variáveis	Baixa	Alterações antes do limite quebram a correspondência.

O cache de prompt também difere da dica "Implementar cache" no guia de faturamento, que significa armazenar respostas para requisições idênticas repetidas em sua própria aplicação. Isso evita a chamada ao modelo inteiramente, mas só ajuda quando toda a requisição se repete. Para sessões longas de agente, o guia de custo de agente de codificação cobre tamanho de contexto, limites de saída e escolha de modelo junto com o cache.

FAQ

Um hit de cache sempre torna uma requisição mais barata?

Apenas para o prefixo correspondente, e apenas se o modelo listar um preço de leitura de cache. Nos modelos que verificamos, uma leitura custa de 2% a 10% da entrada. O sufixo e todos os tokens de saída são cobrados às taxas normais. Uma perda em um modelo com prêmio de escrita pode custar mais do que uma chamada sem cache.

Um preço de escrita de cache ausente é o mesmo que gratuito?

Não. Para gpt-5.5 e gemini-3.8-flash, a API ao vivo listou um preço de leitura de cache e nenhum preço de escrita em 03/10/2026. Execute uma primeira requisição e leia a cobrança no Usage em vez de assumir zero ou a taxa de entrada.

Onde vão os valores por usuário em um prompt armazenável em cache?

Coloque-os após o conteúdo compartilhado, na mensagem do usuário ou em uma entrada messages tardia. Qualquer coisa que varie antes do bloco compartilhado altera o prefixo e força uma nova escrita. Isso inclui timestamps, IDs de sessão e listas de ferramentas reordenadas.

Por que uma requisição repetida não mostraria tokens em cache?

Verificaríamos quatro coisas em ordem. O modelo lista prompt-cache? O prefixo é byte-idêntico entre as chamadas? A segunda chamada chegou dentro do tempo de vida do cache? A contagem em cache está em um campo que seu log descarta? A documentação que lemos não nomeia esse campo, então registre o objeto usage completo.

Compare preços de cache ao vivo antes de se comprometer com um modelo na página de Modelos da TokenLab.