Prompt caching con Claude: cómo reducir el costo de tu API hasta 90%

Si tu aplicación envía el mismo system prompt extenso, las mismas definiciones de herramientas o el mismo documento largo en cada llamada, estás pagando precio completo de input por reprocesar texto idéntico una y otra vez. El prompt caching guarda ese prefijo ya procesado y, en las llamadas siguientes, lo lee desde cache a una fracción del costo.

El ahorro neto depende de dos cosas: qué fracción de tu prompt es prefijo reutilizable y cuántas veces lo relees dentro de la ventana de tiempo. En cargas con prefijo grande y muchas relecturas, el ahorro sobre el costo total se ubica en el rango de 60% a 90%. No es magia: es no volver a pagar por lo que ya se procesó.

• **TTL por defecto: 5 minutos.** Cada vez que el contenido cacheado se reutiliza dentro de la ventana, el TTL se reinicia sin costo adicional.
• **TTL extendido: 1 hora.** Se activa agregando "ttl": "1h" dentro de cache_control. Útil para tráfico intermitente con huecos largos. Su escritura cuesta más (alrededor de 2x el input base).
• **Máximo 4 puntos de corte** (cache_control) explícitos por request.

// 5 minutos (por defecto)
{ "cache_control": { "type": "ephemeral" } }

// 1 hora
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

Regla práctica: si tu tráfico es continuo (requests cada pocos minutos), el TTL de 5 minutos basta y es más barato. El de 1 hora conviene cuando hay pausas largas entre llamadas que comparten el mismo prefijo.

System prompt extenso (Python)

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "Prompt de sistema extenso o documento largo...",
            "cache_control": {"type": "ephemeral"},  # TTL 5 min
        }
    ],
    messages=[{"role": "user", "content": "Resume los puntos clave"}],
)

Tools + documento largo, corte al final del prefijo estable (Python)

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[
        {"name": "buscar", "description": "...", "input_schema": {}},
        {"name": "crear", "description": "...", "input_schema": {},
         "cache_control": {"type": "ephemeral"}},  # cachea TODAS las tools
    ],
    system=[
        {"type": "text", "text": "Instrucciones del agente"},
        {"type": "text", "text": "Documento largo de contexto",
         "cache_control": {"type": "ephemeral"}},  # cachea tools + system
    ],
    messages=[
        {"role": "user", "content": "Pregunta que cambia en cada llamada"},
    ],
)

TTL de 1 hora (TypeScript)

const response = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: "Documento largo de contexto...",
      cache_control: { type: "ephemeral", ttl: "1h" },
    },
  ],
  messages: [{ role: "user", content: "Resume los puntos clave" }],
});

• **Agentes con system prompt largo o muchas tools.** Las definiciones de herramientas van en posición cero del prefijo; cachear tools + system reduce el costo fijo de cada turno.
• **RAG con contexto repetido.** El documento o los ejemplos few-shot extensos como prefijo fijo, con la pregunta variable después del último punto de corte.
• **Conversaciones multi-turno.** El historial previo se relee desde cache en cada turno; los aciertos se acumulan a medida que crece la conversación.
• **Análisis de documentos largos.** El documento se cachea una vez y múltiples preguntas sobre él solo pagan cache read.