Por Caché de prompts en Claude: cálculo del equilibrio
Escribir en caché cuesta 1,25x y leer 0,1x: un prefijo de Claude se amortiza en el segundo uso. Calcula tu equilibrio y compruébalo en la API.
Costes de la caché de prompts antes de que genere ahorros
La caché de prompts permite que Claude reutilice el inicio del prompt en lugar de leerlo de nuevo en cada llamada. La decisión depende de dos multiplicadores del precio base de entrada del modelo. En agosto de 2026, escribir en la caché cuesta 1.25x el precio base de entrada durante 5 minutos, o 2x durante 1 hora. Leer desde la caché cuesta 0.1x. Estos multiplicadores se aplican a todos los modelos de la lista, por lo que el punto de equilibrio siguiente no cambia cuando cambia el precio por token.
El intercambio consiste en pagar un recargo ahora para obtener un descuento después. Se paga una vez un importe adicional para almacenar un prefijo. Cada solicitud posterior que comienza con exactamente los mismos bytes paga una décima parte del precio de entrada normal por esa parte. Si un prefijo no se reutiliza durante su periodo de validez, cuesta un 25 por ciento adicional sin aportar ningún ahorro.
El punto de equilibrio, en una línea de álgebra
Llamemos B al coste base de entrada del prefijo si se enviara sin caché. Sin caché, N solicitudes cuestan N veces B. Con la caché de 5 minutos, la primera solicitud escribe el prefijo a 1.25B y las otras N menos 1 solicitudes lo leen a 0.1B. Si igualamos ambos costes, obtenemos 0.9N = 1.15, por lo que N = 1.28. La segunda solicitud ya es más barata que no usar caché.
Si repetimos el cálculo con la escritura a 2x de la caché de 1 hora, obtenemos 0.9N = 1.9, por lo que N = 2.11. La caché de larga duración necesita dos lecturas para alcanzar el punto de equilibrio, por eso no es la opción predeterminada.
El gráfico siguiente calcula estos costes para un prefijo de 20,000 tokens en Claude Opus 5, cuya tarifa base de entrada es de $5 por millón de tokens en agosto de 2026. Multiplique cada cifra por 0.6 para un modelo de $3 por millón. La forma de la curva no cambia.
The data behind this chart
[
{
"requests": 1,
"uncached_usd": "0.10",
"cached_5m_usd": "0.125",
"cached_1h_usd": "0.20"
},
{
"requests": 2,
"uncached_usd": "0.20",
"cached_5m_usd": "0.135",
"cached_1h_usd": "0.21"
},
{
"requests": 3,
"uncached_usd": "0.30",
"cached_5m_usd": "0.145",
"cached_1h_usd": "0.22"
},
{
"requests": 5,
"uncached_usd": "0.50",
"cached_5m_usd": "0.165",
"cached_1h_usd": "0.24"
},
{
"requests": 10,
"uncached_usd": "1.00",
"cached_5m_usd": "0.215",
"cached_1h_usd": "0.29"
},
{
"requests": 20,
"uncached_usd": "2.00",
"cached_5m_usd": "0.315",
"cached_1h_usd": "0.39"
}
]Una solicitud aislada cuesta $0.10 sin caché y $0.125 con caché, por lo que almacenar en caché una solicitud única supone una pérdida neta. En la segunda solicitud, la caché de 5 minutos cuesta $0.135, frente a $0.20 sin caché. En ese punto, la caché de 1 hora todavía es más cara: $0.21, frente a los mismos $0.20. Sólo supera el coste sin caché en la tercera solicitud: $0.22, frente a $0.30. Con 20 solicitudes, la diferencia es de $2.00 frente a $0.315.
Una lectura de la caché también actualiza la entrada. Por eso la tabla de precios publicada denomina esa columna lecturas y actualizaciones de caché. Un endpoint con mucho tráfico mantiene activa indefinidamente una entrada de 5 minutos con precios de lectura. La duración de 1 hora sólo compensa su escritura a 2x cuando el tráfico presenta intervalos sin actividad.
El coste de una tasa de aciertos baja
El tráfico real produce fallos de caché. Una solicitud que no encuentra la caché pero que sigue incluyendo un prefijo se cobra como una escritura, por lo que la forma correcta de modelarlo es expresar el coste en función de la tasa de aciertos. El gráfico siguiente lo muestra para 1,000 solicitudes, cada una con el mismo prefijo de 20,000 tokens.
The data behind this chart
[
{
"hit_rate_percent": 0,
"cost_5m_usd": "125.00",
"cost_1h_usd": "200.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 25,
"cost_5m_usd": "96.25",
"cost_1h_usd": "152.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 50,
"cost_5m_usd": "67.50",
"cost_1h_usd": "105.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 75,
"cost_5m_usd": "38.75",
"cost_1h_usd": "57.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 90,
"cost_5m_usd": "21.50",
"cost_1h_usd": "29.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 95,
"cost_5m_usd": "15.75",
"cost_1h_usd": "19.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 99,
"cost_5m_usd": "11.15",
"cost_1h_usd": "11.90",
"uncached_usd": "100.00"
}
]Con una tasa de aciertos del 0 por ciento, paga $125.00 en lugar de $100.00, y la caché de 1 hour duplica la factura hasta $200.00. Si resuelve 1.25 menos 1.15h = 1, la caché de 5 minutes empieza a ahorrar dinero con una tasa de aciertos de aproximadamente el 22 por ciento. Por eso, con el 25 por ciento, ya muestra $96.25. El mismo cálculo con la escritura 2x da aproximadamente el 53 por ciento para la caché de 1 hour. Por tanto, una tasa de aciertos del 50 por ciento todavía cuesta $105.00, por encima de la línea sin caché. Con el 90 por ciento, los dos valores quedan en $21.50 y $29.00. Con el 99 por ciento, la caché corta alcanza $11.15, cerca del mínimo de una décima parte del precio sin caché.
La tasa de aciertos es el valor que debe instrumentar, porque es el único parámetro que puede controlar una vez fijado el tamaño del prefijo.
Qué prefijos merecen un punto de caché
Una solicitud puede incluir hasta cuatro puntos de caché, por lo que la cuestión es qué bloques los justifican. Los candidatos son bloques idénticos byte a byte entre llamadas y lo bastante grandes como para tener impacto. El gráfico siguiente calcula el coste de cuatro estructuras habituales en 1,000 solicitudes, con una tasa de aciertos del 90 por ciento en la caché de 5 minutos.
The data behind this chart
[
{
"label": "System prompt",
"prefix_size_tokens": "2,000",
"uncached_usd": "10.00",
"cached_usd": "2.15",
"saved_usd": "7.85"
},
{
"label": "System plus tools",
"prefix_size_tokens": "8,000",
"uncached_usd": "40.00",
"cached_usd": "8.60",
"saved_usd": "31.40"
},
{
"label": "Policy document",
"prefix_size_tokens": "25,000",
"uncached_usd": "125.00",
"cached_usd": "26.88",
"saved_usd": "98.12"
},
{
"label": "Codebase context",
"prefix_size_tokens": "120,000",
"uncached_usd": "600.00",
"cached_usd": "129.00",
"saved_usd": "471.00"
}
]Un prompt de sistema básico de 2,000 tokens ahorra $7.85 por cada 1,000 solicitudes frente a $10.00 sin caché. Es un ahorro real a gran escala, pero no es lo que hace interesante la caché. Si añade las definiciones de herramientas, llega a 8,000 tokens y ahorra $31.40. Un documento de políticas de 25,000 tokens sobre el que todas las solicitudes formulan preguntas ahorra $98.12. La última fila es la que cambia la arquitectura: 120,000 tokens de contexto de una base de código o una transcripción cuestan $600.00 sin caché y $129.00 con caché, lo que supone un ahorro de $471.00.
El ahorro aumenta con el tamaño del prefijo y con la tasa de aciertos, y no depende de nada más. Esto cambia qué merece la pena incluir en un prompt: cuánto cuestan realmente un millón de tokens de Claude reduce a una décima parte del precio indicado el coste de todo lo que envíe más de una vez.
Cómo se refleja en una factura mensual
El gráfico siguiente toma el prefijo de 8,000 tokens indicado arriba, junto con un mensaje del sistema y las definiciones de herramientas, con una tasa de aciertos del 90 por ciento, y lo proyecta a volúmenes mensuales de solicitudes.
The data behind this chart
[
{
"label": "10k requests",
"uncached_usd": "400.00",
"cached_usd": "86.00",
"saved_usd": "314.00"
},
{
"label": "100k requests",
"uncached_usd": "4,000.00",
"cached_usd": "860.00",
"saved_usd": "3,140.00"
},
{
"label": "1M requests",
"uncached_usd": "40,000.00",
"cached_usd": "8,600.00",
"saved_usd": "31,400.00"
}
]Con 10,000 solicitudes al mes, el ahorro es de $314.00, la diferencia entre $400.00 y $86.00. Con 100,000 solicitudes, el ahorro es de $3,140.00. Con un millón de solicitudes, la factura de entrada sin caché es de $40,000.00 y el almacenamiento en caché elimina $31,400.00 de ese importe. Estas cifras sólo corresponden a los tokens de entrada. La salida se factura por separado y el almacenamiento en caché no la afecta. Téngalo en cuenta antes de prometer a alguien una reducción del 90 por ciento en la factura. El almacenamiento en caché complementa las prácticas más amplias para mantener bajo control la factura de un agente de IA en un VPS.
Cómo demostrar que la caché funciona
No confíe en el diseño. Lea el bloque de uso de la respuesta. Cada respuesta de la Messages API (interfaz de programación de aplicaciones) informa de los tokens almacenados en caché, los tokens leídos de la caché y los tokens nuevos que tuvo que procesar.
from anthropic import Anthropic
client = Anthropic()
resp = client.messages.create(
model="claude-opus-5",
max_tokens=512,
system=[
{
"type": "text",
"text": POLICY_DOCUMENT,
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": question}],
)
u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)Ejecute la petición dos veces con el mismo documento y una pregunta diferente. La primera llamada informa de un valor cache_creation_input_tokens distinto de cero y un valor cache_read_input_tokens igual a cero. La segunda invierte esos valores porque se encontró el prefijo. input_tokens sólo cuenta los tokens posteriores al último punto de interrupción, por lo que en una segunda llamada correcta es pequeño. Normalmente contiene sólo el nuevo mensaje del usuario.
Puede hacer la misma comprobación desde el shell con un cuerpo de petición guardado en request.json:
curl -s https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d @request.json | jq '.usage'Una segunda llamada correcta muestra algo parecido a esto:
{
"input_tokens": 42,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 20143,
"output_tokens": 187
}Una línea muestra el resultado real. Si cache_read_input_tokens permanece en 0 entre llamadas, paga el coste de escritura de 1.25x cada vez y no obtiene ningún resultado a cambio.
Para la duración de 1 hora, el punto de interrupción incluye un tiempo de vida (TTL):
{
"type": "text",
"text": "your stable prefix",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}También existe la caché automática: un único campo cache_control en el nivel superior de la petición, a partir del cual la API administra los puntos de interrupción a medida que crece la conversación. Consume uno de los cuatro espacios disponibles para puntos de interrupción. Empiece por esta opción. Cambie a puntos de interrupción explícitos cuando necesite decidir exactamente dónde se sitúa el límite.
La regla de orden que destruye las tasas de acierto
La caché compara un prefijo byte por byte desde el inicio de la solicitud, y la solicitud se ensambla en un orden fijo: herramientas, después sistema y, por último, mensajes. Un cambio en cualquier nivel invalida ese nivel y todo lo que viene después. Si edita una descripción de herramienta, la instrucción del sistema y todo el historial de mensajes quedan invalidados, aunque no los haya modificado.
Esto establece una regla sin excepciones. Todo lo que cambie entre llamadas debe ir después de todo lo que no cambie.
El infractor habitual es una marca de tiempo. Una línea con Current time: 2026-08-03T14:07:11Z al principio de una instrucción del sistema garantiza una tasa de acierto del 0 por ciento, porque el hash del prefijo cambia en cada llamada y ninguna entrada anterior puede coincidir. Muévala al mensaje del usuario, al final. Un identificador de sesión o un nonce por solicitud interrumpen la caché de la misma forma y tienen la misma solución. Los documentos recuperados que cambien en cada solicitud también deben ir después del bloque en caché; de lo contrario, desplazan todos los tokens estables detrás de un límite que cambia.
El segundo infractor es colocar el punto de corte en el bloque que cambia. Las escrituras en la caché se realizan en el punto de corte. Por tanto, si ese bloque es diferente cada vez, nunca se almacena nada estable y la búsqueda hacia atrás sólo encuentra entradas que las solicitudes anteriores escribieron en sus propios puntos de corte variables. Coloque cache_control en el último bloque cuyo contenido sea idéntico entre solicitudes.
El tercero es un cambio de parámetro que no consideraba contenido de la instrucción. Un modelo diferente usa una caché diferente. Cambiar la selección de herramientas invalida desde el nivel del sistema en adelante. Añadir o quitar una herramienta lo invalida todo.
El prefijo mínimo y la operación silenciosa sin efecto
Un prefijo más corto que el mínimo del modelo no se almacena en caché y no se muestra ninguna indicación. No hay errores ni advertencias. La solicitud se completa y ambos contadores muestran 0. En agosto de 2026, los mínimos publicados son:
- 512 tokens en Claude Opus 5 y Claude Fable 5
- 1,024 tokens en Claude Sonnet 5 y Claude Opus 4.8
- 4,096 tokens en Claude Haiku 4.5
Si ambos contadores muestran 0 en una solicitud que debería usar la caché, compruebe primero la longitud del prefijo. Esta es también la razón por la que el modelo más barato no es automáticamente el más barato para una carga de trabajo que usa la caché. Haiku 4.5 necesita un prefijo ocho veces más largo que Opus 5 para que el almacenamiento en caché se active. Por tanto, una instrucción de sistema de 2,000 tokens se almacena en caché con uno de ellos y se ignora silenciosamente con el otro.
Dónde almacena Claude Code la caché y dónde no puede ayudar
Claude Code almacena en caché su propio prefijo. El prompt del sistema y las definiciones de herramientas aparecen al principio de cada solicitud y no cambian de posición, por lo que se escriben una vez y se reutilizan durante el resto de la sesión. Por eso, el coste por turno de una sesión larga es muy inferior a lo que sugiere el tamaño del contexto. Esto se refleja en los contadores descritos en cómo informa Claude Code del uso de tokens.
La caché no puede ayudar cuando se edita contenido cerca del principio del contexto. El historial de conversación sólo permite agregar contenido al final, por lo que los turnos nuevos amplían un prefijo que ya está en caché. Si se edita un archivo que se leyó al principio de la sesión, cambia el contenido en mitad de ese prefijo y es necesario volver a escribir todos los tokens posteriores al cambio. Un periodo largo de inactividad produce el mismo efecto, porque la entrada caduca y el turno siguiente debe pagar una escritura completa. Ninguno de los dos casos es un error. Ambos son el funcionamiento normal de la regla del prefijo.
Si escribe su propio cliente, aplique esta estructura desde la primera solicitud en lugar de adaptarla después: construya la llamada como se hace en una primera aplicación de Claude API en un VPS, con los bloques estables al principio y los variables al final.
Modos de fallo y qué observará
Cada llamada es una escritura. cache_creation_input_tokens es distinto de 0 en todas las solicitudes, mientras cache_read_input_tokens permanece en 0. Algo situado en el punto de interrupción o antes de él cambia entre las llamadas. Muestre los primeros 200 caracteres del prefijo ensamblado en dos solicitudes consecutivas y compárelos visualmente.
Ambos contadores son 0. El prefijo está por debajo del mínimo del modelo o el campo cache_control nunca llegó a la API. Cuente primero los tokens del prefijo y, después, registre el cuerpo de la solicitud que envió realmente.
Las lecturas funcionan y luego se detienen. Se produce una serie de aciertos, después una escritura y, a continuación, vuelven los aciertos. El intervalo entre solicitudes fue superior al tiempo de vida. Acepte la escritura o cambie al TTL de 1 hour después de comprobar que la tasa de aciertos supera el 53 por ciento.
La tasa de aciertos disminuye después de un despliegue. Se editó la descripción de una herramienta o se cambió el modelo. Ambas acciones invalidan todo el prefijo. Espere una ronda costosa de escrituras después de cada despliegue que modifique el prompt.
La factura aumentó después de activar el almacenamiento en caché. La tasa de aciertos está por debajo del punto de equilibrio. Por debajo de aproximadamente el 22 por ciento en la caché de 5 minute, enviar el prefijo sin caché resulta más barato. Por debajo de aproximadamente el 53 por ciento ocurre lo mismo con la caché de 1 hour.
FAQ
¿Cuántas veces hay que reutilizar un prompt para que el almacenamiento en caché sea rentable?
Una vez, con la caché de 5 minutos. Una escritura cuesta 1.25x la entrada base y una lectura cuesta 0.1x. Por tanto, N solicitudes sin caché cuestan N, mientras que N solicitudes con caché cuestan 1.25 más 0.1 por N menos 1. Ambas opciones se igualan en N = 1.28, por lo que la segunda solicitud ya resulta más económica. La caché de 1 hora escribe a 2x y se iguala en N = 2.11, por lo que necesita dos lecturas.
¿Por qué cache_read_input_tokens siempre vale cero?
Compruebe primero la longitud del prefijo: por debajo del mínimo del modelo, 512 tokens en Claude Opus 5 y 4,096 en Claude Haiku 4.5 a fecha de agosto de 2026, el almacenamiento en caché se omite silenciosamente y ambos contadores muestran 0. Si el prefijo tiene una longitud suficiente, busque contenido que cambie entre llamadas y que esté en el punto de corte o antes de él, como una marca de tiempo o un identificador de sesión en el prompt del sistema. Si los contadores funcionaban y dejaron de hacerlo, el intervalo entre solicitudes fue superior a la duración de la caché.
¿El almacenamiento en caché de prompts cambia las respuestas de Claude?
No. La caché almacena la forma procesada de los tokens que ya envió, y el modelo recibe el mismo prompt en ambos casos. Es una función de facturación y latencia, no un cambio de comportamiento. Esto también significa que puede activarla en un prompt funcional sin volver a ejecutar sus evaluaciones.
¿Debería pagar por la caché de 1 hora?
Sólo cuando su tráfico tenga intervalos superiores a 5 minutos y la tasa de aciertos siga superando aproximadamente el 53 %. La escritura a 2x duplica el coste desfavorable de la escritura a 1.25x cuando no hay un acierto. Una entrada de 5 minutos se actualiza con cada acierto, por lo que un tráfico constante la mantiene activa con precios de lectura sin pagar nunca por una duración mayor.