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

Qué significa gpt-5.6-terra@azure en una solicitud de HiAPI

En una solicitud de HiAPI, gpt-5.6-terra@azure es un identificador de modelo: debes colocarlo en el campo model del cuerpo de la solicitud de chat. Ese es todo el contrato por tu parte. No necesitas construir una URL específica del proveedor, ni cambiar el SDK, ni alterar la estructura del cuerpo de la solicitud.

El sufijo @azure es metadatos de enrutamiento: le indica a HiAPI qué backend debe procesar las solicitudes de esta variante del modelo. El resto del cuerpo de la solicitud —messages, temperature, max_tokens, stream, tools— mantiene la estructura estándar de chat-completions que ya conoces. Esto importa en la práctica: si ya tienes una solicitud funcional que llama a otros modelos en HiAPI, migrar a gpt-5.6-terra@azure normalmente solo requiere cambiar una línea.

{
  "model": "gpt-5.6-terra@azure",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

Adoptar dos hábitos hace que los bugs relacionados con el ID del modelo aparezcan muy rara vez:

• Trata el ID como una cadena opaca. Cópialo tal cual, incluidos el @ y el sufijo en minúsculas. Sin espacios, sin cambiar mayúsculas y minúsculas.
• Colócalo en la configuración, no disperso por el código. Usar una constante o una variable de entorno convierte las pruebas A/B entre distintos ID de modelo en un cambio de configuración en lugar de una refactorización.

Como el sufijo se encarga del enrutamiento, no debes inferir nada sobre el stack subyacente solo a partir del ID. La latencia, los límites y los parámetros admitidos son propiedades de la forma en que HiAPI expone este modelo, así que verifica el comportamiento real con una solicitud pequeña antes de escribir suposiciones en tu aplicación.

Requisitos previos y preparación de la clave

Antes de la primera llamada, confirma tres cosas:

1. Una cuenta de HiAPI. Necesitas iniciar sesión para crear credenciales y consultar en la consola la información actual de modelos y precios.
2. Una clave de API. Genérala en la consola y guárdala en un lugar seguro: trátala como una contraseña. Esta guía no asume un formato de clave concreto; cualquier cadena que te dé la consola es el valor que va en la cabecera Authorization.
3. Un cliente HTTP. Usa curl para verificaciones rápidas y Python 3 con requests o el SDK compatible con OpenAI para escribir el código de la aplicación.

Mantén la clave fuera de los archivos fuente

Usa variables de entorno. El patrón es el mismo en todas las plataformas:

export HIAPI_API_KEY="your-key-here"

Luego referénciala en tiempo de ejecución. En el shell: "$HIAPI_API_KEY". En Python: os.environ["HIAPI_API_KEY"]. En CI, usa el almacén de secretos que ofrezca tu proveedor en lugar de confirmar un archivo .env.

Si pegas la clave en la terminal para depurar, ten en cuenta que puede quedar en el historial del shell; si es una credencial real, rótala después. Para desarrollo local, usar una clave desechable solo para pruebas es más fácil de gestionar que reutilizar credenciales de producción.

Confirma tu Base URL y el endpoint

HiAPI ofrece un endpoint de chat completions compatible con OpenAI. Obtén la base URL y la ruta de la documentación de tu consola y mantenlas coherentes en curl y en Python: la mayoría de los informes de "curl funciona pero Python no" se reducen a una barra final o a un segmento de ruta faltante.

Una solicitud curl que funciona

Esta es la llamada mínima correcta. Sustituye la base URL por la que muestra tu consola y asegúrate de que HIAPI_API_KEY esté exportada.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra@azure",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API gateway does in two sentences."}
    ],
    "max_tokens": 200
  }'

Explicación campo por campo:

• -sS silencia la barra de progreso pero sigue mostrando los errores. Si quieres ver las cabeceras de respuesta junto con el cuerpo, añade -i.
• Authorization: Bearer $HIAPI_API_KEY autentica la solicitud. El prefijo Bearer y el espacio son obligatorios.
• Content-Type: application/json: si lo omites, muchos servidores rechazarán el cuerpo antes de analizarlo.
• model: el ID exacto gpt-5.6-terra@azure.
• messages: un array ordenado. system define el comportamiento; user contiene el prompt. En conversaciones multiturno, añade los turnos assistant y user en orden.
• max_tokens: el límite de longitud de la respuesta. Mantenlo pequeño en las verificaciones rápidas para que los fallos sean baratos y rápidos.

Una respuesta correcta es un JSON que contiene un array choices; el texto que necesitas está en choices[0].message.content. En las primeras pruebas, pasa la salida por una herramienta de formateo JSON para ver la estructura en lugar de esforzarte por leer una línea larguísima.

Cuando esta solicitud funcione, guárdala como un script de shell que lea la clave de una variable de entorno. Así tendrás una comprobación de estado repetible que puedes ejecutar cada vez que cambies el ID del modelo o los parámetros.

La solicitud equivalente en Python

El cuerpo de la solicitud es idéntico; solo cambia el transporte. Con requests:

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API gateway does in two sentences."},
    ],
    "max_tokens": 200,
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

