Blog

Tutorial

Cómo llamar a gpt-5.6-sol@azure a través de la API de HiAPI: curl y Python

Autenticación, estructura del cuerpo de la solicitud, ejemplos disponibles y manejo de errores

Nov 10, 2026
Hojas de papel superpuestas en tonos crema y grafito que se suceden en escalones poco profundos, con una hoja terracota como acento — arte de portada para el tutorial de gpt-5.6-sol@azure.
En esta página

Qué significa gpt-5.6-sol@azure como objetivo de modelo en HiAPI

gpt-5.6-sol@azure es un identificador de modelo, no un SDK independiente, no un endpoint independiente y no un método de autenticación independiente. Es exactamente la cadena que colocas en el campo model de la solicitud de chat completions que envías a HiAPI.

El sufijo @azure te indica qué proveedor de backend sirve esa variante del modelo. Desde la perspectiva de tu aplicación, esto no cambia en absoluto la forma de llamarlo: la misma URL base, la misma autenticación bearer, la misma estructura de solicitud y respuesta que cualquier otro modelo de chat de la plataforma. No necesitas instalar nada adicional ni credenciales específicas del proveedor: HiAPI se encarga del enrutamiento y de la relación con el proveedor por su lado.

El resultado práctico es: cualquier cliente compatible con OpenAI que ya estés usando puede apuntar a este modelo con dos cambios: apuntar la URL base del cliente a HiAPI y establecer el nombre del modelo como gpt-5.6-sol@azure. Si actualmente tienes el nombre del modelo codificado en algún lugar de la configuración, ese valor de configuración es lo único que hay que cambiar al cambiar de modelo en la plataforma; esto hace que la comparación A/B sea muy económica.

En este tutorial, el identificador aparece siempre como la cadena literal gpt-5.6-sol@azure. Escríbelo con exactitud: distingue mayúsculas y minúsculas, y los espacios sobrantes que se arrastran al copiar y pegar son una de las causas reales del error de "modelo desconocido" descrito más adelante.

Qué necesitas antes de empezar

  • Una cuenta de HiAPI con acceso a la plataforma.
  • Una clave de API generada desde tu cuenta.
  • Un shell con curl, o Python 3 con la biblioteca requests.

Los ejemplos siguientes no requieren ninguna otra herramienta.

Obtener la clave de API y configurar la autenticación

La autenticación de HiAPI es mediante bearer token: tu clave de API se coloca en el encabezado Authorization de cada solicitud, con el prefijo de la palabra Bearer seguida de un espacio.

Authorization: Bearer YOUR_API_KEY

Generas la clave desde el panel de tu cuenta. Trátala como una contraseña: es una credencial activa que puede consumir tu saldo y nunca debe aparecer en commits, capturas de pantalla, notebooks compartidos ni líneas de registro.

Guardarla en una variable de entorno

La práctica básica es exportar la clave una vez por sesión de shell y leerla desde el entorno en todos los demás lugares:

export HIAPI_API_KEY="your-key-here"

En un servidor, configúrala mediante el gestor de procesos o un almacén de secretos, no con un archivo .env versionado. Si un archivo .env es realmente la única opción, añádelo a .gitignore antes de escribir la primera clave.

Referenciarla, no incluirla en línea

En curl, referencia la variable del shell para que la clave nunca aparezca en el historial de comandos ni en la lista de procesos:

curl -H "Authorization: Bearer $HIAPI_API_KEY" ...

En Python, léela en tiempo de ejecución con os.environ:

import os

API_KEY = os.environ["HIAPI_API_KEY"]

Usa deliberadamente os.environ["..."] en lugar de os.environ.get("..."): si la variable falta, quieres que falle ruidosamente al arrancar en lugar de encontrarte con un error de autenticación confuso quince líneas después.

