O cache de prompt pode reduzir a uma fração o custo da entrada repetida, mas Claude, OpenAI e Gemini o executam cada um de um jeito. Veja como se comparam os breakpoints, as durações, as taxas de escrita e os tamanhos mínimos, com um exemplo de custo calculado e os erros que impedem os cache hits.
Toda requisição que você envia a um modelo de linguagem grande começa com o mesmo ritual caro. O prompt de sistema, as definições de ferramentas, a documentação colada e os exemplos few-shot são lidos de novo, token por token, pelo preço cheio, mesmo que nada deles tenha mudado desde a última chamada. O cache de prompt acaba com esse desperdício. O provedor armazena a forma processada do seu prefixo repetido e cobra uma fração do preço normal de entrada quando a próxima requisição o reutiliza. Pense no mise en place de um restaurante: o cozinheiro pica os chalotas uma vez antes do serviço, e cada pedido depois é montado a partir de recipientes já prontos.
Claude, OpenAI e Gemini oferecem todos a ideia, mas discordam em quase todo o resto: quem decide o que entra no cache, por quanto tempo ele fica guardado, quanto custa escrevê-lo e qual deve ser o tamanho mínimo de um prompt para se qualificar. Este artigo coloca os três lado a lado com números da documentação atual, para você escolher uma configuração e evitar os erros que desligam o cache sem avisar.
Quando um modelo lê seu prompt, ele faz trabalho real para cada token antes de escrever a primeira palavra da resposta. Esse trabalho é idêntico sempre que o início do prompt é idêntico. O cache de prompt permite que o provedor guarde o resultado desse trabalho por uma janela curta e o reutilize, de modo que a parte repetida seja processada uma vez e cobrada com desconto depois.
Imagine um fichário de cartões. O provedor arquiva o prefixo processado sob uma impressão digital do seu conteúdo exato. A próxima requisição que gerar a mesma impressão digital puxa a gaveta, em vez de reconstruir o conteúdo do zero.
O cache funciona a partir do primeiro token, para a frente. A parte em cache precisa ser uma correspondência exata e contínua com o início da sua requisição, e a primeira diferença encerra a correspondência. Tudo depois desse ponto é processado e cobrado pela taxa regular.
Essa única regra molda todas as recomendações dos provedores. Coloque no topo o conteúdo que nunca muda e empurre para a base tudo o que muda (a pergunta do usuário, a data atual, trechos recuperados). Uma boa seção de topo costuma conter:
💡 Verificação rápida: se você imprimisse duas requisições e marcasse o que elas têm em comum, a parte marcada precisa ser um bloco sólido que começa exatamente no primeiro caractere. Um parágrafo compartilhado no meio não conta.
Três coisas melhoram quando o prefixo é reutilizado:
Loops de agentes, perguntas e respostas sobre documentos, históricos longos de conversa e classificadores com uma rubrica grande são os que mais se beneficiam. Um prompt que muda a cada vez não ganha nada.
O Claude oferece o controle mais direto dos três. Você decide onde termina o prefixo que pode ser colocado em cache e decide por quanto tempo ele deve durar.
Você marca um bloco de conteúdo com cache_control do tipo ephemeral, e tudo desde o início da requisição até esse bloco, inclusive, vira o prefixo em cache. A ordem é fixa: primeiro as ferramentas, depois o sistema e por fim as mensagens. Você pode configurar até quatro pontos de quebra, e a API retorna um erro 400 se você tentar colocar um quinto em nível de bloco.
Há também um modo automático. Adicione um único campo cache_control no nível superior da requisição, e o sistema aplica o ponto de quebra ao último bloco que pode ser armazenado em cache, movendo-o para a frente conforme a conversa cresce.
{
"model": "claude-opus-5-5",
"cache_control": { "type": "ephemeral" },
"system": "Long, stable instructions go here...",
"messages": [
{ "role": "user", "content": "Today's question" }
]
}
Um detalhe pega sessões longas de agentes. Quando o sistema procura uma entrada anterior correspondente, ele verifica no máximo 20 posições para trás a partir de cada ponto de quebra. Se um turno acrescenta muitos blocos, a entrada anterior pode ficar fora dessa janela, e a solução é um segundo ponto de quebra colocado mais cedo no prompt.
A duração padrão é de 5 minutos, e cada acerto renova o cronômetro sem custo. Se o seu tráfego chega em rajadas lentas, você pode optar por uma hora com "ttl": "1h", a um preço de escrita mais alto.
| Item | Multiplicador | Exemplo Opus 5.5 (por milhão de tokens) |
|---|---|---|
| Entrada base | 1x | US$ 4,00 |
| Escrita em cache de 5 minutos | 1,25x | US$ 5,00 |
| Escrita em cache de 1 hora | 2x | US$ 8,00 |
| Leitura do cache | 0,05x neste modelo | US$ 0,20 |
A maioria dos modelos Claude lê do cache a 0,1x do preço base de entrada. As faixas Opus 5.5 e Sonnet 5.5 leem a 0,05x, e algumas faixas mais novas ficam ainda mais baixas.
O limite depende do modelo, e ele mudou bastante entre as gerações:
💡 Falha silenciosa: um prompt menor que o mínimo é processado sem cache, e nenhum erro é retornado. O único sinal é um campo de cache que permanece em zero.
A história da OpenAI tem dois capítulos. Por muito tempo, o cache foi totalmente automático. Com o GPT-5.6, ele ganhou pontos de quebra e uma taxa de escrita, o que o aproxima bem mais do Claude.
No GPT-5.5 e no GPT-5.5 Pro, o sistema coloca pontos de quebra implícitos a cada intervalo de 2.048 tokens, e a retenção é definida com prompt_cache_retention, limitada a 24h. Modelos anteriores como o GPT 5.4, o GPT 5.1, o GPT 5 e o GPT 4.1 aceitam tanto a retenção in_memory, que normalmente dura cerca de 5 a 10 minutos de inatividade, quanto a opção estendida 24h.
A taxa de entrada em cache depende do modelo, mas não há nenhuma cobrança extra de escrita nessas versões. Isso torna o cache gratuito para testar. O pior cenário é você pagar o preço normal.
O GPT-5.6 e os posteriores mudaram as regras, e a nova configuração está mais próxima da do Claude:
prompt_cache_options.mode definido como implicit, um ponto de quebra cai no fim da mensagem elegível mais recente. Com explicit, você marca cada ponto de quebra por conta própria usando prompt_cache_breakpoint.prompt_cache_options.ttl aceita um único valor, 30m, que também é o padrão.{
"model": "YOUR_GPT_5_6_MODEL",
"prompt_cache_options": { "mode": "explicit" },
"input": [
{
"role": "developer",
"content": [{
"type": "input_text",
"text": "Stable rubric and instructions...",
"prompt_cache_breakpoint": { "mode": "explicit" }
}]
},
{ "role": "user", "content": "The changing part of the request" }
]
}
As três faixas atuais da plataforma são o GPT 5.6 Terra, o GPT 5.6 Luna e o GPT 5.6 Sol. Confira a tabela de preços atualizada de cada faixa antes de fazer o orçamento, porque a OpenAI lista algumas faixas com taxas de leitura em cache mais baixas.
O Google oferece dois mecanismos separados, e eles são cobrados de maneiras diferentes. Um acontece sozinho. O outro é um objeto que você cria e gerencia.
O cache implícito vem ativado por padrão para todos os modelos Gemini 2.5 e mais novos. Você não muda nenhum código. Se uma requisição compartilha um prefixo comum com uma anterior, ela é elegível a um acerto, e a economia é repassada automaticamente.
Os mínimos são 2.048 tokens para o Gemini 2.5 Flash e o 2.5 Pro, e 4.096 tokens para o Gemini 3.5 Flash, seus irmãos Flash mais novos e o Gemini 3.1 Pro. As próprias dicas do Google seguem exatamente a regra do prefixo: coloque o conteúdo grande e comum no início e envie as requisições com prefixo parecido próximas no tempo.
Não há garantia para nenhuma requisição específica, porém. O cache implícito é oportunista, e é por isso que algumas equipes migram para a versão explícita.
Com o cache explícito, você cria um objeto de cache e depois aponta as requisições para ele.
cache = client.caches.create(
model="gemini-2.5-flash",
config=types.CreateCachedContentConfig(
system_instruction="Long, stable instructions...",
contents=[big_document],
ttl="3600s",
),
)
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Today's question",
config=types.GenerateContentConfig(cached_content=cache.name),
)
A duração padrão é de uma hora, e você pode definir a sua com ttl, por exemplo "300s". Depois você pode mudar o ttl ou o expire_time, e nada mais do cache. A cobrança tem três partes: tokens reutilizados a uma taxa reduzida, armazenamento por token-hora enquanto o cache existir, e o preço normal de tudo que fica fora do cache. Os caches explícitos têm um mínimo de 2.048 tokens nos modelos 2.5 e de 4.096 na linha 3.x. A API Interactions só oferece o tipo implícito.
O Google publicou descontos de reutilização entre 75% e 90%, dependendo da geração do modelo, então confirme o número do seu modelo na página de preços atualizada.
| Recurso | Claude | OpenAI (GPT-5.6 e posteriores) | Gemini |
|---|---|---|---|
| Como você ativa | cache_control pontos de quebra, ou um campo único no nível superior para o modo automático | Implícito por padrão, ou pontos de quebra explícitos | Implícito por padrão, mais objetos de cache explícitos |
| Duração | 5 minutos, ou 1 hora sob pedido | 30 minutos | O implícito não é garantido. O explícito tem padrão de 1 hora |
| Custo de escrita | 1,25x por 5 minutos, 2x por 1 hora | 1,25x | Preço normal de entrada no implícito. Armazenamento por token-hora no explícito |
| Custo de leitura | 0,1x na maioria dos modelos, 0,05x no Opus 5.5 e no Sonnet 5.5 | 0,1x | Taxa reduzida, definida por modelo |
| Prefixo mínimo | 512 a 4.096 tokens, conforme o modelo | 1.024 tokens visíveis | 2.048 no 2.5, 4.096 nos modelos mais novos |
| Controle | Até 4 pontos de quebra | Modo implícito ou explícito | Objeto de cache com um TTL que você define |
Use os números do Claude para verificar o ponto de equilíbrio. Uma única escrita de 5 minutos a 1,25x mais uma leitura a 0,1x custa 1,35x. Duas chamadas sem cache custam 2x. Ou seja, um único reuso já paga a escrita. A opção de 1 hora escreve a 2x, então você precisa de duas leituras antes de ela ficar mais barata que não usar cache.
Agora amplie a conta. Considere um prompt de sistema de 20.000 tokens enviado 1.000 vezes por dia, à taxa base do Opus 5.5 de US$ 4 por milhão de tokens:
As mensagens do usuário e a saída do modelo são cobradas da mesma forma nos dois casos, então isso isola a economia no prefixo. Nos modelos mais antigos da OpenAI, sem taxa de escrita, a conta é ainda mais simples. No Gemini, a rota explícita soma horas de armazenamento à conta, então um cache que fica ocioso na maior parte do dia pode custar mais do que economiza.
A maioria das configurações de cache que falham não são problemas do provedor. Elas vêm de três hábitos.
O erro clássico é uma linha como "Hora atual: 14:32:07" perto do topo do prompt de sistema. O prefixo muda a cada requisição, então nunca pode coincidir. A Anthropic documenta a mesma armadilha com um ponto de quebra colocado em um bloco que contém um carimbo de tempo e uma mensagem do usuário: o cache nunca acerta, porque nenhuma entrada foi escrita em nenhuma posição anterior. A correção é mover o ponto de quebra para o último bloco que permanece idêntico entre as requisições e colocar a linha que muda depois dele.
A ordem faz parte da impressão digital. Embaralhar definições de ferramentas, ordenar uma lista de documentos recuperados de forma diferente ou serializar JSON com uma nova ordem de campos produzem um prefixo novo. No Claude, uma mudança em um nível invalida esse nível e tudo que vem depois: se você editar uma definição de ferramenta, os caches de ferramentas, sistema e mensagens vão todos embora. Adicionar ou remover imagens invalida o cache de mensagens. Mantenha as listas de ferramentas em uma ordem fixa e serialize-as sempre do mesmo jeito.
Uma duração de 5 minutos não ajuda um trabalho que envia uma requisição a cada dez minutos. Cada chamada paga o preço de escrita e nunca vê uma leitura. Nesse caso, você tem três opções: passar para a duração de 1 hora no Claude, enviar uma requisição barata de keep-alive antes que o cronômetro acabe, ou agrupar o trabalho para que as requisições cheguem próximas umas das outras.
💡 Regra prática: ajuste a duração do cache ao intervalo entre as requisições, não ao tamanho da sessão.
Não confie em uma configuração até que a resposta diga que funcionou. Todo provedor informa a atividade do cache no bloco de uso da resposta.
| Provedor | Onde olhar |
|---|---|
| Claude | usage.cache_creation_input_tokens e usage.cache_read_input_tokens |
| OpenAI | usage.input_tokens_details.cached_tokens e, no GPT-5.6 e posteriores, cache_write_tokens |
| Gemini | A contagem de tokens em cache em usage_metadata |
No Claude, o campo input_tokens conta apenas os tokens depois do último ponto de quebra, e não o prompt inteiro. O total real é cache_read_input_tokens + cache_creation_input_tokens + input_tokens, então calcule sua taxa de acerto a partir dessa soma.
Registre três números por requisição: tokens em cache lidos, tokens escritos e tokens cobrados integralmente. Depois observe dois sinais. Uma contagem de leituras que continua em zero após a segunda requisição idêntica significa que o prefixo está mudando ou abaixo do mínimo. Uma contagem de escritas que sobe em toda requisição significa que a duração expira antes da próxima chamada chegar.
As configurações de cache ficam na API de cada provedor, então o lugar para ajustá-las é o seu código. O Picasso IA é útil um passo antes, quando você está decidindo o que o prefixo estável deve dizer:
Um prompt congelado também é estável, que é exatamente o que um cache quer.
As fotografias deste artigo foram todas feitas com o P Image, cada uma a partir de um único prompt descritivo sobre lente, luz e textura. Você pode fazer o mesmo em poucos minutos. Experimente o Seedream 4.5 para detalhes nítidos em 4K, o Flux 2 Pro para realismo fotográfico, o Imagen 4 para cenas naturais ou o Nano Banana Pro para resultados mais refinados.
Escreva um prompt que nomeie o assunto, a luz e a lente, rode-o, depois mude um detalhe e rode de novo. A forma mais rápida de pegar o jeito de um modelo é começar a testar com suas próprias imagens no Picasso IA hoje.
Escolha seu idioma