Hay tres detalles que conviene conservar: usa json=payload en lugar de serializar a mano (configura las cabeceras y la codificación por ti), establece siempre un timeout y llama a raise_for_status() para que un 4xx o 5xx se manifieste como una excepción en lugar de provocar un IndexError al indexar el cuerpo de una respuesta de error.

Estilo SDK del proveedor

Como el endpoint es compatible con OpenAI, un SDK configurado con una base URL personalizada produce la misma solicitud:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)

completion = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Say hello in one word."}],
    max_tokens=50,
)
print(completion.choices[0].message.content)

La razón de mostrar ambos enfoques es esta: el ID del modelo es la única variable que determina qué modelo te atiende. El resto es la tubería habitual de chat-completions, así que puedes alternar entre HTTP directo y el SDK sin reescribir la lógica.

Añadir streaming y llamada a herramientas

Ambas funciones son incrementales. No reescribes la solicitud base, sino que añades campos y cambias la forma de consumir la respuesta.

Streaming

Establece "stream": true en el cuerpo de la solicitud:

stream = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Count from 1 to 10."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

La respuesta se convierte en una serie de eventos enviados por el servidor en lugar de un único objeto JSON. Cada fragmento lleva un delta con una porción de contenido; en el primer y el último fragmento, delta.content puede ser None, así que compruébalo antes de concatenar. Con HTTP directo ocurre lo mismo: lee el cuerpo de la respuesta línea por línea, elimina el prefijo data: , omite [DONE] y analiza el JSON de cada línea.

Llamada a herramientas

Describe las herramientas en la solicitud para que el modelo decida cuándo llamarlas:

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [{"role": "user", "content": "What's the weather in Berlin?"}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
    "tool_choice": "auto",
}

Cuando el modelo quiere llamar a una herramienta, choices[0].message contiene un array tool_calls en lugar de texto plano. Cada entrada tiene un id y un function que contiene name y arguments (una cadena JSON que debes analizar). Ejecuta tu función y luego devuelve el resultado como un mensaje con role: "tool", con el tool_call_id correspondiente y la salida serializada; después, haz otra solicitud para obtener la respuesta final.

tool_choice acepta "auto" (lo decide el modelo), "none" (solo texto) o una función concreta. El streaming y las herramientas pueden combinarse, pero los argumentos de la llamada a herramientas llegan por fragmentos repartidos entre bloques que debes acumular antes de analizar; primero haz que funcione la llamada a herramientas sin streaming.

Diagnosticar errores comunes de solicitud

Depura en este orden; cada paso aísla una capa para que no persigas dos problemas a la vez.

1. Autenticación (401 / 403)

Las causas más probables: clave ausente, prefijo Bearer perdido o una variable de entorno que se expande a una cadena vacía. Muestra cómo se construye la cabecera sin imprimir la clave completa y confirma que la variable esté definida en el mismo shell o proceso que ejecuta la solicitud.

2. Endpoint y ruta (404)

Un 404 suele significar una ruta incorrecta: una errata, falta el /v1 o hay una barra final de más donde no debería. Copia la URL exacta de la consola en lugar de volver a escribirla.

3. ID del modelo (400, con un mensaje relacionado con el modelo)

El ID debe coincidir exactamente: gpt-5.6-terra@azure. Los fallos habituales incluyen cambios de mayúsculas y minúsculas, falta el @azure o espacios extra introducidos al copiar y pegar. Si el mensaje dice que el modelo es desconocido, compara carácter por carácter la cadena configurada con la lista de la consola antes de sospechar de un fallo del servicio.

4. Formato del cuerpo de la solicitud incorrecto (400 / 422)

Si el error menciona el cuerpo de la solicitud, comprueba primero la validez del JSON: las comas finales o las comillas sin escapar son los culpables habituales. Luego verifica los nombres de los campos (es messages, no message) y los roles (system, user, assistant, tool). max_tokens debe ser un número y tools debe ser un array de objetos con la estructura correcta.

5. Tratar una respuesta en streaming como JSON normal

Si la salida está vacía, es ilegible o lanza un error de análisis, es probable que hayas solicitado stream: true pero estés analizando la respuesta como un único documento JSON. Lee por flujo de eventos, omite [DONE] y protege contra deltas None.

6. Tiempo de espera del cliente

Las generaciones largas pueden superar el tiempo de espera HTTP predeterminado. Auméntalo explícitamente en el cliente o cambia a streaming para que los bytes empiecen a llegar de inmediato.

Lista de comprobación para una reproducción rápida

• Ejecuta la llamada curl mínima. Si funciona, el problema está en tu código.
• Si falla, reinténtalo en un shell nuevo con tu clave y tu ID de modelo.
• Registra tanto el código de estado HTTP como el cuerpo de la respuesta: el cuerpo de error contiene detalles de diagnóstico.
• Solo después de que estas comprobaciones pasen deberías sospechar que hay un problema del lado del servicio que merezca escalarse.

Con una solicitud funcional, un bucle de streaming y esta lista de comprobación, gpt-5.6-terra@azure se comporta en tu stack como cualquier otro modelo de chat, y cambiar de modelo se reduce a una línea en la configuración.