¿Cómo usar la API de Claude Opus 5?

Claude Opus 5 se lanzó el 24 de julio de 2026 y Anthropic lo recomienda como primera opción si no está seguro de qué modelo usar. El ID exacto del modelo para la API es claude-opus-5, sin sufijo de fecha.

Prueba Apidog hoy

Esta guía cubre el flujo completo: crear una clave API, enviar su primera solicitud, usar streaming, implementar herramientas, controlar el pensamiento adaptativo con effort y revisar usage para validar la caché de prompts. Todas las solicitudes usan HTTP y JSON, por lo que puede construirlas y depurarlas en Apidog antes de integrarlas en su aplicación.

Si migra desde Opus 4.8, revise también la guía completa de migración de Opus 4.8 a Opus 5.

Antes de su primera llamada: dos cambios disruptivos

1. El pensamiento está activado por defecto

En Opus 4.8, una solicitud sin el campo thinking se ejecutaba sin razonamiento. En Opus 5, la misma solicitud usa pensamiento adaptativo.

max_tokens sigue siendo un límite estricto para los tokens de pensamiento más los tokens de salida. Si su integración de Opus 4.8 tenía un límite ajustado a la longitud esperada de la respuesta, Opus 5 puede truncarla.

Acción recomendada: aumente max_tokens y compruebe stop_reason en sus pruebas.

2. Desactivar el pensamiento limita el esfuerzo

Esta combinación devuelve 400:

{
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "xhigh"}
}

Cuando desactiva el pensamiento, el esfuerzo máximo permitido es high.

Elija una de estas opciones:

• Mantenga el pensamiento activado y reduzca effort para controlar costes.
• Desactive el pensamiento y limite effort a high.

Anthropic recomienda la primera opción. Con el pensamiento desactivado, Opus 5 puede escribir llamadas a herramientas como texto plano en lugar de ejecutarlas, y ocasionalmente puede filtrar etiquetas <thinking> en la salida visible.

Ambos cambios están documentados en la guía de migración de modelos de Anthropic.

Paso 1: Obtener una clave API

Inicie sesión en la Plataforma de Desarrolladores de Claude, abra las claves API de su organización y cree una clave nueva. Cópiela al crearla: no podrá verla otra vez.

Guárdela como variable de entorno:

export ANTHROPIC_API_KEY="sk-ant-..."

No incruste la clave directamente en el código ni en colecciones compartidas.

Si prueba en una interfaz gráfica, cree un entorno con una variable llamada ANTHROPIC_API_KEY. En Apidog puede usarla en los encabezados como:

{{ANTHROPIC_API_KEY}}

Así puede compartir solicitudes con el equipo sin exportar secretos.

También necesita añadir créditos de facturación antes de enviar solicitudes. Opus 5 cuesta $5 por millón de tokens de entrada y $25 por millón de tokens de salida, igual que Opus 4.8. Consulte el desglose completo de precios para tarifas de caché, lotes y modo rápido.

Paso 2: Enviar su primera solicitud

Use el endpoint:

POST https://api.anthropic.com/v1/messages

Incluya estos encabezados:

• x-api-key
• anthropic-version
• content-type

Ejemplo con curl:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "Explain the difference between a 429 and a 529 from an API perspective."
      }
    ]
  }'

Use 4096 como punto de partida, no 1024. El pensamiento y la salida visible comparten el mismo presupuesto de max_tokens.

Ejemplo equivalente con el SDK oficial de Python:

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Explain the difference between a 429 and a 529 from an API perspective.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

No asuma que content[0].text contiene la respuesta. Con el pensamiento activado, message.content puede contener primero un bloque thinking y después un bloque text.

Opus 5 ofrece:

• Ventana de contexto predeterminada y máxima de 1M de tokens.
• Máximo de 128k tokens de salida en la API de Mensajes.
• Fecha de corte de conocimiento de mayo de 2026.

Revise la descripción general de modelos y el explicador de Opus 5 para más detalles.

Paso 3: Trabajar con pensamiento adaptativo

El pensamiento adaptativo permite que el modelo decida cuánto razonamiento interno necesita una solicitud. No configure un presupuesto de pensamiento manualmente; controle el comportamiento mediante output_config.effort.

Implemente estas reglas:

• Procese bloques por tipo. Use block.type == "text" para la salida visible y block.type == "thinking" si necesita registrar razonamiento.
• Conserve el contenido completo del asistente. En conversaciones de múltiples turnos o flujos con herramientas, reenvíe message.content completo.
• Presupueste ambos tipos de tokens. Pensamiento y respuesta comparten max_tokens.
• Compruebe truncamientos. Si recibe stop_reason: "max_tokens", incremente el límite.

Para desactivar el pensamiento:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "high"},
  "messages": [
    {
      "role": "user",
      "content": "Return only the HTTP status code."
    }
  ]
}

No cambie high por xhigh o max: la API devolverá 400.

Paso 4: Controlar el coste con output_config.effort

El parámetro effort se configura dentro de output_config:

{
  "output_config": {
    "effort": "high"
  }
}

Valores permitidos:

• low
• medium
• high
• xhigh
• max

El valor predeterminado es high.

Ejemplo para una tarea de código con mayor esfuerzo:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-5",
    "max_tokens": 65536,
    "output_config": {"effort": "xhigh"},
    "messages": [
      {
        "role": "user",
        "content": "Refactor this handler to stream responses and keep backpressure."
      }
    ]
  }'

Tenga en cuenta estas reglas:

1. No reutilice directamente la configuración de Opus 4.8. Los niveles fueron recalibrados. low y medium son más potentes en Opus 5 que en modelos Opus anteriores.
2. Evalúe con sus propios casos. Envíe el mismo conjunto de prompts usando varios niveles de esfuerzo y compare calidad, latencia y consumo.
3. Use xhigh como punto de partida para código y agentes. Para turnos largos de agente, 65536 es un límite inicial razonable.
4. Menor esfuerzo no significa respuestas más cortas. Reduce el razonamiento interno, no necesariamente la longitud visible. Pida una respuesta breve explícitamente en el prompt.

Consulte la guía detallada del parámetro de esfuerzo para una metodología de evaluación completa.

Paso 5: Transmitir la respuesta con streaming

Añada "stream": true para recibir eventos enviados por el servidor (SSE) en lugar de una única respuesta JSON.

with client.messages.stream(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Draft a retry policy for a flaky upstream.",
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final = stream.get_final_message()
    print("\n\nusage:", final.usage)

La secuencia SSE sigue este orden:

message_start
content_block_start
content_block_delta
content_block_stop
message_delta
message_stop

Con pensamiento activado, normalmente recibirá:

1. Un bloque de pensamiento con deltas thinking_delta.
2. Un bloque de texto con deltas text_delta.

No renderice todos los deltas en el mismo búfer de interfaz. Si lo hace, mostrará el razonamiento del modelo a sus usuarios. Enrute los bloques thinking y text por separado desde el principio.

Un cliente como Apidog permite inspeccionar los eventos SSE mientras llegan, verificar límites de bloques y validar el parser antes de implementar el controlador en producción.

Paso 6: Añadir uso de herramientas

Defina las herramientas en el arreglo tools. Cuando el modelo necesite una herramienta, devolverá:

{
  "stop_reason": "tool_use"
}

Además, message.content incluirá un bloque tool_use. Ejecute la herramienta y reenvíe el resultado como un bloque tool_result.

tools = [
    {
        "name": "get_order_status",
        "description": "Look up the current status of a customer order by ID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "The order ID, e.g. A-10293",
                }
            },
            "required": ["order_id"],
        },
    }
]

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "What's the status of order A-10293?",
        }
    ],
)

if message.stop_reason == "tool_use":
    call = next(block for block in message.content if block.type == "tool_use")
    result = get_order_status(**call.input)

    follow_up = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        tools=tools,
        messages=[
            {
                "role": "user",
                "content": "What's the status of order A-10293?",
            },
            {
                "role": "assistant",
                "content": message.content,
            },
            {
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": call.id,
                        "content": result,
                    }
                ],
            },
        ],
    )

La línea importante es esta:

{"role": "assistant", "content": message.content}

No reconstruya manualmente el turno del asistente. Reenviar message.content conserva los bloques de pensamiento y evita degradar el bucle del agente.

Detalles relevantes para agentes:

• El overhead del prompt del sistema para herramientas es de 286 tokens con tool_choice configurado en auto o none.
• Puede usar el encabezado beta mid-conversation-tool-changes-2026-07-01 para añadir o eliminar herramientas entre turnos sin invalidar la caché del prompt.
• Opus 5 delega a subagentes con más facilidad que Opus 4.8. Si necesita controlar costes, limite esa conducta explícitamente en el prompt de sistema.

Paso 7: Validar aciertos de caché con usage

Cada respuesta incluye un objeto usage:

{
  "usage": {
    "input_tokens": 84,
    "cache_creation_input_tokens": 6421,
    "cache_read_input_tokens": 0,
    "output_tokens": 913
  }
}

Marque contenido estable con cache_control para almacenarlo en caché:

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions and reference material>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Question one."
    }
  ]
}

Compruebe el comportamiento en dos llamadas consecutivas con el mismo prefijo:

Llamada	cache_creation_input_tokens	cache_read_input_tokens
Primera	Mayor que 0	0
Segunda	Normalmente 0	Mayor que 0

Si los valores no cambian como espera, revise lo siguiente:

• El prefijo debe ser idéntico byte a byte.
• El contenido debe superar el mínimo de caché.
• No debe modificar instrucciones, herramientas o contenido estable entre llamadas.

En Opus 5, el mínimo para caché de prompts es de 512 tokens, frente a 1.024 en Opus 4.8. Las lecturas de caché cuestan $0.50 por millón de tokens, frente a $5 por millón para la entrada base.

Añada una aserción sobre cache_read_input_tokens en su suite de pruebas. Así, una edición que invalide la caché se detectará antes de convertirse en un aumento de factura. Consulte también esta guía para reducir su factura de la API de Claude.

Pruebe y depure el flujo completo en Apidog

