Claude Opus 5.5: tutorial de niveles de esfuerzo, modo rápido y caché para controlar el gasto

Claude Opus 5.5 ya no te deja apagar el pensamiento, y eso cambia cómo se controla el gasto. El único mando que queda es el nivel de esfuerzo, que ahora viene por defecto en medium en vez de high, más un modo rápido que duplica la tarifa. Este tutorial explica, con código que puedes copiar, cómo elegir el esfuerzo correcto, cuándo activar el modo rápido y cómo medir lo que gastas antes de que la factura te lo diga.

Lo que necesitas antes de empezar

• Python 3.10 o superior y el SDK oficial: pip install anthropic.
• Una clave de API de Anthropic en la variable de entorno ANTHROPIC_API_KEY.
• El identificador del modelo: claude-opus-5-5.

Si vienes de Opus 5 y ya tienes código funcionando, lee antes la sección de cambios que rompen: hay cuatro y todos devuelven error 400, así que se detectan rápido pero paran producción.

Paso 1: la llamada mínima que funciona

Opus 5.5 piensa siempre. No hay que activarlo ni configurarlo: basta con omitir el parámetro thinking o pasarlo en modo adaptativo.

import anthropic

client = anthropic.Anthropic()

respuesta = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Resume este informe en cinco puntos."}],
)

print(respuesta.content[0].text)
print(respuesta.usage)

Fíjate en max_tokens=16000. Poner una cifra baja «por si acaso» es el error más común: cuando la respuesta choca contra el tope, se corta a media frase y hay que repetir la llamada, así que ahorrar ahí sale caro. Para peticiones sin streaming, 16.000 es un valor razonable; el modelo admite hasta 128.000 tokens de salida, pero para esas cifras hay que usar streaming o la petición se queda sin tiempo.

Paso 2: elegir el nivel de esfuerzo

El esfuerzo va dentro de output_config, no en la raíz de la petición. Es un error frecuente y devuelve un 400 poco descriptivo.

respuesta = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

Hay cinco niveles: low, medium, high, xhigh y max. El de Opus 5.5 por defecto es medium, un escalón por debajo del high que tenía Opus 5. Si migras código sin tocar nada, estás bajando de nivel sin darte cuenta.

La regla práctica

Empieza por el nivel más bajo que resuelva tu caso y sube solo con datos. Bajar esfuerzo reduce las llamadas a herramientas, acorta los preámbulos y hace las confirmaciones más escuetas, y para mucho trabajo de producción eso es exactamente lo que quieres.

Y ajusta por ruta, no de forma global. En una misma aplicación, el endpoint que clasifica tickets y el que refactoriza código no tienen por qué compartir nivel.

Paso 3: el modo rápido, y cuándo no usarlo

El modo rápido ejecuta el mismo modelo hasta 2,5 veces más rápido en tokens de salida por segundo, a cambio de duplicar la tarifa: 8 dólares de entrada y 40 de salida por millón, frente a 4 y 20 del estándar.

Requiere tres cosas a la vez. Si falta una, la petición falla:

1. Usar el endpoint beta: client.beta.messages, no client.messages.
2. Pasar la marca beta fast-mode-2026-02-01.
3. Poner speed="fast" como parámetro de primer nivel, no como cabecera.

respuesta = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    speed="fast",
    betas=["fast-mode-2026-02-01"],
    messages=[{"role": "user", "content": "..."}],
)

print(respuesta.usage.speed)   # confirma qué velocidad se ha usado

Cuatro avisos sobre el modo rápido

• Solo en la API de Anthropic. No está en Amazon Bedrock, Google Cloud ni Microsoft Foundry.
• Tiene su propio límite de peticiones, separado del estándar. Si recibes un 429, o esperas lo que diga la cabecera retry-after o quitas speed y sigues en modo normal.
• Cambiar de velocidad invalida la caché de prompt. Esto importa mucho: si alternas modos sobre el mismo contexto, pierdes el ahorro de la caché y el modo rápido sale todavía más caro de lo que parece.
• No funciona con la API de lotes ni con Priority Tier.

