Pagar menos en la API: effort, caché y Batch

La factura de la API de Claude depende de dos cosas: cuántos tokens mandas y cuántos genera Claude. Hay tres palancas oficiales para bajarla sin cambiar de proveedor ni perder calidad: effort, prompt caching y la Batch API. En esta guía verás cuándo usar cada una, con un cálculo real, y las trampas que hacen que el ahorro no aparezca. Te llevará unos 8 minutos.

Si todavía no has hecho tu primera llamada, empieza por la guía «Tu primera llamada a la API de Claude en Python» o por la lección La API de Claude sin miedo.

Antes de empezar

Un script que ya llame a la API con el SDK de Python.
Saber leer el objeto usage de la respuesta: es la única fuente fiable de lo que pagas.
Los precios de referencia (septiembre de 2026, por millón de tokens): Opus 5.5 cuesta 4 $ de entrada y 20 $ de salida; Sonnet 5.5, 2 $ y 10 $; Haiku 4.5, 1 $ y 5 $. Compruébalos siempre en la página de precios.

Las tres palancas, de un vistazo

De un vistazoQué recorta cada una

Effort

Recorta salida: cuánto piensa y escribe Claude. Útil en todo. Coste de aplicarlo: probar con tus casos que la calidad aguanta.

Prompt caching

Recorta entrada repetida: el manual, las instrucciones o el historial que mandas en cada llamada. En Opus 5.5 una lectura de caché cuesta el 5 % del precio de entrada.

Batch API

50 % de descuento en todo (entrada y salida) a cambio de no tener respuesta inmediata. La mayoría de lotes terminan en menos de una hora; el máximo es 24 horas.

1. Effort: que Claude no piense de más

En los modelos actuales el pensamiento adaptativo decide cuánto razona Claude, y ese razonamiento se factura como tokens de salida aunque no veas su texto. El parámetro output_config.effort es el mando: low, medium, high, xhigh y max.

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "Clasifica esta incidencia: ..."}],
)

Opus 5.5 usa medium por defecto; el resto de modelos, high. Para tareas simples y repetitivas (clasificar, extraer campos, resumir un ticket) prueba low y compara resultados. Guarda high o más para lo que de verdad lo pida. No hay cifra fija de ahorro: mídela comparando output_tokens con cada nivel sobre tus propios ejemplos.

La otra palanca de salida es el modelo: si una tarea sale bien con Sonnet 5.5, pagas la mitad que con Opus 5.5.

2. Prompt caching: no pagues dos veces el mismo manual

Imagina un asistente de soporte SAP que en cada consulta envía un manual interno de 20.000 tokens y una pregunta de 200. Marca el bloque fijo con cache_control:

MANUAL = open("manual_soporte.txt").read()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    system=[
        {"type": "text", "text": MANUAL, "cache_control": {"type": "ephemeral"}}
    ],
    messages=[{"role": "user", "content": pregunta}],
)
print(response.usage.cache_creation_input_tokens, response.usage.cache_read_input_tokens)

La primera llamada escribe la caché (1,25 veces el precio de entrada con la duración de 5 minutos). Las siguientes que llegan dentro de ese plazo la leen, y cada lectura renueva los 5 minutos sin coste extra. Si tu tráfico tiene huecos mayores, existe una caché de 1 hora ("ttl": "1h") cuya escritura cuesta el doble.

3. Batch API: la mitad si puedes esperar

Todo lo que no necesita respuesta al momento cabe aquí: clasificar las incidencias del día, revisar descripciones de material, generar textos de un catálogo. Cada petición lleva un custom_id para casar después los resultados:

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id=f"inc-{i}",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[{"role": "user", "content": texto}],
            ),
        )
        for i, texto in enumerate(incidencias)
    ]
)
print(batch.id, batch.processing_status)

Ejemplo: 10.000 incidencias de 1.500 tokens de entrada y 300 de salida con Opus 5.5 cuestan 60 $ de entrada y 60 $ de salida en tiempo real (120 $). En Batch, 60 $. Un lote admite hasta 100.000 peticiones o 256 MB, lo que llegue antes.

Batch y caché se pueden combinar y los descuentos se suman, pero dentro de un lote los aciertos de caché son de «mejor esfuerzo»: no cuentes con que todas las peticiones la lean.

Si algo falla

La caché no aparece (cache_creation_input_tokens y cache_read_input_tokens a 0): el bloque es más corto que el mínimo cacheable. En Opus 5.5 y Sonnet 5.5 son 512 tokens; en Haiku 4.5, 4.096. La API no da error: simplemente no cachea.
Siempre escribe y nunca lee: algo cambia antes del punto de caché en cada llamada (una fecha, un identificador de sesión en el prompt de sistema). La caché funciona por prefijo exacto: lo fijo, primero; lo variable, al final.
El lote tarda o caduca: los lotes que no terminan en 24 horas expiran. Trocea los muy grandes y no metas en Batch nada con plazo de minutos.
Bajaste effort y empeora la calidad: vuelve un nivel arriba solo para esa tarea. El effort se decide por caso de uso, no para toda la aplicación.

Para recordar

0 de 5 claros

Marca lo que ya tienes claro.