Prompt Caching y Batch API: la economía de escala

Tiempo: ~30 min de teoría + 30 min de práctica

Lo esencial

Dos mecanismos para ahorrar a escala: Prompt Caching es como una membresía de gimnasio (pagas la entrada una vez y vas muchas veces), y Batch API es como un pedido al mayoreo en una fábrica (más barato por unidad, pero esperas la entrega hasta 24 horas). Cada uno por separado da descuentos de 50 a 90%. Juntos, en los tokens de entrada que están en caché, el ahorro llega hasta 95% del precio base (en Opus 5.5 y Fable 5.1 la caché es todavía más barata). Precios y versiones vigentes: Lo vigente.

Conceptos clave

• Prompt Caching: guardar en caché las partes repetidas del prompt en los servidores de Anthropic
• cache_control: el marcador {"type": "ephemeral"} que indica qué guardar en caché
• TTL: el tiempo de vida de la caché: 5 minutos (estándar, "5m") o 1 hora ("1h", más cara al escribir)
• Precio de la caché: escritura 5m: 1.25x del precio base; escritura 1h: 2x; lectura: 0.1x (ahorro de 90%; en Opus 5.5 la lectura es 0.05x, y en Fable 5.1 es todavía más barata)
• Batch API: envío por lotes de hasta 100 000 solicitudes (o 256 MB) con 50% de descuento
• Estados del lote: in_progress → ended (la mayoría termina en menos de 1 hora; el máximo es 24 horas)

Teoría

Parte 1: Prompt Caching

Cómo funciona la caché

Cada vez que envías una solicitud a Claude, pagas por todos los tokens: el prompt de sistema, el contexto, los ejemplos, el mensaje del usuario. Si el prompt de sistema tiene 3000 tokens y haces 1000 solicitudes al día, son 3 millones de tokens solo en contexto repetido.

Prompt Caching guarda el prompt en los servidores de Anthropic. Hay dos TTL (tiempo de vida de la caché):

Primera solicitud: pagas la escritura en caché (1.25x para 5m o 2x para 1h)
Solicitudes 2-N (dentro del TTL): pagas alrededor del 10% por leer de la caché (en Opus 5.5, el 5%; en Fable 5.1, todavía menos) + el precio completo de los tokens que no están en caché

🎨 Imagínalo así: la caché de 5 minutos es una tarjeta de cafetería para la mañana: el segundo café cuesta el 10%, pero solo mientras sigas en la cafetería. La de 1 hora es una tarjeta para todo el día: más cara al comprarla, pero te dura mucho más.

Estructura de una solicitud con caché

Forma 1: caché automática (cache_control a nivel superior)

La más sencilla: agrega cache_control a nivel de la solicitud y la API decide sola qué guardar en caché:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    cache_control={"type": "ephemeral"},  # ← caché automática
    system="Eres un asistente especializado en analizar contratos...",
    messages=[{"role": "user", "content": "Analiza este contrato: [texto]"}]
)

Forma 2: breakpoints explícitos (control puntual)

Para un control preciso, pon cache_control en bloques concretos de contenido:

# Prompt de sistema de más de 2000 tokens (largo y repetido)
SYSTEM_PROMPT = """
Eres un asistente especializado en analizar contratos de arrendamiento de inmuebles.
Trabajas solo en español.

REGLAS DE ANÁLISIS:
1. Revisa siempre el plazo del arrendamiento y las fechas de inicio y fin
2. Destaca las condiciones de terminación anticipada
3. Registra las multas y penalizaciones
4. Revisa si hay ajuste o indexación de la renta
5. Señala la responsabilidad de cada parte en las reparaciones
...otros 1500 tokens de reglas y ejemplos...
"""

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}  # ← marcador en un bloque concreto
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Analiza este contrato: [texto del contrato]"
        }
    ]
)

# Verificamos que la caché funcione
usage = response.usage
print(f"Tokens de entrada: {usage.input_tokens}")
print(f"Tokens escritos en caché: {usage.cache_creation_input_tokens}")
print(f"Tokens leídos de la caché: {usage.cache_read_input_tokens}")

Forma 3: TTL de 1 hora (para lotes y tareas largas con razonamiento)

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    cache_control={
        "type": "ephemeral",
        "ttl": "1h"  # ← 1 hora en lugar de 5 minutos (escritura más cara, lectura igual)
    },
    system="Prompt de sistema largo...",
    messages=[{"role": "user", "content": "Solicitud..."}]
)

Qué conviene guardar en caché

Mínimo para la caché (depende del modelo; a octubre de 2026):

Por debajo del mínimo, la caché no se crea, y sin avisar (no hay error). Revísalo: si cache_creation_input_tokens y cache_read_input_tokens valen 0 los dos, la caché no funcionó.

Modelo de precios de la caché (a octubre de 2026)

Sonnet 5.5 (la opción típica, $2/MTok de entrada):

Todos los modelos vigentes (a octubre de 2026):

Fórmula: escritura 5m = 1.25x de la base, escritura 1h = 2x de la base, lectura = 0.1x de la base (en Opus 5.5, 0.05x; en Fable 5.1, menos todavía). Los precios cambian de una versión a otra, pero el principio se mantiene: Lo vigente.

En la primera solicitud pagas un poco más por crear la caché. Desde la segunda solicitud dentro del TTL ya ahorras alrededor de 90% en los tokens guardados en caché.

Ejemplo de ahorro

Escenario (precios de Sonnet 5.5 a octubre de 2026): 1000 solicitudes al día, prompt de sistema de 3000 tokens, respuesta de 500 tokens. Las solicitudes llegan con suficiente frecuencia como para que la caché se renueve cada 5 minutos.

Sin caché:
  Entrada: 1000 × 3000 = 3,000,000 tokens × $2/1M = $6.00/día
  Salida: 1000 × 500 = 500,000 tokens × $10/1M = $5.00/día
  Total: $11.00/día

Con caché (TTL de 5 minutos, una sesión):
  Creación de la caché (1 vez): 3000 × $2.50/1M = $0.0075
  Lectura de la caché (999 veces): 999 × 3000 × $0.20/1M = $0.599
  Salida (1000 veces): $5.00/día
  Total: $5.61/día

Ahorro: ~49%

El ejemplo muestra el método de cálculo. Usa tus propias cifras de la página Lo vigente: el ahorro depende de qué parte del costo total es entrada repetida.

Varios puntos de caché (breakpoints)

🎨 Imagínalo así: separadores en un libro grueso: uno en la introducción, otro a la mitad, otro al final. No lees desde el principio cada vez; saltas directo a donde necesitas. Los breakpoints son separadores para la API: lee la caché desde el punto indicado y no recalcula todo desde cero.

Puedes guardar en caché varios bloques en una misma solicitud. El máximo es 4 breakpoints (cache_control explícitos):

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": BASE_RULES,           # Reglas base (siempre)
            "cache_control": {"type": "ephemeral"}  # breakpoint 1
        },
        {
            "type": "text",
            "text": DOMAIN_KNOWLEDGE,     # Conocimiento del dominio (cambia a veces)
            "cache_control": {"type": "ephemeral"}  # breakpoint 2
        }
    ],
    messages=[{
        "role": "user",
        "content": user_question
    }]
)

Orden de revisión de la caché: la API revisa la caché en este orden: tools → system → messages. Cada breakpoint guarda todo el contenido anterior a él, incluido él mismo (de forma acumulativa).

Qué se guarda en caché y qué no

Qué invalida la caché

Cambiar cualquiera de estos parámetros "rompe" la caché, y la siguiente solicitud creará una nueva:

• Las definiciones de herramientas
• Los parámetros de thinking y effort (en algunos modelos)
• Cambiar tool_choice
• Cambiar las imágenes del prompt

Parte 2: Batch API

Cuándo necesitas Batch API

🎨 Imagínalo así: un servicio de mensajería. Puedes pedir un taxi ahora mismo y pagar el triple, o entregar 1000 paquetes para el día siguiente y recibir un descuento de mayoreo del 50%. Batch API es la mensajería al mayoreo: no es urgente, pero sale barato.

Batch API es para tareas que no necesitan respuesta inmediata. Procesas un paquete de solicitudes, recibes los resultados en unas horas y pagas la mitad.

Escenarios ideales:

• Clasificar 5000 reseñas de clientes
• Generar descripciones para 2000 productos
• Analizar 1000 currículums
• Traducir 3000 artículos
• Optimizar el SEO de 500 páginas
• Evaluaciones masivas (miles de casos de prueba)

Qué puedes mandar en un lote: cualquier solicitud de la Messages API: Vision, tool use, mensajes de sistema, varios turnos, modo de razonamiento (thinking), cualquier función beta. Excepción: el fast mode no está disponible en lotes. Cada solicitud se procesa de forma independiente; puedes mezclar distintos tipos en un mismo lote.

