Prompt caching en Claude: cómo reducir tu factura de API hasta un 90%

El problema que nadie te cuenta cuando escala tu uso de la API de Claude

Si tienes una aplicación en producción que usa Claude, probablemente ya notaste el patrón: cada llamada a la API envía el mismo bloque de contexto una y otra vez. El system prompt, los documentos de referencia, los ejemplos few-shot, las instrucciones de comportamiento. Todo eso se tokeniza y se cobra en cada request, aunque no haya cambiado ni una coma desde la llamada anterior.

Anthropic ofrece una solución directa a este problema: prompt caching. Bien implementado, puede reducir costes entre un 70% y un 90% en flujos de trabajo con contextos repetidos. Aquí te explico exactamente cómo funciona y cómo implementarlo hoy.

Cómo funciona el prompt caching por dentro

El mecanismo es conceptualmente simple: cuando marcas una parte del prompt para caché, Claude almacena ese bloque procesado durante 5 minutos (con opción de extender a versiones futuras). Si la misma llamada —o una llamada diferente— envía exactamente ese bloque en la misma posición, Claude reutiliza el procesamiento ya hecho en lugar de repetirlo.

La tarifa actual en Claude 3.5 Sonnet es reveladora:

• Tokens de entrada normales: $3.00 por millón
• Escribir al caché (cache write): $3.75 por millón (un 25% más caro la primera vez)
• Leer desde caché (cache read): $0.30 por millón (un 90% más barato)

La lógica económica es clara: pagas un poco más la primera vez que el bloque entra al caché, y después prácticamente lo regalas. Si tu system prompt tiene 2.000 tokens y haces 1.000 llamadas al día, la diferencia anual es significativa.

Requisito técnico fundamental: el prefijo debe ser idéntico

Este es el punto donde más proyectos fallan en la implementación. El caché solo funciona si el bloque marcado es exactamente igual y ocupa exactamente la misma posición en el array de mensajes. Un solo espacio de diferencia invalida el caché.

Implicación práctica: el contenido dinámico (la pregunta del usuario, la fecha actual, variables de sesión) debe ir después del bloque cacheado, nunca dentro de él.

Implementación paso a paso con la API

La sintaxis usa el campo cache_control dentro del contenido del mensaje. Aquí un ejemplo completo en Python:

import anthropic

client = anthropic.Anthropic()

# Este bloque largo se enviará una vez al caché
SYSTEM_PROMPT_LARGO = """Eres un asistente especializado en análisis legal.
Tienes acceso a los siguientes documentos de referencia:
[...aquí podrían ir 10.000 tokens de documentación...]
Siempre cita el artículo específico cuando respondas."""

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT_LARGO,
            "cache_control": {"type": "ephemeral"}  # Marca para caché
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "¿Qué dice el contrato sobre las penalizaciones por retraso?"
        }
    ]
)

print(response.usage)  # Verifica cache_read_input_tokens

El campo usage de la respuesta devuelve métricas diferenciadas: cache_creation_input_tokens (primera llamada) y cache_read_input_tokens (llamadas siguientes). Monitoriza estos valores para confirmar que el caché está funcionando.

Tres patrones de uso donde el ahorro es máximo

• RAG con documentos fijos: Si tu sistema recupera siempre los mismos documentos base (manuales de producto, bases de conocimiento internas), cachea ese contexto y solo varía la query del usuario.
• Few-shot prompting extenso: Los ejemplos de entrenamiento en el prompt raramente cambian. Un bloque de 20 ejemplos bien cacheado se amortiza desde la segunda llamada.
• Chatbots con historial largo: Puedes marcar el historial de conversación hasta cierto punto y solo añadir el último mensaje dinámicamente. Útil en sesiones de soporte con mucho contexto acumulado.

Lo que el prompt caching no resuelve

El caché tiene un TTL de 5 minutos que se reinicia con cada lectura. Si tu aplicación tiene periodos de inactividad superiores a ese tiempo, el primer request de cada ciclo pagará precio completo. En casos de uso con llamadas muy espaciadas (por ejemplo, un batch nocturno), el ahorro será marginal.

Tampoco funciona si el bloque a cachear cambia frecuentemente. Si tu system prompt incluye la hora actual o el nombre del usuario, el caché nunca se activa. La solución es simple: extrae ese contenido dinámico del bloque marcado.

Siguiente paso: audita tus llamadas actuales

Antes de refactorizar, analiza tus logs de API y responde estas preguntas: ¿Qué porcentaje de tus tokens de entrada son contexto repetido? ¿Tienes system prompts de más de 1.024 tokens (el mínimo para que el caché sea rentable)? ¿Con qué frecuencia varían tus documentos de referencia?

Si más del 50% de tus tokens son contexto estático y haces más de 100 llamadas diarias, el prompt caching no es una optimización opcional. Es una decisión de arquitectura que deberías haber tomado ayer.