Tutorial

Cómo usar Claude Opus 4.8 a través de la API de hiapi

Sep 21, 2026

Qué vas a construir

Una integración funcional que llama a Claude Opus 4.8 a través de la API Chat Completions compatible con OpenAI de hiapi — el modelo de gama alta actual de la serie Claude 4.8 de Anthropic. Una sola solicitud devuelve una completación real, junto con los modos de producción que necesitarás una vez que tu demo funcione (transmisión en streaming, llamada a herramientas, razonamiento adaptativo).

Requisitos previos:una clave de API de hiapi. Obtén una desde laconsola — es una cadena sk-..., y la misma clave funciona para todos los modelos habilitados en tu cuenta, no solo para este modelo.

Todo lo que aparece a continuación se ejecutó realmente contra la API en producción en el momento de escribir este artículo.

Ejemplo mínimo funcional

Claude Opus 4.8 es unmodelo de texto en el endpoint estándar Chat Completions — no el flujo asíncrono /v1/tasks que hiapi usa para modelos de imagen/vídeo/audio. Una solicitud, una respuesta, sin sondeo.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [
      {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
    ],
    "max_tokens": 1024
  }'

Respuesta (abreviada):

{
  "id": "msg_011CfFm8abLRcYtLVSky81As",
  "model": "claude-opus-4-8",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 10, "completion_tokens": 4, "total_tokens": 14 }
}

La misma llamada en Python, usando solo requests:

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-<your-api-key>"},
    json={
        "model": "claude-opus-4-8",
        "messages": [
            {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
        ],
        "max_tokens": 1024,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"])  # prompt_tokens / completion_tokens / total_tokens

Envía directamente el ID de modelo sin prefijo claude-opus-4-8 — sin prefijo de proveedor, sin sufijo de enrutamiento. hiapi lista dos rutas de backend para este modelo (default y aws) para proporcionar redundancia, pero comparten el mismo ID de modelo; no necesitas elegir entre ellas.

Dado que el formato de la solicitud es compatible con OpenAI, esto también funciona sin cambios con los SDK oficiales de Python/JS openai — solo apunta base_url a https://api.hiapi.ai/v1 y pasa tu clave de hiapi.

Patrones de producción

Transmisión en streaming

Establece "stream": true y lee Server-Sent Events. Cada fragmento contiene un trozo de delta.content; el flujo termina en el último fragmento con finish_reason: "stop", seguido de un centinela [DONE]:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "Count 1 to 3"}],
    "stream": true,
    "max_tokens": 20
  }'

data: {"choices":[{"delta":{"content":"","role":"assistant"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":"1"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":", 2, 3"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Acumula choices[0].delta.content a través de los fragmentos para reconstruir el texto completo. El evento de datos final (después de finish_reason) lleva los totales de usage, no un delta.

Llamada a herramientas

Declara funciones de la misma manera que con OpenAI, luego reproduce en el siguiente turno el mensaje tool_calls del asistente y el mensaje de resultado tool:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "What is the status of task demo-123?"}],
    "max_tokens": 200,
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_task_status",
        "description": "Look up a task by ID.",
        "parameters": {
          "type": "object",
          "properties": {"task_id": {"type": "string"}},
          "required": ["task_id"],
          "additionalProperties": false
        }
      }
    }],
    "tool_choice": "auto"
  }'

La respuesta llega con finish_reason: "tool_calls" y contiene el nombre de la función y los argumentos codificados en JSON en choices[0].message.tool_calls. Ejecuta tu función localmente y luego envía el resultado de vuelta en la siguiente solicitud como un mensaje role: "tool" con el tool_call_id correspondiente — el modelo continuará desde ahí.

Razonamiento adaptativo

Claude Opus 4.8 admite rondas de razonamiento opcionales. Añade "thinking": {"type": "adaptive"} y elige el nivel de esfuerzo mediante output_config.effort (low, medium o high están confirmados como disponibles):

{
  "model": "claude-opus-4-8",
  "messages": [{"role": "user", "content": "Compare two approaches and state the trade-offs."}],
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "high"}
}

Hay dos cosas que conviene saber antes de construir sobre esta función. Primero, "adaptativo" significa que el modelo decide por sí mismo si un prompt merece razonamiento — con un nivel de esfuerzo low o incluso medium, una pregunta simple puede no devolver en absoluto el campo reasoning_details, así que no asumas que cada solicitud producirá ese campo. Segundo, a diferencia de algunos otros modelos de texto en hiapi, Opus 4.8 no devuelve una traza de razonamiento legible por humanos: las entradas reasoning.text del arreglo reasoning_details vienen vacías, solo las entradas signature están pobladas. Trata reasoning_details como un estado de continuación opaco — si vas a llevar la sesión a una llamada de herramienta posterior, pásalo tal cual — y no lo analices ni lo muestres al usuario.

Manejo de errores

Un fallo de autenticación devuelve HTTP 401 con un sobre hiapi_error:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

Comprueba response.status_code antes de acceder a response.json()["choices"], y registra error.request_id si necesitas escalar el caso — el equipo de soporte puede rastrear la llamada específica con él.

Idempotencia y reintentos

Las llamadas a Chat Completions no son idempotentes por ID de solicitud como las tareas de /v1/tasks — una solicitud reintentada es una nueva completación y también un nuevo cobro. Para tráfico de producción, envuelve la lógica de reintento con retroceso en tu código para casos de 5xx/tiempo de espera, y limita max_tokens para que una tormenta de reintentos (o una llamada de razonamiento adaptativo de larga duración) no genere un coste sin límite.

Lecturas relacionadas

Claude Opus 4.8 en hiapi — precios actuales y ficha del modelo.
Autenticación — cómo funcionan las claves de API de hiapi y cómo rotarlas.
Cómo usar Claude Sonnet 4.6 a través de la API de hiapi — el mismo patrón de integración para el nivel de Claude con equilibrio de costes de hiapi, si tu carga de trabajo no necesita un modelo tan potente como Opus 4.8.
Precios de hiapi — tarifas por token en tiempo real de Claude Opus 4.8 y todos los demás modelos habilitados.

Preguntas frecuentes

¿claude-opus-4-8 es el ID de modelo exacto que debo enviar? Sí — envía la cadena sin prefijo claude-opus-4-8 en el campo model. No se necesita prefijo específico de proveedor ni sufijo de enrutamiento; hiapi lo resuelve internamente a la ruta de backend correcta.

¿Esto usa el mismo flujo /v1/tasks que los modelos de imagen y vídeo de hiapi? No. Los modelos de texto como Claude Opus 4.8 usan el endpoint síncrono POST /v1/chat/completions — una solicitud, una respuesta (o un flujo SSE). /v1/tasks solo se aplica a modelos de medios (imagen, vídeo, audio), que se ejecutan de forma asíncrona y devuelven una URL o callback para sondear.

¿Puedo usar el SDK de OpenAI en lugar de curl/requests sin procesar? Sí. Como el endpoint es compatible con OpenAI, apunta el base_url del SDK oficial openai a https://api.hiapi.ai/v1 y usa tu clave de hiapi como api_key — no se necesitan otros cambios de código para chat básico, streaming o llamada a herramientas.

¿Debería usar Opus 4.8 o Sonnet 4.6? Opus 4.8 es el nivel de mayor capacidad y mayor coste — elígelo en tareas de razonamiento, programación o agentes más difíciles, cuando la precisión importa más que la latencia o el coste por token. Para tráfico de alto volumen o sensible a la latencia, Claude Sonnet 4.6 ofrece la misma forma de API a un precio más bajo.

¿thinking devuelve siempre una traza de razonamiento visible? Ni una cosa ni la otra: el razonamiento adaptativo puede omitir por completo el razonamiento en solicitudes que juzga simples, y cuando sí razona, los campos de texto de reasoning_details de Opus 4.8 actualmente vienen vacíos — solo la firma está poblada. No construyas una interfaz que asuma que siempre existe una traza legible.

¿Dónde consulto los precios actuales antes de ejecutar lotes grandes? Lapágina de precios de hiapi lista las tarifas por token en tiempo real de Claude Opus 4.8 — consúltala antes de presupuestar, ya que este artículo no codifica de forma fija cifras que podrían quedar obsoletas.