Consejo: para lotes con un prompt de sistema común usa la caché de 1 hora ("ttl": "1h"): un lote suele durar más de 5 minutos, y la caché de 5 minutos caducará.

Enviar un lote

import anthropic

client = anthropic.Anthropic()

# Preparar las solicitudes. Haiku 4.5 podría retirarse de la API no antes del 15.10.2026:
# antes de ejecutarlo, revisa la página de model deprecations y usa el modelo barato vigente
requests = []
products = load_products_from_db()  # tus 1000 productos

for i, product in enumerate(products):
    requests.append({
        "custom_id": f"product-{product['id']}",  # tu ID para emparejar resultados
        "params": {
            "model": "claude-haiku-4-5-20251001",  # Haiku para lotes: más barato
            "max_tokens": 500,
            "messages": [{
                "role": "user",
                "content": f"""Escribe una descripción SEO para el producto:
Nombre: {product['name']}
Categoría: {product['category']}
Características: {product['specs']}

La descripción debe tener de 100 a 150 palabras e incluir palabras clave."""
            }]
        }
    })

# Enviamos el lote
batch = client.messages.batches.create(requests=requests)

print(f"Lote creado: {batch.id}")
print(f"Estado: {batch.processing_status}")  # in_progress
print(f"Solicitudes en el lote: {batch.request_counts.processing}")

Revisar el estado y obtener los resultados

import time

batch_id = batch.id

# Esperamos a que termine (polling)
while True:
    batch_status = client.messages.batches.retrieve(batch_id)
    
    if batch_status.processing_status == "ended":
        print("¡Lote terminado!")
        print(f"Exitosas: {batch_status.request_counts.succeeded}")
        print(f"Con error: {batch_status.request_counts.errored}")
        break
    
    print(f"En proceso: {batch_status.request_counts.processing} solicitudes...")
    time.sleep(60)  # revisamos una vez por minuto

# Obtenemos los resultados
results = {}
for result in client.messages.batches.results(batch_id):
    if result.result.type == "succeeded":
        results[result.custom_id] = "".join(b.text for b in result.result.message.content if b.type == "text")
    else:
        results[result.custom_id] = None
        print(f"Error en {result.custom_id}: {result.result.error}")

# Guardamos en la base de datos
save_descriptions_to_db(results)

Estados del lote

in_progress  → las solicitudes se están procesando
ending       → terminando (algunas siguen en curso)
ended        → todo listo, los resultados están disponibles

Dentro de cada solicitud:
  succeeded   → OK, hay resultado
  errored     → error (rate limit, solicitud inválida)
  expired     → la solicitud no se procesó en 24 horas
  canceled    → el lote se canceló a mano

🎨 Imagínalo así: revisar el estado de un lote es como rastrear un paquete en el sitio de la paquetería: entras una vez por minuto, ves "en camino" o "entregado", y no esperas a que te llame el repartidor.

Importante: los resultados del lote están disponibles 29 días después de crearlo. Pasado ese plazo, el lote sigue visible, pero ya no puedes descargar los resultados.

Cancelar un lote

# Si cambiaste de opinión, cancélalo mientras se pueda
client.messages.batches.cancel(batch_id)

Las solicitudes canceladas y no procesadas no se cobran.

Precios de Batch API

Todo al 50% de los precios estándar, tanto la entrada como la salida:

Batch API + el beta header output-300k-2026-03-24: hasta 300 000 tokens de salida por solicitud en Opus 5.5, Sonnet 5.5 y varios modelos anteriores (el límite normal de una solicitud síncrona es de 128k en Fable 5.1, Opus 5.5 y Sonnet 5.5, y de 64k en Haiku 4.5). Una respuesta así puede tardar más de una hora en generarse, así que cuenta con la ventana de 24 horas.

La combinación: Batch + Caching = el máximo ahorro

# Prompt de sistema común, en caché con TTL de 1 hora (¡el lote dura más de 5 min!)
ANALYSIS_SYSTEM = """[más de 4500 tokens de reglas de análisis: para Haiku 4.5 el mínimo de caché es 4096 tokens]"""

requests = []
for doc in documents:  # 5000 documentos
    requests.append({
        "custom_id": f"doc-{doc['id']}",
        "params": {
            "model": "claude-haiku-4-5-20251001",
            "max_tokens": 300,
            "system": [
                {
                    "type": "text",
                    "text": ANALYSIS_SYSTEM,
                    "cache_control": {
                        "type": "ephemeral",
                        "ttl": "1h"  # ← ¡1 hora! El lote dura más de 5 minutos
                    }
                }
            ],
            "messages": [{"role": "user", "content": doc['text']}]
        }
    })

