Saltar al contenido

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)
  1. Qué se cobra en cada llamada sin prompt caching
  2. Lo fijo primero, lo variable al final
  3. Marcar el bloque con cache_control
  4. Cuánto dura la caché y qué la invalida
  5. Medir el ahorro con los campos de uso de la respuesta
  6. Errores comunes
  7. Preguntas frecuentes
  8. Checklist

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:

ModeloEntrada baseEscritura 5 minEscritura 1 hLectura 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.

el prompt como pila: lo fijo arriba, lo variable al finaltools · definiciones de herramientassystem · instruccionessystem · políticas y catálogomessages · historialmessages · pregunta nuevacache_controlfijo: igual en cada llamadase escribe una vez (1.25x)y luego se lee de la cachévariable: cambia siemprese cobra a precio normalorden del prefijo: tools, system, messagesfuente: documentación de prompt caching de Anthropic

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.

qué conviene cachear y dónde vacontenido¿cachear?dónde vadefiniciones de toolssíal inicio del prefijoinstrucciones del systemsíantes del breakpointcatálogo, políticas, documentossíantes del breakpointhistorial de la conversaciónsíbreakpoint al finalfragmentos de RAG por preguntanodespués del breakpointfecha, hora, id de sesiónnodespués, o fuera del promptpregunta del usuarionoal finalun byte distinto antes del breakpoint y no hay lecturalo estable primero, lo que cambia al finalhasta 4 breakpoints por petición, según la documentación

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 }],
  });
}
  1. MODEL es el id de Claude Opus 5.5, el que usan los ejemplos de la documentación.
  2. POLICIES se lee una vez al arrancar. No se arma con plantillas en cada petición: así no se cuela una fecha ni un espacio distinto.
  3. SYSTEM es una lista de bloques. El primero son las instrucciones; el segundo, las políticas.
  4. 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.
  5. ask solo cambia la pregunta, que va en messages, 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, system y messages.
  • Cambiar tool_choice o añadir o quitar imágenes: invalida messages; las tools y el system siguen sirviendo.
  • Activar o desactivar la búsqueda web o las citas: invalida system y messages.
  • Cambiar los parámetros de razonamiento o el nivel de esfuerzo: invalida messages, y según el modelo también el system y 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");
}
  1. PRICE guarda los precios por millón de tokens de Opus 5.5. Si cambias de modelo, cambia esta tabla.
  2. written y read leen los dos campos de caché; el SDK los tipa como number | null, por eso el ?? 0.
  3. w1h separa lo escrito con duración de 1 hora, que viene en cache_creation.ephemeral_1h_input_tokens y se cobra a otro precio.
  4. usd multiplica cada tipo de token por su precio y divide entre un millón.
  5. total aplica la fórmula de la documentación y hitRate dice qué parte de la entrada salió de la caché.
  6. cached es falso si los dos campos valen 0: el prefijo no llegó al mínimo o no hay punto marcado.
  7. run.ts hace 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.

costo con y sin caché (ejemplo ilustrativo)barra oscura: sin caché · barra de color: con caché1 llamada$0.0868$0.106810 llamadas$0.8680$0.2040100 llamadas$8.68$1.18con una sola llamada la caché cuesta más: escribir es 1.25xcada fila a su propia escalaOpus 5.5 · prefijo 20 000 tokens, pregunta 200, respuesta 300

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_control va 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_tokens como 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_control está 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

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

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

← Blog