💸 Termos e economia
Agora aos números. Três campos de usage contam a história de cada turno,
o TTL decide por quanto tempo o cache fica quente, e quatro custos
relativos explicam por que uma conversa longa sai por ~10% — e quando
o cache já se pagou.
📖 cache_read_input_tokens
Toda resposta da API vem com um bloco de contabilidade chamado usage.
O primeiro campo que importa é cache_read_input_tokens: os tokens
que foram servidos do cache neste turno. Eles custam ~0,1× do preço de input —
é o dinheiro que o cache te economiza.
Novo aqui? "usage" e "token"
- usage — o resuminho de consumo que a API devolve junto da resposta, dizendo quantos tokens entraram e de onde vieram.
- token — o pedacinho de texto que o modelo conta (~uma sílaba/palavra curta). Preço e tamanho são medidos em tokens.
Ilustração: quanto maior essa faixa, mais o cache está trabalhando por você. É o campo que prova que houve hit.
✓ Sinal saudável
- ✓
cache_read_input_tokensalto e crescendo entre turnos - ✓A maior parte do input vindo do cache numa conversa longa
✗ Sinal de problema
- ✗Fica 0 mesmo repetindo o mesmo prefixo — tem algo quebrando o cache
- ✗Some depois de uma ação — algo mudou o prefixo
O que é
O campo de usage que conta os tokens servidos do cache neste turno, cobrados a ~0,1× do preço de input.
Por que aprender
É a prova objetiva de que o cache bateu. Sem olhar esse campo, você só supõe que está economizando.
Conceitos-chave
✍️ cache_creation_input_tokens
O segundo campo é cache_creation_input_tokens: os tokens
gravados no cache neste turno. Gravar tem um leve prêmio — custa ~1,25×
(com TTL de 5 min) ou ~2× (com TTL de 1 h). É o preço que você paga uma vez para poder ler barato depois.
A troca por trás do prêmio
Você paga um pouco mais para gravar (1,25×) e, em troca, cada leitura seguinte custa quase nada (0,1×). É um investimento: um write agora compra muitos reads baratos depois.
- •Write com TTL 5 min ≈ 1,25×
- •Write com TTL 1 h ≈ 2× (gravação mais cara, vida mais longa)
Quando esse campo fica alto
É normal ele aparecer no primeiro turno (grava o prefixo) e sempre que entra um bloco novo (uma skill carregada, por exemplo). Ver write o tempo todo, sem read, porém, é sinal de um cache que grava e nunca lê — provável invalidador (você vê isso na Trilha 2).
O que é
Os tokens gravados no cache neste turno, cobrados a ~1,25× (TTL 5 min) ou ~2× (TTL 1 h).
Por que aprender
Entender que o write é um prêmio pago uma vez evita o susto de ver um número maior que o input cheio — e ensina a esperar o payback.
Conceitos-chave
🧮 input_tokens (o resto)
O terceiro campo é input_tokens: só a parte
não cacheada, cobrada pelo preço cheio (1×). E aqui vem a regra de ouro
da leitura de usage: o total do prompt é a soma
dos três campos — não olhe um isolado.
Ilustração: se você olhar só input_tokens, acha que o turno foi minúsculo. O tamanho verdadeiro é a soma — e é normal que o grosso venha do cache.
A pegadinha do "input pequeno"
Seu agente rodou por horas e input_tokens mostra um número baixinho? Não é bug nem economia mágica: o resto veio do cache. Some os três campos para ver o tamanho real do que foi processado.
"usage": {
"cache_read_input_tokens": 98000, // lido do cache · 0,1×
"cache_creation_input_tokens": 1200, // gravado agora · 1,25×
"input_tokens": 300 // não-cacheado · 1×
}
// total processado no turno = 98000 + 1200 + 300 = 99500 tokensO que é
A fatia do prompt que não veio do cache, cobrada pelo preço cheio (1×). Somada aos outros dois campos, dá o tamanho real do turno.
Por que aprender
Evita a leitura errada mais comum: achar que o prompt foi pequeno olhando um campo só. A verdade está na soma.
Conceitos-chave
⏱️ TTL: 5 min e 1 h
Uma entrada de cache não vive para sempre. O TTL (tempo de vida) é de 5 min por padrão, e ele é renovado a cada uso — ou seja, uma conversa ativa mantém o cache quente sozinha. Existe também a opção de 1 h (write mais caro, ~2×) para tráfego com pausas longas.
Novo aqui? "TTL"
TTL = time to live, o tempo que a entrada continua válida no cache. Passou o TTL sem uso, a entrada expira e a próxima requisição paga a gravação de novo.
O relógio do cache
Você responde dentro de ~5 min
Cada uso reinicia o relógio dos 5 min. Enquanto a conversa está viva, o cache continua quente e você paga read barato.
Você para por mais de ~5 min
O TTL expira, a entrada some do cache, e a próxima mensagem paga um write frio — grava o prefixo de novo.
Tráfego com pausas: TTL de 1 h
Se as pausas passam de 5 min com frequência, o TTL de 1 h mantém o cache vivo por mais tempo — ao custo de um write mais caro (~2×).
O que é
O tempo de vida da entrada no cache: 5 min por padrão (renovado a cada uso) ou 1 h (write ~2×) para pausas longas.
Por que aprender
Explica por que a conversa ativa é barata e por que voltar depois de um tempão custa um write novo.
Conceitos-chave
💸 Custos relativos
Quatro números explicam qualquer conta do curso, todos relativos ao preço de um token de input não-cacheado (1×): read ~0,1×, write 5 min ~1,25×, write 1 h ~2× e não-cacheado 1×. Numa conversa longa, o grosso do input (system + histórico) sai a ~10% do preço.
Ilustração: read é a barrinha minúscula — é aí que mora a economia. Write custa um pouco mais que o cheio, mas você paga uma vez; o cheio, você pagaria a cada turno.
A tabela de custos
| Operação | Custo relativo | Quando |
|---|---|---|
| read | ≈ 0,1× | releitura do cache |
| não-cacheado | 1× | referência (preço cheio) |
| write 5 min | ≈ 1,25× | gravação, TTL curto |
| write 1 h | ≈ 2× | gravação, TTL longo |
O que é
A tabela de preços relativos que rege toda economia do cache: read barato, write com prêmio, cheio como referência.
Por que aprender
Com esses quatro números você estima o custo de qualquer cenário do curso de cabeça, sem depender de tabela de preços absoluta.
Conceitos-chave
⚖️ Break-even
Cachear vale a pena quando você lê o suficiente para o write se pagar. Com TTL 5 min, 2 requisições já compensam (1,25× para gravar + 0,1× para reler = 1,35×, contra 2× pagando cheio duas vezes). Com TTL 1 h (write ~2×), precisa de ~3.
Novo aqui? "break-even"
break-even = o ponto de equilíbrio: quantas leituras você precisa para o custo com cache empatar (e depois superar) o custo sem cache. Antes desse ponto, você só pagou o prêmio do write.
sem cache, 2 turnos: 1× + 1× = 2,00×
com cache, 2 turnos: 1,25× (write) + 0,1× (read) = 1,35×
────────
já no 2º turno o cache sai mais barato → economia
(com TTL 1 h, write ≈ 2×, o empate chega por volta do 3º turno)✓ Vale cachear
- ✓Prefixo estável que vai ser relido em vários turnos
- ✓Conversa ativa: system + histórico se repetem
✗ Não cacheie
- ✗Prefixo que muda a cada request — só paga write, nunca lê
- ✗Chamada única, sem repetição — o write não se paga
O que é
O ponto em que o cache passa a valer: ~2 requisições com TTL 5 min, ~3 com TTL 1 h.
Por que aprender
Ensina a NÃO cachear o que muda todo request (só pagaria write) e a confiar no cache quando há releitura.
Conceitos-chave
Resumo do módulo
Próxima trilha
Trilha 2 — Técnico: o cache dentro de uma conversa que cresce, skills e ferramentas (anexar vs quebrar) e a invalidação a fundo, com exemplos copy-run.