batch = client.messages.batches.create(requests=requests)

¿Por qué "1h" y no "5m"? El lote se procesa de forma asíncrona. Si tarda 20 minutos, la caché de 5 minutos caduca después de las primeras solicitudes y los 4500 documentos restantes pagan el precio completo. La caché de 1 hora es más cara al escribir (2x), pero en total sale más barata.

Una ilustración con $100 hipotéticos (el ahorro real depende de qué parte de la entrada se repite):

🎨 Imagínalo así: dos tipos de ahorro en una tienda. Prompt Caching es la tarjeta de cliente frecuente: el segundo café sale más barato. Batch API es el pedido al mayoreo: llevas 1000 piezas y te dan precio de mayoreo. Si usas los dos, el descuento es máximo.

Práctica

Tarea: procesamiento por lotes con caché

1. Prepara una lista de 10 textos cortos (reseñas, descripciones, lo que sea):

   texts = [
       "¡Excelente servicio, lo recomiendo a todos!",
       "La entrega se retrasó 3 días, qué molesto.",
       # ... otros 8 textos
   ]

2. Crea un lote para clasificar el sentimiento (positivo/negativo/neutral):

   SENTIMENT_PROMPT = """
   Clasifica el sentimiento del texto.
   Responde con una sola palabra: positivo, negativo o neutral.
   No agregues explicaciones.
   """  # ~50 tokens: no llega al mínimo; agrega más reglas y ejemplos

3. Agrega cache_control al prompt de sistema (amplíalo con ejemplos: para Sonnet 5.5 necesitas al menos 512 tokens, para Haiku 4.5 al menos 4096)

4. Envía el lote y arranca el ciclo de polling para revisar el estado

5. Cuando termine: muestra el custom_id + el resultado de cada texto

6. Revisa el usage de las respuestas: ¿aparecen cache_read_input_tokens?

Objetivo: recorrer el ciclo completo de Batch API y ver el ahorro en números reales.

Funciones de pago adicionales de la API (a octubre de 2026)

Además de los tokens del modelo, la Claude API tiene servicios que se cobran aparte:

Fast mode (research preview) para Opus 5.5: bastante más rápido, pero el doble de caro: $8/MTok de entrada y $40/MTok de salida, contra $4 y $20 en el modo normal. No funciona con Batch API. Úsalo cuando la velocidad importe más que el precio.

🎨 Imagínalo así: Web Search es como un buscador de pago para Claude. Code Execution es como un arenero donde Claude puede ejecutar Python de verdad y ver el resultado (en lugar de adivinarlo). Managed Agents es un servidor rentado para tu agente: pagas por hora, como un taxi con el taxímetro corriendo.

Herramientas y recursos

• Documentación de Prompt Caching: platform.claude.com/docs: prompt caching
• Documentación de Batch API: platform.claude.com/docs: batch processing
• Precios: platform.claude.com/docs: pricing
• API Console: platform.claude.com
• Python SDK: pip install anthropic (Batch API viene incluida en el SDK)
• Límites de Batch API: hasta 100 000 solicitudes o 256 MB; los resultados se guardan 29 días
• Beta header output-300k-2026-03-24: hasta 300k tokens de salida en lotes para Opus 5.5, Sonnet 5.5 y varios modelos anteriores
• Precios y versiones vigentes: Lo vigente

Conclusiones clave

Prompt Caching se paga solo desde la segunda solicitud. Dos TTL: 5 minutos (por defecto, escritura +25%) y 1 hora (escritura +100%); la lectura suele costar 0.1x (−90%), y en Opus 5.5 y Fable 5.1 todavía menos. El mínimo para la caché depende del modelo: de 512 a 4096 tokens. Si el prompt es más corto, la caché no se crea y no hay aviso. Batch API: hasta 100 000 solicitudes a la vez, 50% de descuento. La mayoría de los lotes termina en < 1 hora. Para los lotes usa la caché de 1 hora ("ttl": "1h"): la de 5 minutos caduca antes de que el lote termine. Combina los dos métodos en tareas masivas: ahorro de 90 a 95% del precio base.

Siguiente lección

→ Loop y Scheduled Tasks: cuándo usar cada uno