La regla que nos funciona: modo estándar por defecto, y modo rápido solo en las rutas donde hay una persona mirando la pantalla mientras se genera la respuesta.

Paso 4: la caché, que es donde está el dinero de verdad

Antes de tocar el esfuerzo para ahorrar, arregla la caché. Es gratis en calidad y es la palanca que más baja la factura en cualquier aplicación con contexto estable.

La lectura de caché en Opus 5.5 cuesta 0,20 dólares por millón de tokens, veinte veces menos que la entrada normal. Si tu aplicación manda el mismo prompt de sistema y las mismas definiciones de herramientas en cada petición, ese bloque debería viajar cacheado siempre.

respuesta = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    system=[
        {
            "type": "text",
            "text": PROMPT_DE_SISTEMA_LARGO,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": pregunta_variable}],
)

print(respuesta.usage.cache_read_input_tokens)   # si sale 0, la caché no funciona

Las tres reglas de la caché que casi todo el mundo rompe

1. El orden es tools, luego system, luego messages. La caché funciona por prefijo: cualquier byte que cambie invalida todo lo que viene detrás.
2. Lo estable delante, lo volátil detrás. Una marca de tiempo, un identificador de petición o un JSON sin ordenar metidos en el prompt de sistema tiran la caché entera en cada llamada.
3. Comprueba siempre usage.cache_read_input_tokens. Si sale cero en peticiones repetidas, tienes un invalidador silencioso. No hay error, no hay aviso: simplemente pagas veinte veces más.

Hay un máximo de cuatro puntos de corte de caché por petición, y el prefijo mínimo que se puede cachear depende del modelo: por debajo de ese umbral la caché no se crea y tampoco te lo dice nadie.

Paso 5: poner un techo a las tareas largas

Si estás montando un agente que encadena muchos pasos, hay una herramienta específica que conviene conocer: el presupuesto de tarea. No es lo mismo que max_tokens.

max_tokens es un tope por respuesta que el modelo no ve: cuando lo alcanza, se le corta a media frase. El presupuesto de tarea, en cambio, le dice al modelo cuánto tiene para todo el trabajo, de modo que se dosifique y termine de forma ordenada en lugar de quedarse a medias.

with client.beta.messages.stream(
    model="claude-opus-5-5",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 64000},
    },
    betas=["task-budgets-2026-03-13"],
    messages=[{"role": "user", "content": "..."}],
    tools=[...],
) as stream:
    respuesta = stream.get_final_message()

El mínimo del presupuesto son 20.000 tokens. Y usa streaming: con un max_tokens tan alto, una petición normal se queda sin tiempo antes de terminar.

Paso 6: cambiar de esfuerzo a mitad de conversación

Hay una trampa que aparece en cuanto tienes conversaciones largas: cambiar el effort de primer nivel a mitad de una conversación invalida la caché de los mensajes. Es decir, ahorras en razonamiento y lo pierdes en entrada.

La forma correcta de hacerlo es con un mensaje de sistema a mitad de conversación, que se añade al array de messages en vez de tocar el campo system de arriba. Eso preserva el prefijo cacheado. Para el caso concreto de cambiar solo el esfuerzo, existe una variante con contenido vacío:

mensajes.append({
    "role": "system",
    "content": [],
    "output_config": {"effort": "max"},
})

Este mensaje de solo esfuerzo está exento de las reglas de colocación que aplican a los mensajes de sistema con texto, así que puede ir en cualquier posición del array. Va en beta (mid-conversation-output-config-2026-07-01).

El patrón útil: llevar toda la conversación en medium y subir a max solo en el turno donde el usuario pide algo difícil, sin pagar el coste de reconstruir la caché entera.

Paso 7: manejar el rechazo sin romper la aplicación

Opus 5.5 amplía sus clasificadores de seguridad: a la categoría de ciberseguridad se suman biología y extracción de razonamiento. Cuando uno de ellos actúa, la petición no falla con un error HTTP: devuelve un 200 perfectamente normal con stop_reason igual a refusal.

