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
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 bibliotecarequests.
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
Authorizationantes 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 cadenagpt-5.6-sol@azure. Es lo que enruta la solicitud al objetivo correcto.messages: un array de objetos de mensaje. Cada objeto tieneroleycontent. Los roles habituales sonsystem(instrucciones que moldean el comportamiento),user(la entrada) yassistant(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, ajustatemperatureotop_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
-sSsilencia la barra de progreso pero sigue imprimiendo errores, para que los fallos no pasen inadvertidos.-X POSTestablece el método explícitamente, sobre todo por legibilidad.- El encabezado
Authorizationlleva el bearer token desde el entorno. Content-Type: application/jsones obligatorio; sin él el servidor no sabe cómo interpretar el cuerpo.-dproporciona 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:
- ¿Está
HIAPI_API_KEYrealmente definida en el shell o proceso que envía la solicitud?echo $HIAPI_API_KEYdebería imprimir algo. - ¿Incluye el encabezado la palabra literal
Bearery exactamente un espacio antes de la clave? - ¿La clave arrastra un salto de línea o comillas del copiar y pegar? Expórtala de nuevo limpiamente.
- ¿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, usajson=payload. - Si menciona
messages, comprueba que pasaste un array de objetos conroleycontent, 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 →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio