Las mecánicas de caché, los niveles de precios, las duraciones de TTL y los umbrales mínimos de tokens cambian a medida que Anthropic actualiza la plataforma. No te fíes de ningún número concreto de guías de terceros. Consulta siempre la documentación oficial de almacenamiento en caché de prompts y la página de Modelos y Precios para los valores actuales.
Economía del Almacenamiento en Caché de Prompts
Cada vez que llamas a la API de Claude, pagas por cada token de entrada que envías, incluidos tu prompt de sistema, tus definiciones de herramientas y cualquier contexto que inyectes. Si estás haciendo muchas llamadas con el mismo prefijo grande, estás pagando por procesar ese prefijo desde cero cada vez.
El almacenamiento en caché de prompts cambia eso. Marcas como cacheable una porción estable de tu prompt. La primera llamada la procesa y la almacena. Las llamadas posteriores que aciertan en la caché se saltan ese procesamiento, y pagan una fracción de la tarifa normal por esos tokens.
El ahorro no es cosmético. Para aplicaciones con prompts de sistema grandes y estables o con contexto pesado, la caché puede cambiar la economía de una característica de "demasiado cara para lanzar" a "básicamente gratis de ejecutar".
El modelo mental: prefijo estable, sufijo volátil
Piensa en cada llamada a la API como dos partes:
El prefijo estable — contenido que no cambia entre llamadas. Aquí es donde aplica la caché. Ejemplos:
- Tu prompt de sistema
- Las definiciones de herramientas
- Un documento de referencia grande o una base de código que inyectas en cada llamada
- Un bloque largo de ejemplos few-shot
El sufijo volátil — contenido que cambia en cada llamada. Aquí es donde la caché no aplica. Ejemplos:
- El mensaje actual del usuario
- Datos en tiempo real que inyectas por petición
- El historial de conversación que crece con cada turno
La regla es simple: estructura tus prompts para que el contenido estable vaya primero y el contenido cambiante vaya al final. Los puntos de corte de caché son posicionales: todo lo que está antes del punto de corte marcado es elegible para la caché; todo lo que está después no lo es.
Si pones contenido dinámico antes del contenido estático, rompes la caché, porque el prefijo cambia en cada petición.
Cómo funciona el modelo de costes
El almacenamiento en caché de prompts introduce una división en tres del modo en que se tarifan los tokens de entrada:
| Tipo de token | Cuándo ocurre | Coste relativo a la entrada normal |
|---|---|---|
| Escritura en caché | Primera llamada, o tras expirar la caché | Más alto que la entrada normal |
| Lectura de caché | Llamadas posteriores que aciertan en la caché | Mucho más bajo que la entrada normal |
| Entrada regular | Tokens después del último punto de corte de caché | Tarifa normal |
Los multiplicadores exactos están en la página oficial de precios y fluctúan — compruébalos directamente. Lo que no cambia es la estructura: las escrituras cuestan más que lo normal, las lecturas cuestan mucho menos. El punto de cruce — cuando has hecho suficientes llamadas cacheadas para recuperar el sobrecoste de la escritura — llega rápido en cualquier prompt con contenido estable sustancial.
La latencia sigue el mismo patrón. Las lecturas de caché se saltan el procesamiento completo de la porción cacheada, lo que reduce de forma significativa el tiempo hasta el primer token en llamadas con prefijos grandes.
Cuándo ayuda el almacenamiento en caché de prompts
La caché rinde cuando se cumplen dos condiciones a la vez:
- Tienes un prefijo estable sustancial (hay un umbral mínimo de tokens por debajo del cual la caché no está disponible — consulta la documentación actual para el número exacto por modelo).
- Reutilizas ese prefijo con la frecuencia suficiente para acertar en la caché más que ocasionalmente.
Escenarios donde la caché encaja de forma natural:
- Preguntas y respuestas sobre documentos — el mismo documento grande se inyecta para muchas preguntas de usuario.
- Asistentes de programación — una base de código grande o un árbol de archivos se incluye en cada petición.
- Bucles agénticos — el mismo prompt de sistema y las mismas definiciones de herramientas se envían en cada paso de un flujo de varios pasos.
- Agentes conversacionales con instrucciones largas — una persona detallada, un conjunto de reglas o una base de conocimiento que nunca cambia entre llamadas.
- Procesamiento por lotes — muchas entradas se ejecutan contra la misma plantilla.
Cuándo no ayuda el almacenamiento en caché de prompts
La caché no es útil cuando:
- Tus prompts son cortos (por debajo del umbral mínimo de tokens cacheables).
- Tu prefijo cambia en cada llamada — inyectar una marca de tiempo, un contexto específico del usuario o cualquier personalización en la parte "estable" invalida la caché.
- Haces llamadas poco frecuentes con largos intervalos entre ellas. El contenido cacheado expira tras un TTL (una duración que puedes configurar, dentro de los límites que la API admite). Si tu tráfico es escaso, estarás pagando sobre todo costes de escritura con pocas lecturas.
- Tu prefijo es pequeño en relación con el contenido dinámico por llamada. El ahorro escala con el tamaño de lo que se cachea.
Estructurar los prompts para que sean compatibles con la caché
El único requisito estructural es el orden: el contenido estable debe ir antes del contenido volátil.
En la práctica:
[Prompt de sistema — instrucciones, persona, reglas]
[Definiciones de herramientas — si son estáticas]
[Documentos o contexto inyectados grandes — si son los mismos entre llamadas]
--------- punto de corte de caché aquí ---------
[Contenido dinámico por llamada — mensaje del usuario, fragmentos recuperados específicos de esta petición]
Marcas el punto de corte con un campo cache_control en el último bloque que quieras incluir en la caché. Todo lo que está antes de ese marcador es elegible para la caché; todo lo que está después es entrada regular.
Puedes colocar hasta cuatro puntos de corte explícitos en una sola petición. Esto es útil cuando partes distintas de tu prompt cambian a frecuencias distintas — por ejemplo, las definiciones de herramientas cambian rara vez, el historial de conversación cambia en cada turno. Cada sección puede tener su propio punto de corte.
Reglas de invalidación de caché
La caché es sensible al orden. Cualquier cambio en un bloque cacheado, o en cualquier bloque que vaya antes de él en el prompt, invalida la caché en ese punto de corte y en todos los posteriores.
Los cambios en las definiciones de herramientas invalidan todas las cachés. Los cambios en el prompt de sistema invalidan las cachés del sistema y de los mensajes. Los cambios a mitad de la conversación afectan solo a la caché de mensajes.
La implicación práctica: si estás inyectando cualquier cosa que cambia por petición, asegúrate por completo de que vive después del último punto de corte de caché, no antes ni dentro de él.
Precalentamiento y monitorización
Puedes precalentar la caché antes de que llegue el tráfico de usuarios enviando una petición con max_tokens: 0 — esto escribe la caché sin generar salida. Útil para trabajos por lotes o para adelantar el coste de escritura durante horas de baja actividad.
El campo usage de la respuesta de la API te dice cuántos tokens se leyeron de la caché (cache_read_input_tokens), cuántos se escribieron en la caché (cache_creation_input_tokens) y cuántos se facturaron como entrada regular. Monitoriza estos para verificar que tu caché está acertando de verdad y para medir el ahorro que estás obteniendo.
Usa la Calculadora de Costes para modelar el ahorro esperado antes de comprometerte con una arquitectura de caché.
La conclusión
El almacenamiento en caché de prompts no es una microoptimización. Para cualquier aplicación que envía el mismo prefijo grande repetidamente, es una decisión económica estructural. El modelo para pensarlo es directo: el contenido estable va primero, el contenido volátil va al final, pon el punto de corte en la frontera.
Si estás construyendo contra la API y aún no has mirado la caché, revisa tus prompts actuales en busca de secciones grandes y estables. Si existen, habilitar la caché suele requerir poco esfuerzo y el ahorro es real.