Eso significa que el código que lee directamente respuesta.content[0].text sin comprobar antes el motivo de parada puede explotar con un índice fuera de rango, o peor, devolver algo vacío al usuario sin explicación.

if respuesta.stop_reason == "refusal":
    categoria = respuesta.stop_details.category
    registrar(f"Petición rechazada por el clasificador: {categoria}")
    return MENSAJE_PARA_EL_USUARIO

texto = respuesta.content[0].text

Ojo con stop_details: solo está relleno cuando el motivo es refusal. En cualquier otro caso vale None, así que hay que comprobar el motivo antes de leerlo.

Si tu aplicación no puede permitirse un rechazo en producción, existe un parámetro de respaldo en servidor que enruta automáticamente a otro modelo según la categoría del rechazo. Conviene activarlo desde el principio en cualquier servicio de cara al público.

Cuándo es obligatorio el streaming

Tres situaciones en las que una petición normal se queda sin tiempo y hay que usar client.messages.stream(...):

• Cuando max_tokens es alto. Opus 5.5 admite hasta 128.000 tokens de salida, pero con cifras así el SDK exige streaming: una petición sin él choca con el tiempo máximo de la conexión.
• Cuando usas presupuestos de tarea, que por definición implican trabajos largos.
• Cuando hay entrada muy larga. El modelo tiene una ventana de contexto de un millón de tokens; procesarla entera lleva su tiempo.

Si no necesitas ir mostrando la respuesta según se genera, el SDK tiene un atajo cómodo: abrir el flujo y llamar a get_final_message() al terminar, que devuelve el mensaje completo como si fuera una petición normal.

Un detalle sobre el razonamiento visible

Por defecto, los bloques de pensamiento llegan vacíos: el modelo piensa y se te factura igual, pero no ves nada. Si estás construyendo una interfaz donde el usuario espera, ese silencio se percibe como una pausa larga antes de que aparezca nada. Se arregla pidiendo el resumen del razonamiento:

thinking={"type": "adaptive", "display": "summarized"}

El ajuste solo cambia lo que se muestra, no lo que se piensa ni lo que se paga. La cadena de razonamiento en bruto no se expone nunca, en ningún modelo.

Cuatro cambios que rompen el código que venía de Opus 5

Todos devuelven error 400, así que aparecen en cuanto pruebas. Conviene conocerlos antes de migrar.

1. El pensamiento no se puede desactivar

Tanto thinking={"type": "disabled"} como budget_tokens devuelven 400 en cualquier nivel de esfuerzo. En Opus 5 se podía desactivar hasta esfuerzo high; aquí no. Si tu código lo apagaba para ahorrar, sustitúyelo por effort="low", que consigue el mismo objetivo sin romper nada.

2. No se puede forzar el uso de una herramienta

tool_choice={"type": "any"} y tool_choice={"type": "tool", "name": "..."} devuelven 400. Las alternativas, en orden de preferencia:

• Si forzabas la llamada solo para recibir JSON, usa salidas estructuradas con output_config.format.
• Si necesitas que llame a una herramienta concreta, deja tool_choice={"type": "auto"}, nombra la herramienta en el prompt y pon strict: True en su definición para que los argumentos validen contra el esquema.

tool_choice={"type": "none"} sigue funcionando igual.

3. Los bloques de pensamiento van atados al modelo

Opus 5.5 aplica pensamiento preservado: sus bloques de razonamiento solo los lee él mismo dentro de la misma conversación. Si tienes un mecanismo de respaldo que cae a Opus 5, ese modelo se ejecutará sin ellos. Y si tu sistema reescribe el historial —compactación casera, borrado de turnos antiguos—, hay una comprobación de edición de historial que puede rechazar la petición. La regla segura: que tu bucle solo añada mensajes, nunca modifique los anteriores.

4. El uso del ordenador cambia de conjunto de herramientas

Solo funciona con computer_toolset_20260801. El anterior computer_20251124 devuelve 400.

Cómo medir antes de decidir

Todo lo anterior son opciones; la decisión sale de medir tu tráfico, no el de nadie más. Un procedimiento corto que funciona:

1. Guarda cincuenta peticiones reales de la ruta que quieres ajustar. No ejemplos inventados: peticiones que hayan pasado por tu aplicación.
2. Define qué es una respuesta buena antes de ejecutar nada. Aunque sea una lista de cinco criterios revisados a mano, tiene que existir antes.
3. Ejecuta el conjunto con dos niveles de esfuerzo y apunta usage.input_tokens, usage.output_tokens y usage.cache_read_input_tokens de cada llamada.
4. Compara coste por tarea terminada, no por petición. Una petición barata que necesita tres intentos no es barata.
5. Quédate con el nivel más bajo que mantenga la calidad y vuelve a medirlo cuando cambies el prompt.

Para contar tokens de un texto antes de mandarlo, usa el endpoint de conteo del propio SDK (client.messages.count_tokens). Las bibliotecas de otros proveedores dan cifras equivocadas porque el tokenizador es distinto.

Una receta completa para empezar

Si quieres un punto de partida sensato sin pensar mucho, esto es lo que montaríamos para una aplicación nueva:

import anthropic

client = anthropic.Anthropic()

SISTEMA = [
    {
        "type": "text",
        "text": PROMPT_DE_SISTEMA,          # estable entre peticiones
        "cache_control": {"type": "ephemeral"},
    }
]

def preguntar(texto, esfuerzo="medium", rapido=False):
    parametros = dict(
        model="claude-opus-5-5",
        max_tokens=16000,
        system=SISTEMA,
        output_config={"effort": esfuerzo},
        messages=[{"role": "user", "content": texto}],
    )
    if rapido:
        return client.beta.messages.create(
            **parametros, speed="fast", betas=["fast-mode-2026-02-01"]
        )
    return client.messages.create(**parametros)

Con eso tienes caché activa desde el principio, esfuerzo explícito en vez de heredado y el modo rápido disponible cuando lo pidas, sin que se active por descuido. A partir de ahí, ajusta con lo que midas.

Lecturas relacionadas

• Claude Opus 5.5: benchmarks, precio y qué cambia frente a Opus 5
• Cómo crear tu primer agente con la API de Claude y MCP en Python
• Claude Agent SDK en Python: crea agentes autónomos paso a paso
• Claude Code: tutorial completo para programar desde la terminal
• High Reasoning Mode de Claude Opus 5: tutorial paso a paso
• Anthropic abre oficina en Madrid

El equipo que acompaña este flujo de trabajo

Nada de esto necesita una máquina potente para hablar con la API, pero sí para lo que haces alrededor: ejecutar las pruebas, levantar contenedores y tener abiertas tres ventanas de terminal. Estas son las piezas que más se notan; el precio, en Amazon, que cambia cada semana.

Lo primero que se queda corto es la memoria. Pasar a 64 GB de DDR5 es la mejora más rentable de una máquina de desarrollo: Crucial Pro DDR5 64 GB a 6000 MHz, ver precio actual en Amazon. Detrás va el disco, que en un flujo de compilación constante sufre más que jugando: Samsung 990 EVO Plus de 2 TB, ver disponibilidad en Amazon.

Para la pantalla, un panel 4K de 27 pulgadas con USB-C deja sitio a dos terminales y el navegador con un solo cable: Dell S2725QC, ver precio actual en Amazon. Y si escribes mucho, un teclado mecánico Redragon K673 Pro con distribución española, ver disponibilidad en Amazon cuesta poco y se nota el primer día. Las horas sentado las arregla una silla ergonómica con respaldo adaptativo, ver precio actual en Amazon.

Si además ejecutas modelos abiertos en local para las tareas que no compensa enviar a la nube, manda la VRAM: MSI GeForce RTX 5060 Ti de 16 GB, ver disponibilidad en Amazon es el escalón de entrada, y un MINISFORUM MS-S1 MAX con 128 GB de memoria unificada, ver precio actual en Amazon, la alternativa silenciosa. Lo desglosamos en la guía de modelos de IA local según la VRAM.

Para la teoría detrás de todo esto, Machine Learning con PyTorch y Scikit-Learn, ver disponibilidad en Amazon sigue siendo la referencia en español.