Prompt caching: deja de pagar completo tu prompt largo en cada llamada
En la práctica/ 12 min de lectura
Prompt caching en la API de Claude: lo fijo primero, marcado con cache_control, y los campos de uso para ver cuánto ahorras. Código en TypeScript y guía en PDF.
- IA
- Node.js
En este artículo (8)
Prompt caching hace que la API de Claude guarde la parte fija de tu prompt (instrucciones, tools, catálogo) y la vuelva a leer a una fracción del precio de entrada en las llamadas siguientes. Pones lo fijo primero, lo marcas con cache_control y dejas lo variable al final. Sin eso, cada llamada cobra el prompt completo.
Abajo tienes qué se cobra en cada llamada, cómo ordenar el prompt, el código en TypeScript con el SDK oficial, cuánto dura la caché, qué la invalida y cómo medir el ahorro con los campos de uso. Las reglas y los precios salen de la documentación de prompt caching y de la página de precios de Anthropic, consultadas el 19 de noviembre de 2026. El código se probó con un cliente simulado, sin llamar a la API.
Qué se cobra en cada llamada sin prompt caching
La API no recuerda nada entre llamadas. Cada petición manda el prompt entero: definiciones de herramientas, instrucciones del sistema, historial y la pregunta nueva. Y cada token de entrada se cobra al precio base del modelo, aunque sea idéntico al de hace diez segundos. Si tu asistente de tienda lleva 20 000 tokens de políticas y catálogo en el system, cien preguntas son dos millones de tokens de entrada, casi todos repetidos.
Las herramientas también cuentan. Si ya leíste function calling explicado con un carrito, recuerda que el JSON de cada tool viaja en cada petición como tokens de entrada. Y en una conversación larga el historial crece en cada turno: es la misma razón por la que se agota el límite de uso de Claude Code, que ya aplica la caché por ti.
Con prompt caching, la primera llamada escribe el prefijo en la caché y las siguientes lo leen. Escribir cuesta un poco más que la entrada normal y leer cuesta mucho menos. Según la documentación, una escritura con duración de 5 minutos cuesta 1.25 veces el precio base, una de 1 hora cuesta 2 veces, y una lectura cuesta 0.1 veces en la mayoría de los modelos; en Claude Opus 5.5 y Sonnet 5.5 la lectura baja a 0.05 veces. Estos son los precios por millón de tokens publicados el 19 de noviembre de 2026:
| Modelo | Entrada base | Escritura 5 min | Escritura 1 h | Lectura de caché | Mínimo cacheable |
|---|---|---|---|---|---|
| Claude Opus 5.5 | $4 | $5 | $8 | $0.20 (0.05x) | 512 tokens |
| Claude Sonnet 5.5 | $2 | $2.50 | $4 | $0.10 (0.05x) | 512 tokens |
| Claude Sonnet 5 | $2 | $2.50 | $4 | $0.20 (0.1x) | 1,024 tokens |
| Claude Haiku 5.5 (prompts de hasta 100,000 tokens) | $0.10 | $0.125 | $0.20 | $0.01 (0.1x) | 512 tokens |
| Claude Haiku 4.5 | $1 | $1.25 | $2 | $0.10 (0.1x) | 4,096 tokens |
La cuenta del punto de equilibrio es corta. En Opus 5.5, escribir con 5 minutos cuesta 0.25 veces de más y cada lectura ahorra 0.95 veces: una sola lectura ya paga la escritura. Con la escritura de 1 hora pagas 1 vez de más, así que necesitas dos lecturas. Los multiplicadores se suman a otros modificadores de precio, como el descuento de la Batch API y la residencia de datos. Si un prefijo se usa una sola vez, cachearlo te sale más caro.
Lo fijo primero, lo variable al final
La caché funciona por prefijo. La documentación dice que el prefijo se arma en este orden: tools, luego system, luego messages. Una lectura solo ocurre si todo lo que va antes del punto marcado es idéntico, byte por byte, a una petición anterior. Si algo cambia en un nivel, ese nivel y todo lo que viene después dejan de servir.
De ahí sale la regla de orden: lo que nunca cambia va arriba y lo que cambia en cada llamada va abajo. Las definiciones de tools, siempre en el mismo orden. Las instrucciones del sistema, sin fecha ni nombre de usuario. Los documentos largos, como políticas o catálogo. Después, el historial. Al final, la pregunta nueva.
Desliza la figura para verla completa
Hay un mínimo. Un prefijo más corto que el mínimo del modelo no se cachea y la API no devuelve error: simplemente cobra todo como entrada normal. En Opus 5.5, Sonnet 5.5 y Haiku 5.5 el mínimo es de 512 tokens; en Sonnet 5, de 1,024; en Haiku 4.5, de 4,096. Un prompt de sistema de tres líneas no se beneficia.
Con RAG, los fragmentos que recuperas cambian con cada pregunta, así que van después del punto marcado. Si tu base de conocimiento es pequeña, la alternativa es meterla entera en el prompt y cachearla; el artículo sobre el chatbot RAG con tus documentos explica cuándo conviene cada camino.
Desliza la figura para verla completa
Marcar el bloque con cache_control
Hay dos formas de activarlo. La automática es un solo campo cache_control en la raíz de la petición: la API pone el punto en el último bloque cacheable y lo mueve hacia adelante cuando la conversación crece. Sirve para chats de varios turnos. La explícita pone cache_control en el bloque exacto donde termina lo fijo. Puedes usar hasta 4 puntos por petición. Este es el ejemplo explícito, un asistente de tienda con las políticas en el system:
// ask.ts
import { readFileSync } from "node:fs";
import type Anthropic from "@anthropic-ai/sdk";
export const MODEL = "claude-opus-5-5";
// Fixed part: read once at startup, the same bytes on every call.
const POLICIES = readFileSync(new URL("./policies.md", import.meta.url), "utf8");
export const SYSTEM: Anthropic.TextBlockParam[] = [
{ type: "text", text: "You answer customer questions for an online store. Use only the policies below." },
// Breakpoint: everything up to and including this block is cached.
{ type: "text", text: POLICIES, cache_control: { type: "ephemeral" } },
];
// Variable part: the question goes last, after the breakpoint.
export function ask(client: Anthropic, question: string) {
return client.messages.create({
model: MODEL,
max_tokens: 1024,
system: SYSTEM,
messages: [{ role: "user", content: question }],
});
}
MODELes el id de Claude Opus 5.5, el que usan los ejemplos de la documentación.POLICIESse lee una vez al arrancar. No se arma con plantillas en cada petición: así no se cuela una fecha ni un espacio distinto.SYSTEMes una lista de bloques. El primero son las instrucciones; el segundo, las políticas.cache_control: { type: "ephemeral" }en el segundo bloque es el punto de corte: todo lo anterior, incluido ese bloque, se escribe en la caché la primera vez y se lee después.asksolo cambia la pregunta, que va enmessages, después del punto. El prefijo es idéntico en cada llamada.
Si quieres que dure una hora, el bloque lleva cache_control: { type: "ephemeral", ttl: "1h" }. Si tus tools son largas, pon el punto en la última definición de la lista tools, que es la primera parte del prefijo. Un detalle: cada punto mira hacia atrás un máximo de 20 posiciones buscando una escritura previa. En una conversación muy larga, añade otro punto antes de pasar ese límite o usa el modo automático.
Cuánto dura la caché y qué la invalida
La duración por defecto es de 5 minutos y se renueva gratis cada vez que alguien la lee. Si tu tráfico tiene huecos más largos, la opción de 1 hora cuesta el doble al escribir pero aguanta la pausa. Ojo: la documentación mide la duración desde el inicio de la petición que escribe o lee, no desde el final de la respuesta. Una respuesta larga se come parte de esa ventana. No hay forma de borrar la caché a mano; las entradas caducan solas.
Lo que la invalida, según la tabla de la documentación:
- Cualquier cambio en el contenido antes del punto: un carácter, una línea nueva, una fecha.
- Cambiar las definiciones de tools: invalida tools,
systemymessages. - Cambiar
tool_choiceo añadir o quitar imágenes: invalidamessages; las tools y elsystemsiguen sirviendo. - Activar o desactivar la búsqueda web o las citas: invalida
systemymessages. - Cambiar los parámetros de razonamiento o el nivel de esfuerzo: invalida
messages, y según el modelo también elsystemy las tools.
La caché tampoco se comparte entre organizaciones, aunque el prompt sea idéntico, y en la API de Claude además se separa por espacio de trabajo.
Medir el ahorro con los campos de uso de la respuesta
Cada respuesta trae un objeto usage. Tres campos dicen qué pasó con la entrada: cache_creation_input_tokens son los tokens escritos en la caché, cache_read_input_tokens los leídos de ella e input_tokens los que van después del último punto. Ojo con este último: no es el total. La documentación da la fórmula: total de entrada = lectura + escritura + input_tokens. Con eso calculas el costo de cada llamada:
// cost.ts
import type Anthropic from "@anthropic-ai/sdk";
// USD per million tokens for Claude Opus 5.5, from the pricing page on 2026-11-19.
export const PRICE = { input: 4, write5m: 5, write1h: 8, read: 0.2, output: 20 };
export function cost(u: Anthropic.Usage, p = PRICE) {
const written = u.cache_creation_input_tokens ?? 0;
const read = u.cache_read_input_tokens ?? 0;
const w1h = u.cache_creation?.ephemeral_1h_input_tokens ?? 0;
const usd =
(u.input_tokens * p.input + (written - w1h) * p.write5m + w1h * p.write1h +
read * p.read + u.output_tokens * p.output) / 1e6;
const total = read + written + u.input_tokens; // the docs' total input formula
return { usd, total, hitRate: total ? read / total : 0, cached: written + read > 0 };
}
// run.ts
import Anthropic from "@anthropic-ai/sdk";
import { ask } from "./ask.ts";
import { cost } from "./cost.ts";
const client = new Anthropic(); // reads ANTHROPIC_API_KEY from the environment
for (const q of ["Do you ship to Monterrey?", "Can I return a gift?"]) {
const { usage } = await ask(client, q);
const c = cost(usage);
console.log(
`write ${usage.cache_creation_input_tokens} · read ${usage.cache_read_input_tokens}` +
` · new ${usage.input_tokens} · $${c.usd.toFixed(4)}`,
);
if (!c.cached) console.warn("no cache: prefix under the model minimum, or no breakpoint");
}
PRICEguarda los precios por millón de tokens de Opus 5.5. Si cambias de modelo, cambia esta tabla.writtenyreadleen los dos campos de caché; el SDK los tipa comonumber | null, por eso el?? 0.w1hsepara lo escrito con duración de 1 hora, que viene encache_creation.ephemeral_1h_input_tokensy se cobra a otro precio.usdmultiplica cada tipo de token por su precio y divide entre un millón.totalaplica la fórmula de la documentación yhitRatedice qué parte de la entrada salió de la caché.cachedes falso si los dos campos valen 0: el prefijo no llegó al mínimo o no hay punto marcado.run.tshace dos preguntas seguidas e imprime una línea por llamada.
Esto imprimió run.ts con el cliente simulado, que cuenta los tokens como caracteres entre cuatro (no son conteos reales de Claude):
write 4533 · read 0 · new 12 · $0.0247
write 0 · read 4533 · new 12 · $0.0030
La primera llamada escribe, la segunda lee. Si en la segunda ves otra escritura en lugar de una lectura, algo cambió en el prefijo. Para ver el efecto en volumen, este es un escenario ilustrativo calculado con la tabla de precios, no una medición: prefijo de 20 000 tokens, pregunta de 200, respuesta de 300, todas las llamadas dentro de la ventana de 5 minutos. Sin caché, cien llamadas cuestan $8.68; con caché, $1.18. Solo en entrada, el gasto baja de $8.08 a $0.58, un 93 % menos. Con una sola llamada, la caché cuesta más: $0.1068 contra $0.0868.
Desliza la figura para verla completa
Errores comunes
- Una fecha u hora en el prompt de sistema. Cambia en cada llamada y el prefijo nunca coincide: pagas la escritura de 1.25 veces cada vez. Ponla después del punto o quítala.
- El punto marcado en el bloque que cambia. Si
cache_controlva en la pregunta del usuario, cada llamada escribe una entrada nueva y nunca lee. - Tools en distinto orden. Si las armas desde un objeto o una consulta sin orden fijo, el JSON cambia y la caché se invalida entera.
- Un prefijo por debajo del mínimo. No da error; solo no cachea. Revisa que los dos campos de caché no valgan 0.
- Leer
input_tokenscomo el total. Es solo lo que va después del último punto; suma los tres campos. - Cachear algo que se usa una vez. La escritura cuesta más que la entrada normal; sin lecturas, pierdes dinero.
- Fragmentos de RAG antes del punto. Cambian con cada pregunta y rompen el prefijo de todo lo que va detrás.
Preguntas frecuentes
¿Cuántos tokens necesita un prompt para que se cachee?
Depende del modelo: 512 tokens en Opus 5.5, Sonnet 5.5 y Haiku 5.5; 1,024 en Sonnet 5; 4,096 en Haiku 4.5. Si el prefijo es más corto, la API lo procesa sin caché y sin avisar.
¿Uso la caché de 5 minutos o la de 1 hora?
La de 5 minutos si las llamadas llegan seguidas, porque cada lectura la renueva gratis. La de 1 hora si hay pausas largas entre llamadas o respuestas que tardan; cuesta 2 veces el precio base al escribir y necesita al menos dos lecturas para salir a cuenta.
¿Puedo borrar la caché?
No. La documentación dice que no hay forma de limpiarla a mano: las entradas caducan solas tras el tiempo de inactividad. Si cambias el prompt, la siguiente llamada escribe una entrada nueva.
¿Otra cuenta puede leer lo que guardé en la caché?
No. Las cachés no se comparten entre organizaciones, aunque el prompt sea idéntico, y en la API de Claude se separan también por espacio de trabajo. La clave de la caché sale de un hash del prompt hasta el punto marcado.
Checklist
- El prompt va en orden: tools, instrucciones, documentos, historial, pregunta.
- Nada antes del punto cambia entre llamadas: sin fechas, ids ni nombres.
- Las tools salen siempre en el mismo orden.
cache_controlestá en el último bloque fijo, no en la pregunta.- El prefijo supera el mínimo del modelo.
- Elegiste 5 minutos o 1 hora según el ritmo de tus llamadas.
- Registras los tres campos de entrada y la tasa de lectura.
- Los precios del cálculo coinciden con la página de precios de tu modelo.
Con el prefijo estable, cada llamada repetida paga una fracción de lo que pagaba. Si tu prompt además lleva tools, el siguiente paso es el bucle de function calling.
¿Viste esto en Instagram? Todas las guías de los Reels están en ecomlabs.dev/guias.
Escrito por

Publicado el 19 de noviembre de 2026 · actualizado el 20 de noviembre de 2026