Blog

Tutorial

Cómo llamar a claude-opus-5-5@aws a través de la API de HiAPI: guía con curl y Python

Nov 12, 2026
Arte de portada con puntos de semitono verde menta que varían en densidad sobre un fondo casi negro con acentos verde azulado profundo.
En esta página

Cómo se ve usar claude-opus-5-5@aws a través de HiAPI

HiAPI ofrece una interfaz HTTP unificada para múltiples modelos. No necesitas configurar cuentas, SDK ni almacenamiento de credenciales por separado para cada proveedor; basta con usar el mismo formato de solicitud de HiAPI y seleccionar el modelo deseado mediante su identificador. En este tutorial, ese identificador es claude-opus-5-5@aws: el sufijo @aws forma parte del nombre del modelo, no es un campo independiente, y debe pasarse tal cual.

El ciclo de vida de una solicitud es el siguiente:

  1. Autenticación: envía tu clave de API de HiAPI como bearer token en la cabecera Authorization.
  2. Envío de una carga tipo chat: un cuerpo JSON que contiene model y un array messages, donde cada mensaje incluye role (system, user o assistant) y content.
  3. Recepción de una respuesta JSON: la respuesta del asistente aparece en el array choices de la respuesta, junto con metadatos de uso.
  4. Continuación de la conversación: añade el mensaje del asistente y tu siguiente mensaje de usuario al mismo array messages y vuelve a enviar. La API no tiene estado; la conversación completa se conserva en la carga de tu solicitud.

Dado que la estructura de solicitud es idéntica entre modelos, el código que escribas para claude-opus-5-5@aws puede migrarse a otro modelo simplemente cambiando la cadena model. Mantén ese campo centralizado en un solo lugar del código, como un valor de configuración o una variable de entorno, en lugar de codificarlo de forma fija en varios archivos.

Una aclaración sobre la nomenclatura: la plataforma documenta este modelo como claude-opus-5-5@aws. Usa exactamente esa cadena. Un error tipográfico, un espacio adicional o un sufijo omitido producirán un error de tipo modelo no encontrado, en lugar de una advertencia útil.

Obtención de credenciales y autenticación

Antes de llamar a la API, necesitas una clave de API de tu cuenta de HiAPI. Trata esa clave como un secreto: guárdala en una variable de entorno o en el gestor de secretos de tu plataforma, y nunca la incluyas en el control de código fuente ni en código de cliente que se envíe al navegador.

HiAPI autentica las solicitudes mediante un bearer token en la cabecera Authorization:

export HIAPI_API_KEY="your-api-key-here"

Cada solicitud debe incluir:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Estas reglas prácticas evitan la mayoría de los fallos de autenticación:

  • Conserva el prefijo literal Bearer , seguido de un espacio y luego la clave. Omitir el prefijo o el espacio es un error habitual al copiar y pegar.
  • No entrecomilles la clave en el valor de la cabecera.
  • Si rotas la clave, actualiza la variable de entorno y reinicia el proceso; los workers de larga duración suelen conservar en caché el valor anterior.
  • Al pegar la clave en un archivo .env, comprueba si hay espacios en blanco o saltos de línea finales; algunos cargadores no los eliminan automáticamente.

Si la clave falta o tiene un formato incorrecto, recibirás un error de autenticación (tipo 401), no un error de modelo, por lo que es fácil distinguirlo de problemas posteriores. Una vez que la solicitud se autentica correctamente, la misma cabecera sirve para streaming, llamadas a herramientas y todos los demás patrones de esta guía; no necesitas credenciales distintas para cada función.

Para el código del servidor, carga la clave una vez al iniciar y pásala a un cliente compartido o a una pequeña función envoltorio. Así centralizas el secreto en un solo lugar y cambiar entre credenciales de desarrollo y de producción resulta trivial.

Construcción de una solicitud ejecutable con curl

A continuación se muestra una solicitud completa y ejecutable. Sustituye la clave de marcador de posición por la tuya o ejecuta primero el export de la sección anterior para que el shell realice la sustitución.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5@aws",
    "messages": [
      {
        "role": "user",
        "content": "Explica en tres frases por qué los endpoints POST idempotentes son importantes para una API de pagos."
      }
    ]
  }'

Desglose elemento por elemento:

  • Endpoint: POST https://api.hiapi.ai/v1/chat/completions.
  • Cabeceras: bearer token y tipo de contenido JSON. Ambos son obligatorios.
  • model: el identificador exacto claude-opus-5-5@aws.
  • messages: un array de objetos con role y content. El último mensaje de usuario es aquello a lo que el modelo debe responder.
  • Carga: -d envía JSON sin procesar, por lo que el manejo de comillas es importante. En el shell, encierra todo el cuerpo de la solicitud entre comillas simples y usa comillas dobles para las claves JSON.

La respuesta es un JSON que contiene un array choices. El texto generado se encuentra en choices[0].message.content e incluye información de uso (recuento de tokens) para que puedas monitorizar el consumo. El uso de la respuesta se factura por tokens; las tarifas actuales figuran en el panel de precios del sitio web.

Ajustes habituales:

{
  "model": "claude-opus-5-5@aws",
  "max_tokens": 512,
  "temperature": 0.2,
  "messages": [
    {"role": "system", "content": "Eres un editor técnico conciso."},
    {"role": "user", "content": "Resume el cuerpo de la solicitud anterior en una línea."}
  ]
}

Usa max_tokens para limitar generaciones descontroladas, temperature para controlar la verbosidad y la varianza, y un mensaje system para establecer el comportamiento una vez por conversación. El mensaje system debe colocarse en el mismo array messages, antes del turno del usuario.

La misma solicitud en Python

La versión en Python usa la biblioteca estándar urllib, por lo que el fragmento se ejecuta sin instalar nada. Si prefieres una biblioteca cliente, la estructura de la solicitud es idéntica; solo cambia el transporte.

import json
import os
import urllib.request

API_URL = "https://api.hiapi.ai/v1/chat/completions"
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "claude-opus-5-5@aws"

