Cómo usar la API de Claude Opus 5: integración en producción y migración con EvoLink

Claude Opus 5 Datos breves de la API

La conclusión práctica es simple: Claude Opus 5 se puede llamar a través de EvoLink ahora, mientras que la compatibilidad de parámetros, la facturación y el comportamiento operativo aún deben validarse con una solicitud real a nivel de cuenta antes del lanzamiento completo de producción.

Por qué utilizar Claude Opus 5 a través de una API unificada

Llamar a un nuevo modelo es fácil. Mantener una aplicación flexible después de la semana de lanzamiento es más difícil.

Una integración directa puede ser la opción correcta cuando un equipo necesita todas las características nativas de Anthropic inmediatamente y tiene la intención de utilizar solo Claude. Una puerta de enlace unificada se vuelve más útil cuando la aplicación debe elegir entre modelos, contener costos, preservar un respaldo o cambiar de proveedor sin distribuir código específico del modelo a través del producto.

Por lo tanto, la función útil de EvoLink no es convertir cada solicitud en una solicitud de Opus 5. Es para mantener la selección del modelo en la capa de enrutamiento:

Application task
  -> routing policy
  -> selected model
  -> Messages API request
  -> actual-model and usage verification
  -> quality and cost record
  -> promote, retry, fall back, or roll back

Esta arquitectura brinda a un equipo cuatro ventajas concretas:

1. Una superficie de integración. La aplicación envía mensajes estilo Claude a través de un punto final documentado.
2. Selección de modelo configurable. La lógica empresarial describe el trabajo, como routine_coding o architecture_escalation, mientras que la configuración elige el modelo actual.
3. Retroceso mensurable. Un reintento o cambio de modelo se convierte en un evento operativo explícito en lugar de un contaminante de referencia invisible.
4. Flexibilidad de migración. El próximo cambio de modelo es principalmente una decisión de enrutamiento y evaluación, no una reescritura de solicitudes, códigos de producto y configuraciones del cliente.

Realizar la primera llamada a la API de Claude Opus 5

1. Confirme el acceso a la cuenta antes de cambiar el código de producción

La ruta EvoLink está disponible. Antes de cambiar el tráfico de producción, confirme que su cuenta pueda llamarlo y que la ruta completa de la aplicación se comporte como se espera:

• claude-opus-5 aparece en la lista para su cuenta EvoLink.
• Una solicitud mínima devuelve HTTP 200.
• response.model identifica el modelo esperado.
• El registro de uso y el monto cobrado coinciden con la superficie de precios actual de EvoLink.
• Las funciones requeridas, como la transmisión o las herramientas, funcionan en la misma ruta.

Si su cuenta no expone la ruta o falla una característica requerida, mantenga el modelo existente como alternativa y resuelva el problema de cuenta o compatibilidad antes de la implementación.

2. Almacene la clave API en el servidor

Cree una clave API EvoLink y cárguela desde una variable de entorno del lado del servidor:

export EVOLINK_API_KEY="your_api_key_here"

3. Envíe una solicitud mínima

La solicitud mínima sigue la forma de la Messages API de Claude EvoLink:

curl --request POST \
  --url https://direct.evolink.ai/v1/messages \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "Review this service architecture and identify the three highest-risk failure points."
      }
    ]
  }'

Comience sin parámetros opcionales. Una pequeña carga útil aísla la autenticación, la disponibilidad de rutas y el contrato de solicitud principal antes de que el esfuerzo, las herramientas, la transmisión o el almacenamiento en caché agreguen más modos de falla.

4. Verifique la respuesta, no solo el código de estado

Una respuesta HTTP exitosa demuestra que el punto final devolvió algo. No prueba por sí solo que el modelo previsto cumplió con la solicitud o que el resultado pertenece a una evaluación Opus 5.

Registre al menos:

• response.model
• response.stop_reason
• uso de entrada y salida
• solicitar latencia
• solicitar identificación cuando esté disponible
• ID de tarea de aplicación
• reintento y recuento de respaldo

El siguiente ejemplo de TypeScript del lado del servidor distingue los errores de cliente que no se pueden reintentar de los fallos de capacidad que se pueden reintentar y verifica el modelo devuelto sin utilizar valores sin tipo:

type Usage = {
  input_tokens: number
  output_tokens: number
  cache_creation_input_tokens?: number
  cache_read_input_tokens?: number
}

type TextBlock = {
  type: 'text'
  text: string
}

type MessageResponse = {
  id: string
  model: string
  stop_reason: string | null
  content: TextBlock[]
  usage: Usage
}

const RETRYABLE_STATUS = new Set([429, 500, 503, 524])

function isMessageResponse(value: unknown): value is MessageResponse {
  if (typeof value !== 'object' || value === null) return false

  const record = value as Record<string, unknown>
  return (
    typeof record.id === 'string' &&
    typeof record.model === 'string' &&
    Array.isArray(record.content) &&
    typeof record.usage === 'object' &&
    record.usage !== null
  )
}

async function callClaudeOpus5(prompt: string): Promise<MessageResponse> {
  const credential = process.env.EVOLINK_API_KEY
  if (!credential) throw new Error('EVOLINK_API_KEY is not configured')

  for (let attempt = 0; attempt < 3; attempt += 1) {
    const response = await fetch('https://direct.evolink.ai/v1/messages', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${credential}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'claude-opus-5',
        max_tokens: 4096,
        messages: [{ role: 'user', content: prompt }],
      }),
      signal: AbortSignal.timeout(120_000),
    })

    if (response.ok) {
      const payload: unknown = await response.json()
      if (!isMessageResponse(payload)) {
        throw new Error('Unexpected Claude Messages API response')
      }

      if (payload.model !== 'claude-opus-5') {
        throw new Error(`Unexpected response model: ${payload.model}`)
      }

      return payload
    }

    if (!RETRYABLE_STATUS.has(response.status) || attempt === 2) {
      throw new Error(`Claude request failed with HTTP ${response.status}`)
    }

    const backoffMs = 1_000 * 2 ** attempt + Math.floor(Math.random() * 250)
    await new Promise((resolve) => setTimeout(resolve, backoffMs))
  }

  throw new Error('Claude request exhausted its retry policy')
}

Este es un patrón de referencia, no un sustituto de las pruebas a nivel de cuenta. En un servicio de gran volumen, agregue registros estructurados, correlación de solicitudes, controles de concurrencia y un respaldo elegido por su política de enrutamiento.

Cómo interactúan el pensamiento, el esfuerzo y max_tokens

Opus 5 cambia el comportamiento de una solicitud que de otro modo sería familiar. El pensamiento está activado de forma predeterminada y el esfuerzo controla la cantidad de cálculo que puede aplicar el modelo.

Tres detalles previenen errores comunes de integración:

1. max_tokens cubre el pensamiento y la salida visible. Un límite heredado de una ruta sin pensamiento de Opus 4.8 puede truncar una tarea de Opus 5 antes de lo esperado.
2. El esfuerzo no controla de manera confiable la longitud visible de la respuesta. Solicite explícitamente una respuesta concisa o la longitud objetivo de la respuesta.
3. El soporte del proveedor puede variar. Envíe output_config.effort únicamente a través de EvoLink después de que la documentación de su ruta actual o una prueba real confirme que el campo es aceptado.

Mantenga el pensamiento habilitado cuando sea práctico. Anthropic advierte que deshabilitar el pensamiento puede ocasionalmente hacer que una llamada a una herramienta aparezca como texto normal o exponga etiquetas internas similares a XML en la respuesta visible.

Migrar desde Claude Opus 4.8 sin llevar a cabo suposiciones antiguas

El cambio de ID del modelo es la parte fácil:

- "model": "claude-opus-4-8"
+ "model": "claude-opus-5"

Migración de solicitudes

• Las solicitudes sin un campo thinking ahora se ejecutan con el pensamiento activado.
• Vuelva a visitar max_tokens para ver flujos de trabajo que anteriormente se ejecutaban sin pensar.
• No combine el pensamiento desactivado con xhigh o max.
• Confirma que no queden valores de temperature, top_p o top_k de configuraciones anteriores a 4.8: Opus 4.8 ya los rechaza y Opus 5 mantiene el mismo comportamiento.
• Pruebe el nuevo mínimo de caché de avisos de 512 tokens si los avisos repetidos anteriormente eran demasiado cortos para almacenarlos en caché.
• Manejar stop_reason: "refusal" como resultado de la solicitud.

Migración de prompts

Es más probable que Opus 5 verifique su propio trabajo, narre el progreso y delegue en subagentes. Las indicaciones adaptadas a un modelo anterior pueden multiplicar accidentalmente esos comportamientos.

Actualice las indicaciones de cuatro maneras:

• Especificar la respuesta prevista o la extensión del documento.
• Eliminar instrucciones incondicionales para volver a verificar o agregar un verificador final.
• Restringir el alcance para tareas limitadas.
• Limitar la delegación de subagente a menos que el trabajo paralelo independiente lo justifique.

Migración del harness

Repita las tareas representativas en toda la aplicación, no solo en la llamada al modelo sin formato. Verificar:

• selección de herramientas y argumentos
• comportamiento del analizador de streaming
• límites de tiempo de espera y reintento
• manejo de rechazos
• modelo devuelto real
• uso de token y caché
• longitud de salida
• aceptación de la tarea por parte del revisor real o verificación posterior

Promocionar Opus 5 por carga de trabajo. Un modelo puede mejorar tareas de arquitectura difíciles y al mismo tiempo agregar costos innecesarios a la extracción de rutina.

Gestionar herramientas, streaming, rechazos y fallos de transporte

La EvoLink Messages API expone la transmisión, las herramientas, la elección de herramientas, el uso y los motivos de detención. Un ciclo de producción debería ramificarse a partir de la respuesta en lugar de asumir que cada 200 respuestas contiene una respuesta final.

Send message
  -> end_turn: return the answer
  -> tool_use: execute the allowed tool and continue
  -> refusal: apply the refusal and fallback policy
  -> max_tokens: mark the result incomplete
  -> transport error: retry only when the error is retryable

Establezca un recuento máximo de bucles de herramientas, valide cada argumento de herramienta y conserve el seguimiento necesario para explicar una tarea fallida. Nunca ejecute una llamada a una herramienta producida por un modelo sin autorización a nivel de aplicación y validación de esquema.

Trate los fracasos por clase:

Un rechazo no es lo mismo que una solicitud HTTP fallida. Anthropic lo documenta como un resultado de respuesta normal para Opus 5. El respaldo automático puede estar disponible en la API nativa de Anthropic, pero confirme el equivalente de EvoLink antes de colocar campos específicos del proveedor en una solicitud de puerta de enlace.

Medir el costo por tarea exitosa

Claude Opus 5 mantiene el mismo precio base oficial del token que Opus 4.8, pero el precio de lista no le dice al equipo de producción qué ruta es más barata.

Utilice esta métrica de decisión:

successful-task cost =
  input token cost
  + output token cost
  + retry cost
  + fallback cost
  + tool execution cost
  + human review or repair cost

La tabla de evaluación debe incluir:

No publique una recomendación de esfuerzo universal a partir de un único mensaje. Elija la vía de menor esfuerzo que cumpla con el umbral de calidad para cada carga de trabajo y luego reserve el escalamiento para tareas en las que fallar sea costoso.

Enrutar Sonnet, Opus y Fable según la carga de trabajo

Guarde la decisión de enrutamiento en la configuración:

type Workload =
  | 'routine_text'
  | 'everyday_coding'
  | 'complex_agent'
  | 'frontier_escalation'

const modelByWorkload: Record<Workload, string> = {
  routine_text: 'configured-low-cost-model',
  everyday_coding: 'claude-sonnet-5',
  complex_agent: 'claude-opus-5',
  frontier_escalation: 'claude-fable-5',
}

La aplicación debe registrar tanto el modelo solicitado como el devuelto. Si se produce un retroceso, excluya ese rastro de un punto de referencia limpio de Opus 5 o etiquételo por separado.

Lista de verificación de preparación para la producción

Antes de trasladar el tráfico real a Opus 5:

• claude-opus-5 aparece en la lista para la cuenta EvoLink.
• Una solicitud mínima devuelve el response.model esperado.
• El uso y la facturación coinciden con la ruta documentada.
• Se verifica el streaming si el producto depende de él.
• [] Cada ruta de herramienta requerida tiene una solicitud válida y un seguimiento de resultados.
• La aplicación distingue el rechazo del error HTTP.
• [] Los errores reintentables y no reintentables siguen políticas diferentes.
• Existe una ruta alternativa conocida y se ha utilizado.
• [] Las tareas representativas se han repetido en múltiples niveles de esfuerzo.
• [] Los umbrales de promoción utilizan la tasa de tareas aceptadas, la latencia y el costo de las tareas exitosas.
• [] Los ID de modelo residen en la configuración en lugar de en la lógica empresarial.
• Las condiciones de reversión son explícitas.

Preguntas frecuentes

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

¿Está Claude Opus 5 disponible a través de EvoLink?

¿Qué punto final EvoLink debo usar?

¿El pensamiento está habilitado de forma predeterminada en Claude Opus 5?

¿Qué nivel de esfuerzo debo elegir?

¿Cómo migro desde Claude Opus 4.8?

¿Cuánto cuesta Claude Opus 5?

Fuentes

• Anthropic: Presentamos Claude Opus 5
• Anthropic: Novedades de Claude Opus 5
• Anthropic: Solicitando Claude Opus 5
• Anthropic: Guía de migración
• Anthropic: Esfuerzo
• Anthropic: rechazos y respaldo
• EvoLink: Claude Messages API