Por Caché de prompts de Claude: cálculo del equilibrio
Las escrituras cuestan 1,25x y las lecturas 0,1x: un prefijo de Claude se amortiza en el segundo uso. Calcula y verifica el punto de equilibrio con la API.
Qué coste tiene la caché de prompts antes de empezar a ahorrar
La caché de prompts permite que Claude reutilice el inicio del prompt en lugar de volver a leerlo en cada llamada. La decisión depende de dos multiplicadores sobre el precio base de entrada del modelo. En agosto de 2026, escribir en la caché cuesta 1.25x el precio base de entrada durante los 5 minutos de vigencia, o 2x durante 1 hora. Leer de la caché cuesta 0.1x. Estos multiplicadores se aplican a todos los modelos disponibles, por lo que el punto de equilibrio 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 de más para almacenar un prefijo. Cada solicitud posterior que empiece con exactamente los mismos bytes paga entonces una décima parte del precio normal de entrada por esa parte. Un prefijo que no se reutiliza durante su periodo de vigencia supone un coste adicional del 25 por ciento sin obtener ningún ahorro.
El punto de equilibrio, en una línea de álgebra
Llamemos B al coste de entrada base 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 lo que 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 de entrada base es de $5 por millón de tokens a fecha de agosto de 2026. Multiplique todas las cifras 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 sola solicitud 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. La caché de 1 hora todavía es más cara en ese punto: $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.
Un acierto de caché también renueva la entrada. Por eso la tabla de precios publicada denomina esa columna aciertos y renovaciones de caché. Un endpoint con mucha actividad mantiene así una entrada de 5 minutos activa indefinidamente con precios de lectura. La duración de 1 hora sólo compensa su escritura a 2x cuando el tráfico presenta intervalos reales sin solicitudes.
El coste de una tasa de aciertos baja
Las peticiones reales tienen fallos de caché. Una petición que no encuentra una entrada en la caché, pero que todavía incluye un punto de corte, se cobra como una escritura. Por tanto, 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 peticiones, 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, se pagan $125.00 en lugar de $100.00, y la caché de 1 hora duplica la factura hasta $200.00. Al resolver 1.25 menos 1.15h = 1, la caché de 5 minutos 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 para la escritura 2x da aproximadamente el 53 por ciento para la caché de 1 hora. 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 llegan a $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 la única entrada que puede controlar una vez fijado el tamaño del prefijo.
Qué prefijos justifican un punto de caché
Una solicitud puede incluir hasta cuatro puntos de caché, así que la cuestión es qué bloques los merecen. 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 el almacenamiento en 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 hacen 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 con ningún otro factor. Esto cambia qué merece la pena incluir en un prompt: cuánto cuestan realmente un millón de tokens de Claude pasa a costar una décima parte del precio indicado para cualquier contenido 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 prompt de sistema y las definiciones de las herramientas, con una tasa de aciertos del 90 por ciento, y lo extrapola 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, es decir, 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, el coste de entrada sin caché es de $40,000.00, y la caché elimina $31,400.00 de ese coste. Estas cifras corresponden sólo a tokens de entrada. La salida se factura por separado y la caché no cambia su coste. Téngalo en cuenta antes de prometer a alguien una reducción del 90 por ciento en la factura. La caché complementa las prácticas generales descritas en 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)Ejecútelo 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 sólo el nuevo mensaje del usuario. Ambas llamadas se facturan porque la Claude API no tiene nivel gratuito, aunque para el prefijo de 20,000 tokens indicado arriba, el par cuesta aproximadamente catorce centavos.
La misma comprobación desde el shell, con un cuerpo de solicitud 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 la situación real. Si cache_read_input_tokens permanece en 0 entre llamadas, paga el coste de escritura de 1.25x cada vez y no obtiene nada 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 el almacenamiento automático en caché: un único campo cache_control en el nivel superior de la solicitud, después 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 le sigue. Si edita la descripción de una herramienta, el prompt del sistema y todo el historial de mensajes quedan invalidados, aunque no los haya modificado.
Esto establece una única regla, sin excepciones. Todo lo que cambie entre solicitudes debe ir después de todo lo que no cambie.
El infractor habitual es una marca de tiempo. Una línea que contiene Current time: 2026-08-03T14:07:11Z al principio de un prompt del sistema garantiza una tasa de acierto del 0 por ciento, porque el hash del prefijo cambia en cada solicitud y ninguna entrada anterior puede coincidir. Muévala al mensaje del usuario, al final. Un identificador de sesión o un nonce por solicitud causan el mismo problema y tienen la misma solución. Los documentos recuperados que varían según la solicitud también deben ir después del bloque almacenado en caché; de lo contrario, desplazan todos los tokens estables detrás de un límite que cambia.
El segundo problema 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 en cada solicitud, nunca se almacena nada estable y la búsqueda retrospectiva 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 se considera contenido del prompt. Un modelo diferente tiene una caché diferente. Cambiar la selección de herramientas invalida desde el nivel del sistema en adelante. Añadir o eliminar una herramienta lo invalida todo.
El prefijo mínimo y la operación que no hace nada
Un prefijo más corto que el mínimo del modelo no se almacena en caché y no se informa de ello. No aparece ningún error ni advertencia. 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 cree que está almacenada en 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 con caché. Claude Haiku 4.5 necesita un prefijo ocho veces más largo que Claude Opus 5 para que el almacenamiento en caché se active. Por tanto, una solicitud de sistema de 2,000 tokens se almacena en caché con un modelo y se ignora silenciosamente con el otro.
Dónde almacena Claude Code su caché y dónde no puede ayudarte
Claude Code almacena en caché su propio prefijo. El prompt del sistema y las definiciones de las herramientas están 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.
No puede ayudarte cuando editas algo cerca del principio del contexto. El historial de la conversación sólo permite añadir contenido, por lo que los turnos nuevos amplían un prefijo que ya está almacenado en caché. Si editas un archivo que se leyó al principio de la sesión, cambias el contenido en mitad de ese prefijo y es necesario volver a escribir todos los tokens posteriores al cambio. Un intervalo largo de inactividad produce el mismo efecto, porque la entrada caduca y el siguiente turno debe pagar una escritura completa. Ninguna de las dos situaciones es un error. Ambas son consecuencia directa de la regla del prefijo.
Si estás escribiendo tu propio cliente, aplica esta estructura desde la primera solicitud en lugar de adaptarla después: construye la llamada como se muestra 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 cero 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 no alcanza el 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 después 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 habilitar 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 minutos, enviar el prefijo sin caché es 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 la caché resulte rentable?
Una vez, con la caché de 5 minutos. Una escritura cuesta 1.25x la entrada base y una lectura cuesta 0.1x, por lo que N solicitudes sin caché cuestan N, mientras que N solicitudes con caché cuestan 1.25 más 0.1 por N menos 1. Ambas curvas se cruzan en N = 1.28, por lo que la segunda solicitud ya resulta rentable. La caché de 1 hora escribe a 2x y se cruza en N = 2.11, por lo que necesita dos lecturas.
¿Por qué cache_read_input_tokens siempre es 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, la caché se omite de forma silenciosa y ambos contadores muestran 0. Si el prefijo es suficientemente largo, 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 han dejado de hacerlo, el intervalo entre solicitudes superó la duración de la caché.
¿La 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 que ya funciona sin volver a ejecutar las evaluaciones.
¿Debería pagar por la caché de 1 hora?
Sólo cuando su tráfico tenga intervalos de más de 5 minutos y la tasa de aciertos vaya a superar aproximadamente el 53 por ciento. La escritura a 2x duplica el coste desfavorable de la escritura a 1.25x cuando no hay acierto. Una entrada de 5 minutos se actualiza con cada acierto, por lo que el tráfico constante la mantiene activa con precios de lectura sin pagar nunca por una duración mayor.