Prompt caching: the cost/latency lever most people never flip
Every call to a model that reuses a big system prompt, a pile of tool definitions, or a reference document sends all of it again, from scratch, and pays full price — every single time. Prompt caching lets the model skip re-processing what it has already seen. Here's what it actually does, how to set it up, and the gotchas that silently turn it off.
Every time you send a request to a model, the model has to process — technically, run inference over — the entire input from the first token to the last, even if 90% of that input is identical to the request you sent a minute ago. Prompt caching lets the API store the internal representation of a prefix of your prompt after the first time it's processed, so a later request that starts with that exact same prefix can reuse the stored computation instead of redoing it.
The part that gets cached is a prefix, not an arbitrary chunk — everything from the start of the prompt up to a point you mark. That point is called a cache breakpoint, set explicitly with a cache_control field in the request. Anything before the breakpoint can be reused; anything after it is processed fresh, as normal.
Mental model
Think of it less like a generic web cache and more like a bookmark: "everything up to here, I've already read — start from this page next time." If the next request starts with the exact same text up to that bookmark, the model skips straight to the new part.
2. The problem it exists to solve
The pattern that makes caching worth it shows up constantly in real usage: a long, mostly-static system prompt (role instructions, style guide, few-shot examples), a large set of tool/function definitions for an agent, or a reference document (codebase context, a policy manual, a support KB) that gets attached to every single call in a session. None of that content changes turn to turn — only the user's new message does.
Without caching, every one of those calls reprocesses the entire static block from zero, paying full input-token price and full processing time for content the model has already "read" seconds earlier in the same conversation. In multi-turn agent loops — the exact shape of tools like Claude Code, or any coding/research agent that calls the model dozens of times per task — that repeated cost adds up fast, in both dollars and wait time.
3. How it works: breakpoints, prefixes, TTLs
Caching is opt-in and explicit — you mark where the cacheable prefix ends by attaching cache_control to a content block, and the API takes it from there:
Prefix matching. The API checks whether an earlier request already cached a prefix that exactly matches the start of the new request. Any difference — one added word, one moved sentence — before the breakpoint means no match, and the whole prefix reprocesses normally.
Minimum cacheable size. A cache block needs to be reasonably large to be worth it — the platform documentation sets minimums in the range of roughly 1,024 tokens for smaller/faster models and 2,048 tokens for larger ones. A shorter block than that isn't cached; you pay the small write overhead for nothing.
Time-to-live (TTL). A cached prefix isn't permanent — it expires after a set window, commonly a short default (around 5 minutes) or a longer optional one (around 1 hour) for workloads with slower turn-taking. Every cache hit refreshes the countdown, so an active back-and-forth session keeps its cache alive; a long pause lets it expire.
Multiple breakpoints. A single request can mark more than one breakpoint — for example, one after the system prompt and tool definitions, and another after a large reference document — so different parts of the prompt can be reused independently depending on what changes between calls.
4. The actual numbers: cost and latency
The two effects caching produces are the two things that matter most in production: money and time.
Effect
Typical impact
Input cost on a cache hit
Roughly a 90% discount versus processing that same content fresh — cached tokens are billed at a small fraction of the normal input-token rate.
Latency on a cache hit
Commonly cited reductions of 2x or more for time-to-first-token, since the model skips re-running the heaviest part of the input.
Writing the cache (first call)
Slightly more expensive than a normal, uncached call — you pay a small write premium the first time a given prefix is cached, then reap the discount on every hit after that.
Where the win compounds: the savings aren't per-call, they're per-session. An agent that calls a model 30 times in one task, all sharing the same system prompt and tool definitions, pays the write premium once and the 90%-off rate 29 times — that's the shape of workload prompt caching was built for.
5. What silently breaks the cache
Caching fails quietly — there's no error, the request just falls back to full-price processing — which makes these worth knowing before they cost you money for weeks without anyone noticing:
Anything before the breakpoint that changes. A timestamp embedded in a system prompt, a dynamically inserted user name, or even reordering the same tool definitions invalidates the whole prefix match — the fix is to push anything that varies to after the cache breakpoint, keeping the static part perfectly identical call to call.
Adding or removing a tool mid-session. Tool/function definitions are part of the prefix; changing the toolset available to the model changes the prefix and forces a full recompute.
Switching models. A cached prefix from one model does not carry over to a different model — each model's cache is its own, so a cache built on one model provides zero benefit if a later call in the same workflow switches to another.
Waiting past the TTL. A session that goes idle longer than the cache window (5 minutes on the short default) simply loses the cache and pays the write premium again on the next call — this is expected behavior, not a bug, but it matters for scheduling retries or batch jobs.
6. Where it's worth setting up
Caching pays off specifically when a large, static block of content gets reused across many calls in a short window: coding agents replaying the same system prompt and tool schema dozens of times per task, RAG-style setups that attach the same reference document to every question in a session, chat products with a long, fixed persona/style prompt, and any few-shot prompting setup where the examples themselves are large and never change. It's not worth the setup complexity for one-off calls or prompts that are mostly unique content already — the discount only exists on the part that repeats.
Share:
Newsletter
Learn what AI is creating for you. Don't get lost.
Get notified when a new deep dive or lesson goes up. No spam, just new posts.
Prompt caching: a alavanca de custo/latência que quase ninguém usa
Toda chamada a um modelo que reaproveita um system prompt grande, uma pilha de definições de ferramentas, ou um documento de referência, manda tudo isso de novo, do zero, e paga o preço cheio — toda vez. O prompt caching deixa o modelo pular o reprocessamento do que ele já viu. Aqui está o que ele faz de verdade, como configurar, e as pegadinhas que desligam o cache sem avisar.
Toda vez que você manda uma requisição pra um modelo, ele precisa processar — tecnicamente, rodar inferência sobre — a entrada inteira, do primeiro ao último token, mesmo que 90% dessa entrada seja idêntica à requisição que você mandou um minuto atrás. O prompt caching deixa a API guardar a representação interna de um prefixo do seu prompt depois da primeira vez que ele é processado, pra que uma requisição posterior que comece com esse mesmo prefixo exato reaproveite o cálculo já feito em vez de refazer tudo.
A parte que entra em cache é um prefixo, não um pedaço qualquer — tudo desde o início do prompt até um ponto que você marca. Esse ponto é chamado de cache breakpoint, definido explicitamente com um campo cache_control na requisição. Tudo antes do breakpoint pode ser reaproveitado; tudo depois é processado do zero, normalmente.
Modelo mental
Pense nisso menos como um cache genérico de web e mais como um marcador de página: "tudo até aqui eu já li — na próxima vez, começa dessa página". Se a próxima requisição começar com o mesmo texto exato até esse marcador, o modelo pula direto pra parte nova.
2. O problema que ele resolve
O padrão que torna o caching valioso aparece o tempo todo no uso real: um system prompt longo e majoritariamente estático (instruções de papel, guia de estilo, exemplos few-shot), um conjunto grande de definições de ferramentas/funções pra um agente, ou um documento de referência (contexto de código, um manual de política, uma base de conhecimento de suporte) anexado a toda chamada de uma sessão. Nada disso muda de turno pra turno — só a nova mensagem do usuário muda.
Sem caching, cada uma dessas chamadas reprocessa o bloco estático inteiro do zero, pagando preço cheio de tokens de entrada e tempo de processamento cheio por um conteúdo que o modelo já "leu" segundos antes, na mesma conversa. Em loops de agente com múltiplos turnos — exatamente o formato de ferramentas como o Claude Code, ou qualquer agente de código/pesquisa que chama o modelo dezenas de vezes por tarefa — esse custo repetido soma rápido, tanto em dinheiro quanto em tempo de espera.
3. Como funciona: breakpoints, prefixos, TTLs
O caching é opt-in e explícito — você marca onde o prefixo cacheável termina anexando cache_control a um bloco de conteúdo, e a API cuida do resto:
Casamento de prefixo. A API verifica se uma requisição anterior já colocou em cache um prefixo que bate exatamente com o início da nova requisição. Qualquer diferença — uma palavra a mais, uma frase movida — antes do breakpoint significa que não há correspondência, e o prefixo inteiro é reprocessado normalmente.
Tamanho mínimo cacheável. Um bloco de cache precisa ser razoavelmente grande pra valer a pena — a documentação da plataforma define mínimos na faixa de cerca de 1.024 tokens pra modelos menores/mais rápidos e 2.048 tokens pra modelos maiores. Um bloco menor que isso não entra em cache; você paga o pequeno custo extra de escrita à toa.
Tempo de vida (TTL). Um prefixo em cache não é permanente — ele expira depois de uma janela definida, comumente um padrão curto (cerca de 5 minutos) ou um opcional mais longo (cerca de 1 hora) pra cargas de trabalho com turnos mais espaçados. Todo acerto de cache renova a contagem, então uma sessão ativa de ida e volta mantém o cache vivo; uma pausa longa deixa ele expirar.
Múltiplos breakpoints. Uma única requisição pode marcar mais de um breakpoint — por exemplo, um depois do system prompt e das definições de ferramentas, e outro depois de um documento de referência grande — pra que partes diferentes do prompt possam ser reaproveitadas de forma independente, dependendo do que muda entre as chamadas.
4. Os números de verdade: custo e latência
Os dois efeitos que o caching produz são exatamente as duas coisas que mais importam em produção: dinheiro e tempo.
Efeito
Impacto típico
Custo de entrada num acerto de cache
Cerca de 90% de desconto em relação a processar esse mesmo conteúdo do zero — tokens em cache são cobrados por uma pequena fração da taxa normal de token de entrada.
Latência num acerto de cache
Reduções comumente citadas de 2x ou mais no tempo até o primeiro token, já que o modelo pula a reexecução da parte mais pesada da entrada.
Escrever o cache (primeira chamada)
Um pouco mais cara que uma chamada normal sem cache — você paga um pequeno prêmio de escrita na primeira vez que um prefixo entra em cache, e colhe o desconto em todo acerto depois disso.
Onde o ganho se acumula: a economia não é por chamada, é por sessão. Um agente que chama um modelo 30 vezes numa tarefa, todas compartilhando o mesmo system prompt e definições de ferramentas, paga o prêmio de escrita uma vez e a taxa com 90% de desconto 29 vezes — esse é exatamente o formato de carga de trabalho pro qual o prompt caching foi feito.
5. O que desliga o cache sem avisar
O caching falha silenciosamente — não há erro, a requisição simplesmente volta a ser processada a preço cheio — o que torna estes pontos importantes de saber antes que custem dinheiro por semanas sem ninguém perceber:
Qualquer coisa antes do breakpoint que muda. Um timestamp embutido num system prompt, um nome de usuário inserido dinamicamente, ou até reordenar as mesmas definições de ferramentas invalida o casamento do prefixo inteiro — a correção é empurrar tudo que varia pra depois do breakpoint de cache, mantendo a parte estática perfeitamente idêntica de chamada pra chamada.
Adicionar ou remover uma ferramenta no meio da sessão. Definições de ferramentas/funções fazem parte do prefixo; mudar o conjunto de ferramentas disponível pro modelo muda o prefixo e força um recálculo completo.
Trocar de modelo. Um prefixo em cache de um modelo não vale para um modelo diferente — o cache de cada modelo é próprio, então um cache construído num modelo não dá nenhum benefício se uma chamada posterior no mesmo fluxo trocar para outro.
Esperar além do TTL. Uma sessão que fica ociosa por mais tempo que a janela de cache (5 minutos no padrão curto) simplesmente perde o cache e paga o prêmio de escrita de novo na próxima chamada — isso é comportamento esperado, não um bug, mas importa pra agendar retries ou jobs em lote.
6. Onde vale a pena configurar
O caching compensa especificamente quando um bloco de conteúdo grande e estático é reaproveitado em muitas chamadas numa janela curta de tempo: agentes de código repetindo o mesmo system prompt e schema de ferramentas dezenas de vezes por tarefa, setups estilo RAG que anexam o mesmo documento de referência a toda pergunta de uma sessão, produtos de chat com um prompt de persona/estilo longo e fixo, e qualquer setup de prompting com few-shot onde os exemplos em si são grandes e nunca mudam. Não vale a complexidade de configurar pra chamadas avulsas ou prompts que já são majoritariamente conteúdo único — o desconto só existe na parte que se repete.
Compartilhar:
Newsletter
Saiba o que a IA está criando pra você. Não fique por fora.
Seja avisado quando eu postar uma imersão ou lição nova. Sem spam, só posts novos.