Todo el flujo es HTTP: encabezados de autenticación, cuerpo JSON, streaming SSE y respuestas que puede validar con aserciones. Apidog permite enviar, inspeccionar y probar estas solicitudes sin cambiar cómo Anthropic ejecuta la inferencia.

Apidog no ejecuta el modelo ni enruta modelos: la inferencia sigue ocurriendo en Anthropic.

Configure una colección reutilizable:

1. Cree la solicitud. Use POST https://api.anthropic.com/v1/messages, los tres encabezados requeridos y una variable de entorno para la clave.
2. Guárdela en una colección. El equipo reutiliza una solicitud validada en lugar de reconstruirla desde cero.
3. Duplique la solicitud por nivel de esfuerzo. Cree variantes con low, medium, high y xhigh.
4. Ejecute el mismo prompt en cada variante. Compare salida, latencia y uso de tokens.
5. Active streaming. Añada "stream": true e inspeccione eventos SSE para confirmar que los bloques thinking y text se manejan por separado.
6. Revise las llamadas a herramientas. Si recibe stop_reason: "tool_use", inspeccione el objeto input generado por el modelo y ajuste su input_schema si es demasiado permisivo.
7. Añada aserciones. Compruebe que stop_reason no sea max_tokens y que cache_read_input_tokens sea mayor que cero en solicitudes repetidas.

Descargue Apidog para seguir este flujo. La misma colección puede reutilizarse con Sonnet 5 o con sus solicitudes existentes de Opus 4.8.

Errores y trampas que encontrará

• 400 al combinar thinking: disabled con xhigh o max. Reduzca el esfuerzo a high o reactive el pensamiento.
• 400 con parámetros de muestreo. temperature, top_p y top_k con valores no predeterminados devuelven 400, igual que en Opus 4.8. Controle el formato mediante el prompt de sistema.
• Respuestas truncadas. Si recibe stop_reason: "max_tokens", el presupuesto fue consumido por pensamiento y salida. Aumente max_tokens.
• El nivel de prioridad no es compatible con Opus 5. Opus 4.8 sí lo mantiene. Evalúe este impacto antes de migrar tráfico empresarial.
• Los mensajes de sistema a mitad de conversación funcionan. Opus 5 acepta entradas role: "system" dentro de messages, donde Opus 4.8 devolvía 400.
• Sobre-verificación. Opus 5 ya verifica su trabajo sin que se lo pida. Elimine instrucciones heredadas como “verifique su respuesta antes de responder” si no aportan valor, porque consumen tokens de pensamiento.

El límite honesto

Opus 5 no es el modelo más capaz de la pila de Claude. Anthropic mantiene a Fable 5 como el modelo “más capaz lanzado ampliamente”, con un precio de $10 por millón de tokens de entrada y $50 por millón de tokens de salida.

Opus 5 también está por detrás de Mythos 5 en explotación de ciberseguridad e investigación de biología autónoma, según Anthropic.

Las cifras de lanzamiento —aproximadamente el doble de Opus 4.8 en Frontier-Bench v0.1, aproximadamente tres veces el siguiente mejor modelo en ARC-AGI 3 y dentro del 0,5 % de Fable 5 en CursorBench 3.2— son resultados proporcionados por Anthropic y no habían sido reproducidos de forma independiente al 25 de julio de 2026.

Úselos como punto de partida, pero ejecute sus propias evaluaciones. Consulte la comparación de Opus 5 frente a Fable 5 y la publicación de lanzamiento de Anthropic.

Preguntas frecuentes

¿Cuál es el ID de modelo para Claude Opus 5?

claude-opus-5, exactamente y sin sufijo de fecha.

En Amazon Bedrock es anthropic.claude-opus-5. Google Cloud y la Plataforma Claude en AWS usan el ID de primera parte.

¿Por qué una solicitud de Opus 4.8 ahora se trunca en Opus 5?

Porque el pensamiento está activado por defecto. max_tokens limita pensamiento y respuesta juntos. Aumente el valor y compruebe si recibe:

{
  "stop_reason": "max_tokens"
}

¿Por qué recibo un 400 al desactivar pensamiento?

Probablemente combinó:

{
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "xhigh"}
}

Con pensamiento desactivado, limite effort a high. Alternativamente, active el pensamiento y reduzca el esfuerzo.

¿Necesito un encabezado beta para usar 1M de contexto?

No. Opus 5 ofrece 1M de tokens como contexto predeterminado y máximo, sin encabezado beta ni prima de contexto largo.

Para llegar a 300k de salida en la API por lotes, necesita el encabezado beta output-300k-2026-03-24. La API de Mensajes limita la salida a 128k.

¿Puedo reutilizar la configuración de esfuerzo de Opus 4.8?

No directamente. Anthropic recalibró los niveles y low y medium son más capaces en Opus 5. Ejecute un nuevo barrido de evaluación con sus propios prompts y métricas.

¿Apidog ejecuta el modelo?

No. Apidog envía, inspecciona y prueba solicitudes HTTP. Anthropic ejecuta la inferencia. Apidog ayuda a manejar claves, streaming, llamadas a herramientas y aserciones sobre las respuestas.