Inicio / La API de Claude para quienes construyen

Pasar a Opus 5.5 sin romper tu código

Pasar de Claude Opus 5 a Claude Opus 5.5 no se resume en cambiar el identificador: cuatro ajustes antiguos devuelven ahora un error 400, y las notas escritas entre dos llamadas a herramientas llegan vacías mientras el código no configure thinking.display.

Claude Opus 5.5, anunciado el 22 de septiembre de 2026, se llama claude-opus-5-5 en la API. La página oficial de sus novedades recoge cuatro cambios que rompen el código que ya funciona con Claude Opus 5, y un quinto cambio que no hace fallar ninguna petición pero modifica la forma de la respuesta. Un código que solo cambia el identificador se expone a los cinco.

Cuatro peticiones que la API rechaza

• La reflexión ya no se puede desactivar. Un campo thinking de tipo disabled, como un presupuesto manual de tipo enabled con budget_tokens, devuelve un error 400. El campo se omite, o toma el tipo adaptive, y la profundidad se regula con output_config.effort.
• El forzado de herramienta desaparece. Un tool_choice de tipo any o tool devuelve un error 400, incluso en el punto de acceso que cuenta los tokens. Quedan auto, el valor por defecto, y none.
• Un bloque de reflexión está ligado a su modelo y a la conversación: en las cuentas creadas a partir del 31 de agosto de 2026, reenviarlo tras una modificación del prompt de sistema, de las herramientas o de un mensaje anterior devuelve un error 400.
• En la API de Claude y en Google Cloud, la herramienta computer_20251124 se rechaza en favor del conjunto de herramientas computer_toolset_20260801.

Para sustituir el forzado, la documentación aconseja mantener auto y poner strict: true en la herramienta. Este ajuste restringe los argumentos: cuando Claude llama a la herramienta, su entrada respeta el esquema declarado. No decide que la llamada vaya a producirse. Para eso, el mensaje dice con todas las letras cuándo se aplica la herramienta. El esquema debe ser completo, y cada objeto lleva en él additionalProperties: false. Esta es una petición aceptada por Claude Opus 5 y rechazada por Claude Opus 5.5:

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "thinking": { "type": "disabled" },
  "tools": [{
    "name": "buscar_cliente",
    "description": "Recupera la ficha de un cliente a partir de su número",
    "input_schema": {
      "type": "object",
      "properties": {
        "numero": { "type": "string" }
      },
      "required": ["numero"],
      "additionalProperties": false
    }
  }],
  "tool_choice": { "type": "tool", "name": "buscar_cliente" },
  "messages": [{ "role": "user", "content": "Encuentra la ficha del cliente 4021" }]
}

La misma petición corregida para Claude Opus 5.5:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "output_config": { "effort": "low" },
  "tools": [{
    "name": "buscar_cliente",
    "description": "Recupera la ficha de un cliente a partir de su número",
    "input_schema": {
      "type": "object",
      "properties": {
        "numero": { "type": "string" }
      },
      "required": ["numero"],
      "additionalProperties": false
    },
    "strict": true
  }],
  "tool_choice": { "type": "auto" },
  "messages": [{ "role": "user", "content": "Encuentra la ficha del cliente 4021. Usa la herramienta buscar_cliente." }]
}

El cambio que no devuelve ningún error

Entre dos llamadas a herramientas, Claude Opus 5 escribía notas cortas en bloques de tipo text. Claude Opus 5.5 las coloca en bloques de tipo thinking, y con el ajuste por defecto, display: "omitted", su campo thinking llega vacío. Una interfaz que mostraba esas notas se queda callada, sin el menor error. Clasificar los bloques por su campo type evita tomar un bloque de reflexión por la respuesta, pero no devuelve el texto: hace falta además configurar thinking.display. El valor "updates", en beta bajo la cabecera thinking-display-updates-2026-08-18, devuelve solo las notas; "summarized" les mezcla el resumen completo del razonamiento, sin distinción posible entre ambos.

# petición: "thinking": {"type": "adaptive", "display": "updates"}, cabecera beta thinking-display-updates-2026-08-18
for bloque in respuesta.content:
    if bloque.type == "thinking" and bloque.thinking:
        mostrar(bloque.thinking)  # nota escrita entre dos llamadas a herramientas
    elif bloque.type == "text":
        mostrar(bloque.text)

Esta clasificación solo sirve para la visualización. En un bucle de herramientas, el mensaje del asistente se reenvía tal cual, bloques de reflexión incluidos, aunque estén vacíos: la API rechaza un bloque modificado, desplazado o retirado.

El esfuerzo aplicado cuando falta el campo baja un escalón, como muestra la tabla. La tarifa por token baja, como cifra la figura, pero la reflexión siempre activa se factura en tokens de salida incluso cuando su texto no se devuelve: el compromiso de la lección sobre la elección de un modelo se recalcula con el esfuerzo elegido. La declaración de herramienta de la lección sobre las herramientas es la primera afectada, y una consigna escrita para el comportamiento antiguo envejece, como muestra la lección sobre las consignas que envejecen.