Reglas de higiene de claves que debes interiorizar ahora

  • Una clave por entorno. Las claves de desarrollo y producción deben estar separadas, para que puedas rotar o revocar una sin romper la otra.
  • Si se expone, se rota. Si una clave aparece alguna vez en un lugar público, revócala y emite una nueva; no te limites a borrar el commit.
  • No registres los encabezados. Un middleware de registro de solicitudes que vuelca todos los encabezados escribirá alegremente tu bearer token en disco. Enmascara Authorization antes de registrar.

Si la primera llamada te da un error de autenticación, la causa es casi siempre una de estas: la variable se exportó en un shell distinto del que ejecuta la solicitud, falta el prefijo Bearer , o la clave se copió con un salto de línea final.

Anatomía mínima del cuerpo de la solicitud

Cada llamada a gpt-5.6-sol@azure es un POST con cuerpo JSON. Puedes construir una solicitud válida con un solo campo, y esa es la mejor forma de empezar: primero obtén una respuesta, luego añade controles.

Campos obligatorios

  • model: la cadena gpt-5.6-sol@azure. Es lo que enruta la solicitud al objetivo correcto.
  • messages: un array de objetos de mensaje. Cada objeto tiene role y content. Los roles habituales son system (instrucciones que moldean el comportamiento), user (la entrada) y assistant (turnos anteriores en una conversación multiturno).

El cuerpo mínimo es el siguiente:

{
  "model": "gpt-5.6-sol@azure",
  "messages": [
    { "role": "user", "content": "Explain what an idempotency key is in one paragraph." }
  ]
}

Con eso basta. La respuesta llega con la estructura de chat completions: un array choices cuyo primer elemento contiene la respuesta del asistente en message.content, más un bloque usage que describe el consumo de tokens. Tu código debe leer desde choices[0].message.content, no asumir otros campos.

Campos opcionales que conviene conocer

No son obligatorios, pero serán los primeros que uses:

  • temperature: aleatoriedad del muestreo. Los valores bajos hacen la salida más determinista y repetitiva; los altos, más variada. Elige el valor a propósito, no por costumbre.
  • max_tokens (o el límite equivalente de longitud de salida que exponga tu cliente): un tope a la longitud generada. Útil tanto para la latencia como para el control de costes.
  • top_p: otro control de aleatoriedad. En la práctica, ajusta temperature o top_p, no ambos a la vez, o no podrás atribuir los cambios de comportamiento a ninguno de los dos.
  • stream: si es true, la respuesta llega de forma incremental como eventos enviados por el servidor en lugar de un único documento JSON. Excelente para interfaces orientadas al usuario, pero requiere más trabajo para analizarse correctamente.
  • stop: una o varias secuencias que terminan la generación antes de tiempo.

Nota sobre las conversaciones multiturno

La API no tiene estado. No se conserva nada entre solicitudes. Para continuar una conversación, debes reenviar cada vez el array messages completo, añadiendo la respuesta anterior del asistente y el nuevo mensaje del usuario. Por eso las conversaciones largas hacen crecer el cuerpo de la solicitud, y con ello el uso de tokens: tenlo en cuenta al diseñar una función de chat.

Mantén el cuerpo sencillo al principio

Empieza con los dos campos obligatorios y confirma que obtienes una respuesta razonable. Luego añade un parámetro a la vez y observa la diferencia. Depurar es mucho más fácil cuando tienes una línea base reciente que sabes que funciona.

Solicitud curl que funciona

Esta es una solicitud completa y ejecutable. Si tu región o plan difieren, sustituye la URL base por la que se muestra en la documentación de la API de la plataforma, y asegúrate de que HIAPI_API_KEY esté exportada en el shell actual.

curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol@azure",
    "messages": [
      { "role": "system", "content": "You are a concise technical assistant." },
      { "role": "user", "content": "Give me three practical uses for idempotency keys." }
    ],
    "temperature": 0.3
  }'

Qué hace cada opción

  • -sS silencia la barra de progreso pero sigue imprimiendo errores, para que los fallos no pasen inadvertidos.
  • -X POST establece el método explícitamente, sobre todo por legibilidad.
  • El encabezado Authorization lleva el bearer token desde el entorno.
  • Content-Type: application/json es obligatorio; sin él el servidor no sabe cómo interpretar el cuerpo.
  • -d proporciona la carga útil JSON. Enciérrala entre comillas simples para que el shell no interprete las comillas dobles internas.

