Blog

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

Guía paso a paso de la API de Claude Opus 5: obtén una clave, envía tu primera llamada con el ID del modelo claude-opus-5, transmite las respuestas, añade uso de herramientas, ajusta el esfuerzo y lee el uso para los aciertos de caché.

Ashley Innocent

Ashley Innocent

25 July 2026

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

Apidog para empresas

Despliegue local

SSO & RBAC

Conforme con SOC 2

Explorar Apidog Enterprise

Claude Opus 5 se lanzó el 24 de julio de 2026, y Anthropic ahora lo indica a los desarrolladores como primera opción: la documentación dice que si no estás seguro de qué modelo usar, comiences con Claude Opus 5. El ID del modelo API es la cadena exacta claude-opus-5, sin sufijo de fecha.

Esta guía recorre todo el camino: obtener una clave, enviar una primera solicitud, streaming, uso de herramientas, pensamiento adaptativo, el parámetro effort y la lectura del objeto usage para confirmar que su caché de prompts está funcionando. Cada solicitud aquí es HTTP simple con JSON de entrada y JSON de salida, por lo que puede construirla y depurarla en Apidog antes de integrarla en el código de su aplicación.

botón

Dos cambios con respecto a Opus 4.8 le afectarán en la primera llamada, por lo que se presentan antes que cualquier otra cosa. Si está migrando un servicio existente en lugar de comenzar de cero, lea la guía completa de migración de Opus 4.8 a Opus 5 junto con esta.

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 pensar en absoluto. En Opus 5, esa misma solicitud se ejecuta con pensamiento adaptativo. max_tokens sigue siendo un límite estricto para los tokens de pensamiento más los tokens de respuesta juntos, por lo que un cuerpo de solicitud que copió de una integración 4.8 funcional ahora puede truncarse a mitad de la respuesta. Si su max_tokens estaba ajustado precisamente a la longitud de salida esperada, auméntelo.

2. Desactivar el pensamiento limita su nivel de esfuerzo. Enviar thinking: {"type": "disabled"} junto con un esfuerzo de xhigh o max devuelve un 400. Anthropic aplica esto por solicitud, por lo que falla inmediatamente en lugar de degradarse silenciosamente. La solución es elegir una: mantener el pensamiento activado y reducir el esfuerzo para controlar el costo, o mantener el pensamiento desactivado y limitar el esfuerzo a high.

El propio consejo de Anthropic es la primera opción. Con el pensamiento desactivado, Opus 5 ocasionalmente escribe las llamadas a herramientas como texto plano (nunca se ejecutan, y el texto filtrado contamina turnos posteriores en un bucle de agente) y a veces filtra etiquetas <thinking> en la salida visible. Mantener el pensamiento activado y reducir el esfuerzo evita ambos problemas.

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 la sección de claves API en la configuración de su organización y cree una clave. Cópiela una vez; no podrá leerla de nuevo más tarde.

Guárdela en una variable de entorno en lugar de pegarla directamente en el código:

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

Si está probando en un cliente GUI, coloque la clave también en una variable de entorno allí. En Apidog, esto significa crear un entorno (Local, Staging, Production) con una variable ANTHROPIC_API_KEY, y luego hacer referencia a {{ANTHROPIC_API_KEY}} en el encabezado. Sus solicitudes guardadas seguirán siendo compartibles con el equipo y el secreto nunca terminará en una exportación de colección.

También necesita añadir créditos de facturación antes de que las solicitudes tengan éxito. Las tarifas para Opus 5 son de $5 por millón de tokens de entrada y $25 por millón de tokens de salida, las mismas que Opus 4.8, y el desglose completo de precios cubre tarifas de caché, lotes y modo rápido.

Paso 2: Enviar su primera solicitud

El endpoint es POST https://api.anthropic.com/v1/messages. Tres encabezados son importantes: su clave, la versión de la API y el tipo de contenido.

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."}
    ]
  }'

Observe el valor de max_tokens. 4096 es un aumento deliberado con respecto a los 1024 que ve en la mayoría de los fragmentos de inicio, porque los tokens de pensamiento ahora provienen del mismo presupuesto.

El equivalente en Python a través del SDK oficial:

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)

Ese bucle sobre message.content no es una decoración. El content de la respuesta es una matriz de bloques tipificados, y con el pensamiento activado ahora verá un bloque thinking antes del bloque text. El código que asumía que content[0].text era la respuesta, se rompe en Opus 5. Esta es la falla de actualización más común, y es fácil pasarla por alto porque la solicitud aún devuelve un 200.

Algunas especificaciones que vale la pena tener en cuenta mientras construye: Opus 5 tiene una ventana de contexto de 1M de tokens tanto como predeterminada como máxima (sin encabezado beta, sin prima de precio por contexto largo), una salida máxima de 128k en la API de Mensajes y una fecha de corte de conocimiento de mayo de 2026. La descripción general de los modelos tiene la tabla completa, y nuestro explicador de Opus 5 cubre el resto de la hoja de especificaciones.

Paso 3: Trabajar con el pensamiento adaptativo

El pensamiento adaptativo significa que el modelo decide cuánto razonamiento interno merece una solicitud. Usted no establece un presupuesto de tokens. Lo dirige con el esfuerzo, que se cubre en el siguiente paso.

Lo que necesita manejar en el código:

Para desactivar el pensamiento por completo:

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

El esfuerzo está limitado a high en esa solicitud a propósito. Auméntelo a xhigh y obtendrá el error 400 descrito anteriormente.

Paso 4: Controlar el costo con output_config.effort

El campo effort se encuentra dentro de output_config y acepta low, medium, high, xhigh o max. Su valor predeterminado es high. Este es el parámetro que la cobertura general describió como un interruptor entre costo y capacidad; en la API es una cadena en el cuerpo de su solicitud.

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."}
    ]
  }'

Tres cosas que debe saber antes de ajustarlo.

Paso 5: Transmitir la respuesta (Streaming)

Añada "stream": true y el endpoint devolverá eventos enviados por el servidor en lugar de un único cuerpo 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 sin procesar es message_start, luego content_block_start / content_block_delta / content_block_stop por cada bloque, luego message_delta que contiene stop_reason y el recuento final de tokens de salida, y finalmente message_stop.

Con el pensamiento activado, obtendrá dos bloques de contenido en streaming en orden: un bloque de pensamiento cuyas deltas llegan como thinking_delta, y luego el bloque de texto con text_delta. Una interfaz de usuario que renderice cada delta en el mismo búfer imprimirá el razonamiento del modelo a sus usuarios. Enrútelos por separado desde el principio.

El streaming también es donde un cliente GUI gana su lugar, porque leer SSE en bruto en una terminal es miserable. Apidog renderiza el flujo de eventos a medida que llega, para que pueda observar los límites de los bloques y confirmar sus suposiciones de análisis antes de escribir una sola línea de código de controlador.

Paso 6: Añadir uso de herramientas

Las definiciones de herramientas van en una matriz tools. El modelo responde con stop_reason: "tool_use" y un bloque de contenido tool_use; usted ejecuta la herramienta y envía el resultado de vuelta como un bloque tool_result en un nuevo mensaje de usuario.

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(b for b in message.content if b.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}
            ]},
        ],
    )

Pasar message.content directamente como el turno del asistente es lo que conserva el bloque de pensamiento. No reconstruya ese turno a mano.

Dos detalles de Opus 5 que importan para los agentes. El overhead del prompt del sistema para el uso de herramientas es menor que en Opus 4.8: 286 tokens con tool_choice configurado en auto o none, frente a 290 en 4.8 y 675 en Opus 4.7. Pequeño por solicitud, pero significativo a lo largo de un millón de turnos de agente. Y hay un encabezado beta, mid-conversation-tool-changes-2026-07-01, que le permite agregar o eliminar herramientas entre turnos sin invalidar la caché del prompt.

Opus 5 también delega a subagentes más fácilmente de lo que lo hacía 4.8. En cargas de trabajo sensibles al costo, defina eso explícitamente en su prompt de sistema en lugar de descubrirlo en la factura.

Paso 7: Leer el objeto de uso para aciertos de caché

Cada respuesta incluye un objeto usage. Es la única forma honesta de confirmar que su caché de prompts está funcionando.

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

Para almacenar un bloque en caché, márquelo con cache_control:

{
  "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."}]
}

