Cómo usar la API de Claude Opus 4.8

La API de Claude Opus 4.8 se lanzó con el modelo el 28 de mayo de 2026. El ID del modelo es claude-opus-4-8, y funciona con la misma API de Mensajes que ya conoces. Esta guía detalla la configuración completa: cómo obtener una clave, tu primera llamada, el nuevo parámetro effort, el pensamiento adaptativo, la transmisión (streaming), el uso de herramientas y cómo probar todo en Apidog.

Si ya has llamado a algún modelo de Claude antes, la única cadena que cambia es el nombre del modelo. El único concepto nuevo es el control de esfuerzo, y vale la pena dedicar diez minutos a entenderlo porque reemplaza el antiguo patrón de presupuesto de pensamiento. ¿Eres nuevo en la API de Claude? Podrás realizar llamadas operativas a Opus 4.8 en unos diez minutos. Para obtener información sobre el modelo en sí, consulta qué es Claude Opus 4.8.

Lo que obtienes con la API de Opus 4.8

Los números que dan forma a tu integración:

claude-opus-4-8: contexto de entrada de 1M de tokens, salida de 128K de tokens
Mismo endpoint de Mensajes: reemplazo directo para proyectos que ya usan Opus 4.7
Control de effort: cinco niveles de low a max, configurables por solicitud
Pensamiento adaptativo: el modelo decide la profundidad de su razonamiento
Precios estándar: $5 por millón de tokens de entrada, $25 por millón de tokens de salida

Para conocer el cálculo completo de costes y las tarifas en modo rápido, consulta la guía de precios de Opus 4.8. Si aún no tienes un plan de pago, la guía de acceso gratuito cubre tus opciones.

Paso 1: Obtén tu clave de API de Claude

Ve a console.anthropic.com
Inicia sesión o crea una cuenta
Abre Configuración, luego Claves de API
Haz clic en Crear clave, nómbrala y cópiala

Guarda la clave en una variable de entorno para que nunca termine en tu código:

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

Las nuevas cuentas obtienen créditos de prueba para realizar pruebas antes de añadir la facturación. La clave funciona inmediatamente con claude-opus-4-8.

Paso 2: Instala el SDK

Anthropic proporciona SDK oficiales para Python, TypeScript, Go, Java, C#, Ruby y PHP. Elige tu lenguaje:

# Python
pip install anthropic

# Node.js / TypeScript
npm install @anthropic-ai/sdk

Puedes omitir el SDK por completo y llamar al endpoint REST con curl, como se muestra a continuación. El código fuente del SDK de Python es la referencia si necesitas tipos exactos.

Paso 3: Realiza tu primera llamada a Opus 4.8

Python

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Explain the OAuth 2.0 PKCE flow in 3 short paragraphs."}
    ],
)

print(message.content[0].text)

Node.js

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 4096,
  messages: [
    { role: "user", content: "Explain the OAuth 2.0 PKCE flow in 3 short paragraphs." },
  ],
});

console.log(message.content[0].text);

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-4-8",
    "max_tokens": 4096,
    "messages": [
      {"role": "user", "content": "Explain the OAuth 2.0 PKCE flow in 3 short paragraphs."}
    ]
  }'

Ese es el camino feliz. A partir de aquí, puedes añadir las características que necesites.

Control de esfuerzo: el nuevo parámetro

El parámetro effort controla cuántos tokens gasta Opus 4.8 en toda la respuesta: texto, llamadas a herramientas y razonamiento. Reside dentro de output_config y acepta low, medium, high, xhigh y max. El valor predeterminado es high, por lo que omitirlo resultará en un comportamiento high.

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=8192,
    messages=[{"role": "user", "content": "Refactor this 600-line module for testability."}],
    output_config={"effort": "xhigh"},
)

Node:

const message = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 8192,
  messages: [{ role: "user", content: "Refactor this 600-line module for testability." }],
  output_config: { effort: "xhigh" },
});

Cómo elegir, según la documentación de esfuerzo de Anthropic:

Nivel	Úsalo para
`low`	Clasificación, búsquedas rápidas, trabajos de alto volumen, subagentes
`medium`	Trabajo agéntico equilibrado donde el coste importa
`high`	Predeterminado. Razonamiento complejo donde la calidad supera la velocidad
`xhigh`	Codificación y tareas agénticas de largo plazo; el punto de partida recomendado
`max`	Problemas verdaderamente fronterizos donde has medido el margen de mejora

Dos reglas prácticas. Comienza en xhigh para codificación y bucles agénticos. Cuando uses xhigh o max, establece un max_tokens grande (64K es un punto de partida razonable) para que el modelo tenga espacio para pensar y actuar.

Pensamiento adaptativo

Opus 4.8 utiliza el pensamiento adaptativo. Establece thinking: {type: "adaptive"} y el modelo decide cuándo y cuánto razonar. Sin él, las solicitudes se ejecutan sin pensamiento.

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "Find the race condition in this scheduler."}],
)

for block in message.content:
    if block.type == "thinking":
        print("[thinking]", block.thinking[:200])
    elif block.type == "text":
        print(block.text)

Una trampa de migración: el pensamiento extendido manual con budget_tokens no es compatible con Opus 4.8 y devuelve un error 400. Si lo heredaste de Opus 4.5 o anterior, elimina el campo budget_tokens y usa el pensamiento adaptativo con esfuerzo en su lugar.

Respuestas en streaming

El streaming hace que Opus 4.8 se sienta rápido en una interfaz de usuario. El SDK te proporciona una ayuda:

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Write a 5-step guide to writing a REST client in Go."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Node:

const stream = client.messages.stream({
  model: "claude-opus-4-8",
  max_tokens: 4096,
  messages: [{ role: "user", content: "Write a 5-step guide to writing a REST client in Go." }],
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

Para REST puro, añade "stream": true al cuerpo de la solicitud y lee los eventos enviados por el servidor.

Uso de herramientas y llamadas a funciones

Opus 4.8 llama a las herramientas de manera más eficiente que 4.7, y el nivel de effort determina cuántas llamadas realiza. Define una herramienta con un input_schema:

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["city"],
        },
    }
]

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What's the weather in Singapore right now?"}],
)

for block in message.content:
    if block.type == "tool_use":
        print(f"Call: {block.name}")
        print(f"Args: {block.input}")

Ejecutas la herramienta localmente, añades un bloque tool_result y llamas de nuevo para continuar. Un `effort` más bajo hace que Claude agrupe las operaciones en menos llamadas; un `effort` más alto hace que explique su plan primero. Si estás construyendo sistemas multiagente, nuestra guía de agentes gestionados vs Agent SDK cubre las opciones de arquitectura.

Mensajes de sistema a mitad de conversación

Opus 4.8 viene con un cambio en la API de Mensajes: ahora puedes colocar una entrada de sistema en medio del array messages, no solo al principio. Esto te permite inyectar nuevas instrucciones o permisos a mitad de tarea, lo cual es la base de los flujos de trabajo dinámicos de Claude Code. Si estás orquestando subagentes a través de la API, lee la exploración profunda de flujos de trabajo dinámicos para conocer el patrón completo.

Probando tu integración de Opus 4.8 con Apidog

Una llamada al SDK en funcionamiento es el primer paso. Las integraciones de producción deben manejar las partes complicadas: fragmentos transmitidos, validación de llamadas a herramientas, la nueva forma de output_config y bloques de pensamiento adaptativo en la respuesta. Ahí es donde una configuración de prueba real da sus frutos.

Apidog maneja toda la superficie de la API de Mensajes en un solo espacio de trabajo:

Guarda el endpoint como una solicitud: pega https://api.anthropic.com/v1/messages, adjunta tus encabezados x-api-key y anthropic-version, y pulsa Enviar
Repite entre versiones de modelo: cambia claude-opus-4-7 por claude-opus-4-8 en la misma solicitud y compara las salidas
Transmite respuestas en línea: Apidog renderiza los fragmentos transmitidos a medida que llegan, con tiempos por fragmento
Valida la forma de la respuesta: añade aserciones que detecten desviaciones cuando cambies los niveles de effort o alternes el pensamiento
Simula el endpoint: genera una respuesta de Mensajes simulada para que puedas probar el código posterior sin gastar créditos
Crea escenarios de bucle de agente: encadena llamadas con validación de llamadas a herramientas entre pasos

Para empezar, descarga Apidog, crea una solicitud apuntando al endpoint de Mensajes e importa el fragmento de curl anterior. La configuración tarda unos dos minutos. El mismo flujo funciona para la API de Gemini 3.5 y la API de Qwen 3.7 si utilizas más de un proveedor.

Manejo de errores y límites de tasa

El modelo de errores de Claude es consistente. Los códigos importantes:

400 invalid_request_error: cuerpo mal formado, a menudo budget_tokens en Opus 4.8 o un valor effort incorrecto
401 authentication_error: clave de API incorrecta o faltante
403 permission_error: tu clave no puede acceder al modelo
429 rate_limit_error: espera y reintenta
500 api_error: lado del servidor, reintenta con retroceso exponencial
529 overloaded_error: la API está temporalmente sobrecargada, reintenta con retroceso exponencial

Envuelve las llamadas con un bucle de reintento y retroceso exponencial:

import time
import anthropic

client = anthropic.Anthropic()

def call_with_retry(prompt, max_retries=4):
    for attempt in range(max_retries):
        try:
            return client.messages.create(
                model="claude-opus-4-8",
                max_tokens=4096,
                messages=[{"role": "user", "content": prompt}],
            )
        except anthropic.RateLimitError:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

Los límites de tasa escalan con tu nivel de uso. Para trabajos por lotes de alto rendimiento que no requieren latencia en tiempo real, la API por lotes también desbloquea hasta 300K tokens de salida con un encabezado beta.

Migración de Opus 4.7 a 4.8

La mayoría de los proyectos cambian exactamente una cadena:

# Before
model="claude-opus-4-7"

# After
model="claude-opus-4-8"

Qué verificar después del cambio:

Niveles de esfuerzo: el comportamiento es el mismo rango que en 4.7, pero vuelve a ejecutar tus evaluaciones en el nivel que utilices
Configuración de pensamiento: si alguna vez configuraste budget_tokens, elimínalo; Opus 4.8 lo rechazará con un error 400
Esquemas de herramientas: se mantienen, pero vuelve a ejecutar tu evaluación de uso de herramientas
Coste: tarifas por token idénticas a las de 4.7, por lo que no habrá sorpresas en la facturación

Preguntas Frecuentes

¿Cuál es el ID del modelo de la API de Claude Opus 4.8? claude-opus-4-8 en la API de Claude y Vertex AI, y anthropic.claude-opus-4-8 en AWS Bedrock.

¿Existe un nivel gratuito para la API de Opus 4.8? No hay un nivel de API gratuito permanente, pero las nuevas cuentas obtienen créditos de prueba. Consulta la guía de acceso gratuito para otras opciones de bajo coste.

¿Cómo establezco el nivel de esfuerzo? Pasa output_config: {"effort": "xhigh"} (o low, medium, high, max) en la solicitud. El valor predeterminado es high.

¿Por qué mi solicitud devuelve un 400 sobre budget_tokens? Opus 4.8 no admite el pensamiento extendido manual. Elimina budget_tokens y usa thinking: {type: "adaptive"} con el parámetro effort.

¿Opus 4.8 funciona con el SDK compatible con OpenAI? Anthropic proporciona una capa de compatibilidad para el SDK de OpenAI. Apunta la URL base al endpoint de Anthropic y usa tu clave de Anthropic; mantén la cadena del modelo claude-opus-4-8.

¿Qué max_tokens debo establecer para el trabajo agéntico? Comienza con 64K cuando uses el esfuerzo xhigh o max para que el modelo tenga espacio para pensar y encadenar llamadas a herramientas. Ajusta a la baja una vez que veas el uso real.

¿Cómo pruebo las respuestas en streaming en Apidog? Abre la solicitud, habilita el streaming en el cuerpo, y Apidog renderizará los fragmentos de eventos enviados por el servidor a medida que llegan, lo que facilita la detección de respuestas incompletas.