Leer la respuesta

Una llamada correcta devuelve un JSON con el array choices. El texto que quieres está en choices[0].message.content. También hay un objeto usage con el recuento de tokens de prompt y de completado: regístralo, porque es la única forma económica de vigilar su tendencia antes de que el consumo se convierta en una sorpresa.

Si quieres inspeccionar la estructura sin pelearte con el terminal, pásala por un formateador:

curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol@azure","messages":[{"role":"user","content":"Say hello."}]}' \
  | python3 -m json.tool

Esta línea es la prueba de humo más rápida que existe para una clave nueva. Ejecútala antes de tocar cualquier código de la aplicación: si falla, el problema está en las credenciales o en la conectividad, no en tu programa.

La misma solicitud en Python

La versión con requests es corta, pero conviene escribirla con cuidado: comprueba el código de estado antes de analizar el cuerpo de la respuesta, porque la estructura de una respuesta de error es distinta de la de una respuesta correcta y, si accedes directamente a choices, obtendrás un confuso KeyError.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"

payload = {
    "model": "gpt-5.6-sol@azure",
    "messages": [
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Give me three practical uses for idempotency keys."},
    ],
    "temperature": 0.3,
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

if response.status_code != 200:
    # Surface the status and the server's error body, not just the exception.
    print(f"HTTP {response.status_code}: {response.text}")
    response.raise_for_status()

data = response.json()
text = data["choices"][0]["message"]["content"]
print(text)
print(json.dumps(data.get("usage", {}), indent=2))

Tres detalles importantes

Usa json=payload, no data=json.dumps(payload). Pasar un diccionario a json= establece el encabezado de tipo de contenido por ti y serializa correctamente siempre. La serialización manual es el origen de la mayoría de los cuerpos de solicitud mal formados.

Establece siempre un timeout. Sin él, una solicitud atascada bloquea tu proceso de trabajo indefinidamente. Un timeout generoso sigue siendo mucho mejor que ninguno.

Imprime response.text cuando falles. El cuerpo de error contiene los detalles que necesitas: el tipo de error, el código y un mensaje legible. Registrar solo el mensaje de la excepción de raise_for_status() descarta esa información y te deja adivinando.

Envuélvelo en una función

Cuando la llamada funcione, conviértela en una función que reciba el array de mensajes como parámetro y devuelva la cadena de contenido. Esto mantiene limpio el código de la aplicación y te da exactamente un lugar donde cambiar el nombre del modelo, el timeout o, más adelante, la estrategia de reintentos.

Diagnosticar los errores habituales

Casi todas las primeras llamadas fallidas pertenecen a una de cuatro categorías. Así se distinguen rápidamente.

Fallos de autenticación

Síntoma: una respuesta 401, o 403 si la clave es válida pero le falta acceso al recurso solicitado.

Comprueba en orden:

  1. ¿Está HIAPI_API_KEY realmente definida en el shell o proceso que envía la solicitud? echo $HIAPI_API_KEY debería imprimir algo.
  2. ¿Incluye el encabezado la palabra literal Bearer y exactamente un espacio antes de la clave?
  3. ¿La clave arrastra un salto de línea o comillas del copiar y pegar? Expórtala de nuevo limpiamente.
  4. ¿Se ha revocado o rotado la clave desde que la copiaste? Emite una nueva.

Identificador de modelo desconocido

Síntoma: 400 o 404, con un mensaje que menciona el modelo.

El culpable habitual es una errata, una discrepancia de mayúsculas y minúsculas o espacios sobrantes en la cadena. gpt-5.6-sol@azure debe ser exacto: el @, los guiones y la escritura en minúsculas cuentan. Si lees el nombre del modelo de un archivo de configuración o de una variable de entorno, imprime ese valor y su longitud; los espacios invisibles son un culpable frecuente.

Cuerpo de solicitud mal formado

Síntoma: 400, que se queja del análisis de JSON o de campos ausentes.

  • Si el error menciona el análisis, tu cuerpo no es JSON válido. En curl, encierra la carga útil entre comillas simples y las claves entre comillas dobles. En Python, usa json=payload.
  • Si menciona messages, comprueba que pasaste un array de objetos con role y content, no cadenas simples.
  • Si menciona que falta model, la clave está mal escrita o en el nivel de anidamiento equivocado.

Comprobación rápida de sanidad: pasa la carga útil por un validador de JSON antes de enviarla. Son solo unos segundos y eliminan toda una categoría de problemas.

Límites de velocidad y cuota

Síntoma: respuesta 429, a veces con una indicación de retry-after.

Esto significa que tu solicitud está bien formada y autenticada, pero llega demasiado rápido o supera la cuota. La solución no es reintentar de inmediato en un bucle ajustado: eso solo lo empeora. Usa retroceso exponencial con jitter, limita el número de intentos y trata un 429 persistente como una señal para revisar tu concurrencia.

Errores del lado del servidor

Un 500 o un 502 no son culpa tuya. Reintenta con retroceso; si persiste, captura el ID completo de la solicitud y el cuerpo de la respuesta antes de escalar: esos detalles son los que hacen productiva una conversación con soporte.

Hábito de depuración universal

Registra cuatro cosas en cada llamada fallida: el estado HTTP, el cuerpo de la respuesta, la ruta del endpoint y el nombre del modelo. No registres la clave de API. Esa cuaterna distingue todas las categorías anteriores en segundos, algo que un mensaje de excepción desnudo rara vez logra.

Pasos siguientes tras la primera llamada correcta

Cuando la prueba de humo devuelva contenido, ya tienes una integración funcional. Así la haces duradera.

Ajusta los parámetros con criterio

Elige una temperature para tu caso de uso y anota el motivo. Las tareas de extracción y clasificación suelen querer poca aleatoriedad; la lluvia de ideas quiere más. En cada experimento cambia solo un parámetro para poder atribuir los resultados. Si estás considerando el streaming, prototíipalo pronto: las diferencias en el análisis de la respuesta son lo bastante grandes como para que añadirlo después cueste más que usarlo desde el principio.

Trata los reintentos y los timeouts como estrategia, no como algo accesorio

Envuelve la llamada en reintentos con retroceso exponencial solo para respuestas 429 y 5xx. Nunca reintentes un 400 o un 401: la solicitud o las credenciales son incorrectas y reintentar solo pierde tiempo. Define un timeout de cliente para cada solicitud y considera una fecha límite global para los flujos de usuario.

Monitoriza coste y latencia desde el primer día

Registra el bloque usage junto con tus propias mediciones de latencia. El recuento de tokens es la entrada de toda conversación sobre costes, y la latencia la de toda conversación sobre experiencia de usuario. Sin ellos, optimizas a ciegas.

Pon el nombre del modelo en la configuración

Codificar gpt-5.6-sol@azure en tres archivos es la forma de que migrar duela. Guárdalo en un único valor de configuración y cambiar de modelo pasa a ser un cambio de una línea; también es la forma de comparar modelos de manera justa en la plataforma.

Lleva las claves a una gestión de secretos adecuada

Si empiezas con variables de entorno en un portátil, el camino a producción es un almacén de secretos gestionado con inyección en tiempo de ejecución. El mismo código, una custodia más segura.

Refuerza la ruta de salida

La salida del modelo es entrada no confiable. Si la renderizas como HTML, escápala. Si la analizas como JSON, valídala antes de actuar. Si la enrutas a sistemas posteriores, decide explícitamente qué ocurre cuando la respuesta llega vacía o truncada.

Cuando estés listo para explorar otros objetivos de modelo en la plataforma, usan la misma estructura de solicitud: solo cambia la cadena model, así que todo lo que construiste arriba se mantiene tal cual.

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