Si hay una feature de la API de Anthropic que está infrautilizada en aplicaciones reales, es prompt caching. Bien usada baja costes de la API entre 70% y 90% en escenarios con prompts repetitivos. Mal entendida, te puede costar más que no usarla.
Y desde marzo de 2026 hay un cambio que ha pillado a mucha gente con el pie cambiado: el TTL por defecto bajó de 1 hora a 5 minutos. Vamos por partes.
Si vienes a entender pricing en general, mira ahorrar en API IA con enrutamiento inteligente y BYOK explicado. Aquí vamos al detalle del caching.
Qué es prompt caching
Mecanismo que permite reusar la parte estática de tus prompts entre llamadas. En vez de procesar el mismo system prompt de 10K tokens cada llamada, lo procesas una vez, lo cacheas, y las llamadas siguientes lo leen del cache a una fracción del precio.
El cache cubre tools, system y messages (en ese orden) hasta el bloque marcado con cache_control. Lo que viene después se procesa como input normal cada vez.
Cuándo te conviene
Calculadora rápida:
Prompt grande estático (system prompt detallado, contexto del proyecto, RAG fijo).
Múltiples llamadas en ventana corta (asistente conversacional, agente que itera).
El mismo prefix repetido en N requests.
Si solo tiras 1-2 llamadas con prompts distintos cada vez, no te compensa. Si tiras 10+ con prefix común en pocos minutos, te ahorra dinero serio.
Pricing 2026
Para Claude Opus 4.7 / Sonnet 4.6 (ratios sobre el precio de input estándar):
|
Operación |
Multiplicador |
|---|---|
|
Cache write 5 min |
1.25x |
|
Cache write 1 h |
2x |
|
Cache read |
0.1x (90% descuento) |
Es decir:
Si normalmente pagas 1 € por 1M input tokens, los cacheas: la primera escritura de un prefix de 100K tokens te cuesta 0.125 € (5 min) o 0.20 € (1 h).
Cada lectura del cache te cuesta 0.01 € por esos mismos 100K tokens.
Break-even:
Cache de 5 min se paga con 1 lectura (1.25x escritura + 0.1x lectura = 1.35x para 2 llamadas, vs 2x sin cache).
Cache de 1 h se paga con 2 lecturas (2x escritura + 2x 0.1x lectura = 2.2x para 3 llamadas, vs 3x sin cache).
A partir de ahí, cada lectura adicional te ahorra 90% del coste del prefix.
TTL: 5 minutos vs 1 hora
Anthropic ofrece dos TTLs:
5 min (
{"type": "ephemeral"}): default desde el 6 de marzo de 2026.1 hora (
{"type": "ephemeral", "ttl": 3600}): explícito.
Ese cambio del 6 de marzo es clave. Antes el default era 1 h. Mucha gente que no actualizó su código siguió esperando 1 h y se llevó sorpresas en la factura: el cache expiraba antes, y cada nueva llamada pagaba "write" en vez de "read".
Cómo elegir:
5 min: agentes conversacionales con cadencia rápida. Operaciones síncronas. Demos en vivo.
1 h: workflows largos (research deep, análisis multi-paso, sesiones de coding agéntico de 30+ min). Worth el 2x si vas a hacer 5+ reads.
Si tu caso de uso pasa de 5 min de inactividad regularmente, especifica ttl: 3600 explícitamente o el cache expira y pagas write cada vez.
Ejemplo en código
Anthropic SDK Python
import anthropic
client = anthropic.Anthropic()
system = [
{
"type": "text",
"text": "Eres un asistente que conoce la documentación de Levante...",
},
{
"type": "text",
"text": LARGE_DOC_CONTEXT, # 50K tokens de docs
"cache_control": {"type": "ephemeral"}, # 5 min
},
]
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
system=system,
messages=[{"role": "user", "content": "¿Qué es BYOK?"}],
)
print(response.usage)
# Usage(
# input_tokens=15, # solo lo nuevo (la pregunta)
# cache_creation_input_tokens=50000, # primera vez: write
# cache_read_input_tokens=0,
# output_tokens=180,
# )Segunda llamada dentro de 5 min:
# Mismo system, distinta pregunta
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
system=system,
messages=[{"role": "user", "content": "¿Cuál es el plan free?"}],
)
print(response.usage)
# Usage(
# input_tokens=20,
# cache_creation_input_tokens=0,
# cache_read_input_tokens=50000, # ahora: read (10% precio)
# output_tokens=240,
# )TTL 1 h
"cache_control": {"type": "ephemeral", "ttl": 3600}Múltiples bloques cache
Puedes meter varios cache_control marcando distintos puntos de "fin de prefix". El último gana, los anteriores también quedan cacheados en sub-bloques (útil para patrones jerárquicos: "system base + system rol + system contexto").
system = [
{"type": "text", "text": SYSTEM_BASE},
{"type": "text", "text": ROLE_REVIEWER, "cache_control": {"type": "ephemeral"}},
{"type": "text", "text": PROJECT_CONTEXT, "cache_control": {"type": "ephemeral"}},
]Sirve para reusar partes según vayan cambiando.
Cómo medirlo
Cada respuesta incluye breakdown de uso:
response.usage.cache_creation.ephemeral_5m_input_tokens # tokens escritos a 5min
response.usage.cache_creation.ephemeral_1h_input_tokens # tokens escritos a 1h
response.usage.cache_read_input_tokens # tokens leídos
response.usage.input_tokens # tokens NUEVOSTrackea estas tres métricas por feature. Verás muy rápido qué prompts vale la pena cachear.
Si usas un AI Gateway con observabilidad (tipo Portkey o Levante Platform), suele venir un dashboard con cache hit rate por endpoint — útil para ver si tu estrategia funciona.
Workspace isolation
Desde el 5 de febrero de 2026, el cache es por workspace, no por organización. Si tienes una org con varios workspaces (dev, staging, prod), cada uno tiene su cache aislado.
Implicación: si arrancas un nuevo workspace, los caches del anterior no migran. Re-warmup necesario.
Errores comunes
1. Cache no efectivo por cambios sutiles
Si el system prompt incluye datetime.now() o un user-id distinto cada vez, el prefix cambia y el cache no aplica. La regla: lo que va antes de cache_control tiene que ser idéntico byte a byte entre llamadas.
Solución: meter elementos variables después del cache_control.
2. TTL 5 min cuando deberías 1 h
Tu workflow tarda 15 min entre llamadas. Tu cache de 5 min ya expiró. Pagas write cada llamada. Comprueba el cache_creation_input_tokens en respuesta: si es alto en cada llamada, el TTL está mal calibrado.
3. Cachear cosas pequeñas
Cachear 500 tokens te cuesta más overhead que beneficio. Mínimo recomendado: 1024 tokens en el prefix cacheado. Por debajo, no se garantiza siquiera que el sistema haga el cache.
4. Esperar caching automático
Si no metes cache_control, no hay cache. La API no decide por ti.
5. No actualizar tras el cambio del 6 de marzo
Si tu código usa ttl por defecto pensando que son 60 min, en 2026 son 5. Audita tus llamadas y especifica ttl: 3600 donde lo necesites.
6. Mezclar streaming y no-streaming
El cache funciona idéntico en ambos. Pero si haces streaming True en una llamada y False en la siguiente con el mismo prefix, el cache se mantiene. No es un problema, solo recordarlo.
Casos reales con números
RAG con docs grandes (50K tokens)
Llamadas/hora: 60 (1/min de un equipo).
TTL recomendado: 1 h (siempre warm).
Sin cache: 60 × 50K = 3M input tokens/hora a precio normal.
Con cache 1 h: 50K write × 2 + 59 × 50K read × 0.1 = 100K + 295K equivalentes ≈ 395K tokens efectivos.
Ahorro: ~87%.
Agente de coding con CLAUDE.md grande (20K tokens)
Llamadas: ráfagas de 5-15 en pocos minutos, luego pausa.
TTL recomendado: 5 min (5 lecturas en menos de 5 min).
Sin cache: 10 × 20K = 200K tokens.
Con cache 5 min: 20K × 1.25 + 9 × 20K × 0.1 = 25K + 18K = 43K.
Ahorro: ~78%.
Chatbot con system prompt mediano (5K tokens), conversación esporádica
Llamadas: 1 cada 10 min.
TTL ofrecido: solo 5 min (no llega a la siguiente llamada).
Sin cache: 10 × 5K = 50K/100 min.
Con cache 5 min: cada llamada paga write (1.25x), cache nunca se reusa. 10 × 5K × 1.25 = 62.5K.
Cache te cuesta MÁS.
Lección: si tu cadencia entre llamadas supera el TTL, el cache te perjudica. Desactiva o sube a 1 h.
Combinarlo con el resto del stack
Streaming: independiente del cache. Funciona igual.
Tool use: las definiciones de tools también se cachean si están antes del
cache_control.Vision: imágenes en el prefix también cacheables. Útil cuando le das una imagen base a varios prompts.
Extended context: con prompts muy largos (>200K tokens) el cache es prácticamente obligatorio para no quemar dinero.
Observabilidad
Si llevas el cache en serio:
Métricas por endpoint: cache hit rate, ratio creation vs read.
Alertas: si el hit rate baja del 70% en producción, algo cambió (prefix variable, TTL mal, etc.).
Dashboards: muestra coste por prompt, ahorro por caching.
Herramientas: Portkey, LiteLLM con tracking activado, Levante Platform con observabilidad nativa, o tu propio dashboard sobre los usage de Anthropic.
Conclusión
Prompt caching es dinero gratis si tienes el patrón adecuado: prompts grandes con prefix repetido y cadencia rápida. Pero exige saber qué cachear, cuánto TTL pedir y monitorizar resultados.
Tres movimientos para empezar mañana mismo:
Identifica los 2-3 prompts más caros que tienes (en tokens × frecuencia).
Mete
cache_controlen su prefix estático.Mide el
cache_read_input_tokensantes y después.
Si el ratio de read/write es 5:1 o mejor, vas bien. Si es 1:1, replantea TTL o el patrón de uso.
Recursos: docs oficiales prompt caching, pricing API Anthropic. Para entender otras formas de bajar coste: ahorrar en APIs IA con enrutamiento inteligente, BYOK explicado y AI Gateway comparativa 2026.