Primera llamada: cache_creation_input_tokens es distinto de cero y cache_read_input_tokens es 0. Segunda llamada con el mismo prefijo: esos valores se invierten. Si nunca se invierten, su prefijo no es idéntico byte a byte o está por debajo del mínimo.

Ese mínimo es la buena noticia en Opus 5. El almacenamiento en caché de prompts ahora se activa a los 512 tokens, frente a los 1.024 de Opus 4.8. Los prompts que antes eran demasiado cortos para cachear, ahora se cachean sin ningún cambio en el código, y las lecturas de caché se facturan a $0.50 por millón de tokens frente a una tarifa base de entrada de $5. Afirme sobre cache_read_input_tokens en su suite de pruebas para que una edición de prompt que rompa silenciosamente la caché se muestre como una prueba fallida en lugar de una factura. Para más palancas, consulte nuestra guía sobre cómo reducir su factura de la API de Claude.

Pruebe y depure todo el flujo en Apidog

Todo lo anterior es una solicitud HTTP con encabezados de autenticación, un cuerpo JSON, un flujo SSE y una respuesta contra la que debe afirmar. Apidog es una plataforma de desarrollo de API todo en uno, y este es precisamente el tipo de endpoint que maneja: envía la solicitud, almacena la clave, renderiza el flujo y prueba la respuesta. No ejecuta inferencia ni enruta modelos; la llamada sigue yendo a Anthropic.

Una configuración que se amortiza desde el primer día:

  1. Cree la solicitud. POST https://api.anthropic.com/v1/messages con los tres encabezados, y la clave extraída de una variable de entorno en lugar de pegada en línea.
  2. Guárdela en una colección. Su equipo reutiliza una forma de solicitud conocida y probada en lugar de que cada persona la reconstruya a partir de un fragmento de blog.
  3. Bifúrcela por nivel de esfuerzo. Duplique la solicitud con output_config.effort configurado en low, medium, high y xhigh, envíe el mismo prompt a cada una y compare la calidad de la salida, la latencia y el recuento de tokens lado a lado. Este es el barrido de esfuerzo que Anthropic le pide que ejecute, realizado sin escribir un arnés.
  4. Observe el flujo SSE. Active "stream": true y lea los eventos a medida que llegan para confirmar que maneja los bloques de pensamiento y los bloques de texto por separado.
  5. Inspeccione las cargas útiles de las llamadas a herramientas. Cuando stop_reason vuelve como tool_use, el objeto input exacto que produjo el modelo está ahí mismo, que es como se da cuenta de que su input_schema era demasiado permisivo.
  6. Afirme sobre la respuesta. Agregue verificaciones de que stop_reason no sea max_tokens (su canario de truncamiento) y que cache_read_input_tokens esté por encima de cero en llamadas repetidas (su canario de caché).

Descargue Apidog si desea seguir la guía. El mismo patrón de colección funciona con cualquier modelo de Claude, por lo que puede apuntarlo a Sonnet 5 o a sus solicitudes existentes de Opus 4.8 y comparar el comportamiento.

Errores y trampas que realmente encontrará

El límite honesto

Opus 5 no es la cima de la pila de Claude, y vale la pena decirlo claramente. Fable 5 sigue siendo la designación de Anthropic como el "más capaz lanzado ampliamente", a $10 por millón de entradas y $50 por millón de salidas. Opus 5 también está por detrás de Mythos 5 en explotación de ciberseguridad e investigación de biología autónoma, lo que Anthropic mismo declara.

Las afirmaciones de referencia de lanzamiento (aproximadamente el doble de Opus 4.8 en Frontier-Bench v0.1, aproximadamente 3 veces el siguiente mejor modelo en ARC-AGI 3, dentro del 0.5% de Fable 5 en CursorBench 3.2) son todos números propios de Anthropic y no han sido reproducidos de forma independiente a partir del 25 de julio de 2026. Léalos como resultados proporcionados por el proveedor, y luego ejecute sus propias evaluaciones. La comparación de Opus 5 frente a Fable 5 analiza dónde la diferencia de precio vale la pena y dónde no, y la publicación de lanzamiento de Anthropic es la fuente principal de las afirmaciones mismas.

Preguntas Frecuentes (FAQ)

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar