💸 Términos y ahorro
Ahora, los números. Tres campos de usage cuentan la historia de cada turno,
el TTL decide cuánto tiempo permanece activa la caché, y cuatro costos
relativos explican por qué una conversación larga sale por ~10% — y cuándo
la caché ya se amortizó.
📖 cache_read_input_tokens
Toda respuesta de la API viene con un bloque de contabilidad llamado usage.
El primer campo que importa es cache_read_input_tokens: los tokens
que fueron servidos desde la caché en este turno. Cuestan ~0,1× del precio de input —
es el dinero que te ahorra el caché.
¿Nuevo por aquí? «usage» y «token»
- usage — el resumen breve del consumo que la API devuelve junto con la respuesta e indica cuántos tokens entraron y de dónde vinieron.
- token — el fragmento de texto que cuenta el modelo (~una sílaba o palabra corta). El precio y el tamaño se miden en tokens.
Ilustración: cuanto mayor sea esta franja, más trabaja la caché por ti. Es el campo que prueba que hubo un hit.
✓ Señal saludable
- ✓
cache_read_input_tokensalto y creciendo entre turnos - ✓La mayor parte del input de una conversación larga viene del caché
✗ Señal de problema
- ✗Queda 0 aunque repitas el mismo prefijo, algo está rompiendo la caché
- ✗Desaparece después de una acción: algo cambió el prefijo
Qué es
El campo de usage que cuenta los tokens servidos desde la caché en este turno, cobrados a ~0,1× del precio de entrada.
Por qué aprenderlo
Es la prueba objetiva de que la caché funcionó. Si no revisas este campo, solo supones que estás ahorrando.
Conceptos clave
✍️ cache_creation_input_tokens
El segundo campo es cache_creation_input_tokens: los tokens
guardados en el caché en este turno. Escribir tiene una ligera prima — cuesta ~1,25×
(con TTL de 5 min) o ~2× (con TTL de 1 h). Es el precio que pagas una vez para poder leer barato después.
El intercambio que hay detrás del recargo
Pagas un poco más al escribir (1,25×) y, a cambio, cada lectura siguiente cuesta casi nada (0,1×). Es una inversión: una escritura ahora compra muchas lecturas baratas después.
- •Write con TTL 5 min ≈ 1,25×
- •Write con TTL 1 h ≈ 2× (escritura más cara, vida útil más larga)
Cuando este campo está alto
Es normal que aparezca en el primer turno (guarda el prefijo) y cada vez que se incorpora un bloque nuevo (una skill cargada, por ejemplo). Ver write todo el tiempo, sin read, sin embargo, es señal de un caché que escribe y nunca lee: probablemente hay un invalidador (lo verás en la Trilha 2).
Qué es
Los tokens guardados en la caché en este turno, cobrados a ~1,25× (TTL 5 min) o ~2× (TTL 1 h).
Por qué aprenderlo
Entender que el write es una prima que se paga una sola vez evita el susto de ver un número mayor que el input completo y te enseña a esperar el retorno.
Conceptos clave
🧮 input_tokens (el resto)
El tercer campo es input_tokens: solo la parte
no cacheada, cobrada al precio completo (1×). Y aquí viene la regla de oro
de la lectura de usage: el total del prompt es la suma
de los tres campos — no mires uno aislado.
Ilustración: si solo miras input_tokens, cree que el turno fue minúsculo. El tamaño real es la suma, y es normal que la mayor parte venga de la caché.
La trampa del «input pequeño»
Tu agente estuvo ejecutándose durante horas y input_tokens ¿muestra un número bajo? No es un bug ni un ahorro mágico: el resto vino de la caché. Suma los tres campos para ver el tamaño real de lo que se procesó.
"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 tokensQué es
La parte del prompt que no vino del caché, cobrada al precio completo (1×). Sumada a los otros dos campos, da el tamaño real del turno.
Por qué aprenderlo
Evita el error más común al leer: pensar que el prompt fue pequeño mirando un solo campo. La verdad está en la suma.
Conceptos clave
⏱️ TTL: 5 min y 1 h
Una entrada de cache no vive para siempre. El TTL (tiempo de vida) es de 5 min por defecto, y es renovado en cada uso — es decir, una conversación activa mantiene la caché caliente por sí sola. También existe la opción de 1 h (escritura más cara, ~2×) para tráfico con pausas largas.
¿Nuevo por aquí? «TTL»
TTL = tiempo de vida, el tiempo que la entrada sigue siendo válida en el caché. Si pasa el TTL sin uso, la entrada vence y la siguiente solicitud vuelve a pagar la escritura.
El reloj de la caché
Respondes dentro de ~5 min
Cada uso reinicia el temporizador de 5 min. Mientras la conversación sigue activa, la caché permanece caliente y pagas una lectura más barata.
Te detienes por más de ~5 min
El TTL expira, la entrada desaparece de la caché y el siguiente mensaje paga un write frío — vuelve a escribir el prefijo.
Tráfico con pausas: TTL de 1 h
Si las pausas superan los 5 min con frecuencia, el TTL de 1 h mantiene el caché activo por más tiempo, a cambio de un write más caro (~2×).
Qué es
El tiempo de vida de la entrada en la caché: 5 min por defecto (se renueva con cada uso) o 1 h (write ~2×) para pausas largas.
Por qué aprenderlo
Explica por qué la conversación activa es barata y por qué volver después de mucho tiempo cuesta una nueva escritura.
Conceptos clave
💸 Costos relativos
Cuatro números explican cualquier cálculo del curso, todos relativos al precio de un token de input sin caché (1×): lectura ~0,1×, write 5 min ~1,25×, write 1 h ~2× e sin caché 1×. En una conversación larga, la mayor parte del input (system + historial) cuesta ~10% del precio.
Ilustración: La lectura es la barrita diminuta: ahí está el ahorro. Escribir cuesta un poco más que el precio completo, pero lo pagas una vez; el precio completo lo pagarías en cada turno.
La tabla de costos
| Operación | Costo relativo | Cuándo |
|---|---|---|
| read | ≈ 0,1× | relectura de la caché |
| sin caché | 1× | referencia (precio completo) |
| write 5 min | ≈ 1,25× | guardado, TTL corto |
| write 1 h | ≈ 2× | guardado, TTL largo |
Qué es
La tabla de precios relativos que rige todo el ahorro del caché: lectura barata, escritura con recargo y precio completo como referencia.
Por qué aprenderlo
Con estos cuatro números puedes estimar mentalmente el costo de cualquier escenario del curso, sin depender de una tabla de precios absolutos.
Conceptos clave
⚖️ Punto de equilibrio
Usar la caché vale la pena cuando lees lo suficiente para amortizar la escritura. Con TTL 5 min, 2 solicitudes ya compensan (1,25× para guardar + 0,1× para volver a leer = 1,35×, frente a 2× pagando el precio completo dos veces). Con TTL 1 h (escritura ~2×), necesita ~3.
¿Nuevo por aquí? «break-even»
break-even = el punto de equilibrio: cuántas lecturas necesitas para que el costo con caché iguale (y luego supere) el costo sin caché. Antes de ese punto, solo pagaste el costo adicional del 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 la pena guardar en caché
- ✓Prefijo estable que se volverá a leer en varios turnos
- ✓Conversación activa: system + historial se repiten
✗ No guardes en caché
- ✗Prefijo que cambia el cada solicitud: solo pagas escritura, nunca lectura
- ✗Una sola llamada, sin repetición: la escritura no se amortiza
Qué es
El punto en que la caché empieza a convenir: ~2 solicitudes con TTL de 5 min, ~3 con TTL de 1 h.
Por qué aprenderlo
Enseña a NO cachear lo que cambia en cada request (solo pagarías el write) y a confiar en el caché cuando se vuelve a leer.
Conceptos clave
Resumen del módulo
Siguiente ruta
Trilha 2 — Técnico: la caché dentro de una conversación que crece, skills y herramientas (adjuntar vs. romper) y la invalidación en profundidad, con ejemplos para copiar y ejecutar.