def ask(user_message: str, system_message: str | None = None) -> str:
    messages = []
    if system_message:
        messages.append({"role": "system", "content": system_message})
    messages.append({"role": "user", "content": user_message})

    payload = json.dumps({
        "model": MODEL,
        "messages": messages,
    }).encode("utf-8")

    request = urllib.request.Request(
        API_URL,
        data=payload,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        body = json.loads(response.read().decode("utf-8"))

    return body["choices"][0]["message"]["content"]

if __name__ == "__main__":
    print(ask("Saluda usando exactamente cinco palabras."))

Por qué merece la pena conservar esta estructura:

  • MODEL y API_URL son constantes a nivel de módulo, por lo que cambiar de modelo o de endpoint requiere una sola línea.
  • La clave proviene del entorno; la función nunca acepta un parámetro de secreto sin procesar.
  • La lógica de análisis está aislada al final, por lo que puedes cambiar urllib por httpx o requests sin modificar la forma de construir la conversación.

Para continuar una conversación de varios turnos, añade la respuesta del asistente y el siguiente mensaje de usuario a messages antes de volver a enviar. Deja que el array crezca hasta alcanzar el límite de contexto y, después, resume los turnos anteriores en un mensaje system para mantenerte dentro del presupuesto. El uso de la respuesta se basa en tokens; las tarifas actuales se publican en el panel de precios del sitio web.

Respuestas en streaming para escenarios interactivos

Para interfaces de chat y generaciones largas, el streaming envía contenido parcial a medida que se produce la salida, en lugar de esperar a la respuesta completa. El cuerpo de la solicitud no cambia salvo por un campo:

{
  "model": "claude-opus-5-5@aws",
  "messages": [{"role": "user", "content": "Escribe una entrada breve de changelog para una biblioteca que acaba de adoptar streaming."}],
  "stream": true
}

Con stream: true, el endpoint responde con eventos enviados por el servidor (server-sent events): cada bloque es una línea con el prefijo data: , y el flujo termina con un marcador final. La mayoría de los bloques contienen, dentro del array choices, un delta con un fragmento de texto en lugar del mensaje completo.

Con curl, elimina el efecto silencioso de -sS para observar cómo llega la salida de forma progresiva:

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-5-5@aws","stream":true,"messages":[{"role":"user","content":"Cuenta hasta cinco lentamente."}]}'

El flag -N desactiva el almacenamiento en búfer para que veas los bloques a medida que llegan. En Python, lee la respuesta línea por línea:

with urllib.request.urlopen(request) as response:
    for raw_line in response:
        line = raw_line.decode("utf-8").strip()
        if not line.startswith("data: "):
            continue
        data = line[len("data: "):]
        if data == "[DONE]":
            break
        chunk = json.loads(data)
        delta = chunk["choices"][0].get("delta", {})
        text = delta.get("content")
        if text:
            print(text, end="", flush=True)

Consejos prácticos:

  • Gestiona siempre el marcador de terminación [DONE] y las líneas vacías o de keep-alive; no asumas que todas las líneas son JSON.
  • Nunca bloquees el hilo de la interfaz de usuario durante todo el flujo: añade los deltas a un búfer a medida que lleguen.
  • Si el cliente se desconecta, cierra la respuesta para liberar la generación ascendente.
  • El streaming no cambia cómo se calcula el uso; el último bloque suele llevar los metadatos de uso. La facturación se calcula por tokens de salida; las tarifas actuales figuran en el panel de precios del sitio web.

Añadir llamadas a herramientas a la conversación

El uso de herramientas permite que el modelo solicite operaciones estructuradas a tu código, no solo que genere texto. La solicitud incorpora un array tools; la conversación incorpora mensajes del asistente que llevan tool_calls y mensajes role: "tool" que llevan resultados.

Define los parámetros de la herramienta con JSON Schema:

{
  "model": "claude-opus-5-5@aws",
  "messages": [
    {"role": "user", "content": "¿Qué tiempo hace ahora en Lisboa?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Devuelve el tiempo actual de una ciudad.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "Nombre de la ciudad, por ejemplo Lisbon"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

Es posible que el modelo devuelva un mensaje que contenga tool_calls en lugar de texto final. Cada entrada especifica el nombre de la función y lleva parámetros como una cadena JSON. Tu trabajo consiste en ejecutar esa función contra tu propio sistema y, después, añadir el resultado:

  1. Añade tal cual a messages el mensaje del asistente que contiene tool_calls.
  2. Para cada llamada, añade un mensaje que contenga role: "tool", el tool_call_id correspondiente del mensaje del asistente y content establecido al resultado serializado.
  3. Envía de nuevo la solicitud con el mismo array tools. El modelo generará entonces una respuesta en lenguaje natural basada en tus resultados.

Medidas de protección que conviene establecer desde el principio:

  • Valida los parámetros: antes de ejecutar cualquier operación, valida los parámetros según el schema; nunca pases la salida del modelo directamente a un shell o a una consulta de base de datos.
  • Limita los bucles. Establece un límite para las rondas de llamadas a herramientas (normalmente de tres a cinco) para evitar que un modelo que sigue solicitando llamadas entre en un bucle infinito.
  • Devuelve los errores como resultados de la herramienta. Si la función falla, envía una cadena de error breve con el tool_call_id correspondiente; el modelo podrá entonces reintentar o explicar el fallo en lugar de quedarse bloqueado.
  • Mantén descripciones de herramientas precisas. Las descripciones vagas provocan selecciones de herramienta incorrectas con mucha más frecuencia que los errores de parámetros.

Las definiciones de herramientas se evalúan con la solicitud y cuentan para tu uso de tokens. Las tarifas actuales se publican en el panel de precios del sitio web.

Qué hacer a continuación

Empieza con la llamada mínima con curl, llévala a una función envoltorio de Python y, después, añade streaming y herramientas solo cuando tu caso de uso lo requiera. La cadena de modelo claude-opus-5-5@aws permanece siempre igual; todo lo demás son campos de la carga de la solicitud.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API