Blog

Tutorial

Cómo usar gpt-6-sol a través de la API de HiAPI: curl, Python y una solicitud que funciona

Nov 12, 2026
Arte de portada arquitectónico con planos de hormigón gris cálido cortados por una sombra angular azul pizarra y una fina junta verde salvia.
En esta página

Qué necesitas antes de la primera llamada

Antes de escribir cualquier código, prepara tres cosas. El resto de este tutorial se basa en ellas.

Una clave de API de HiAPI

Cada solicitud enviada a la API de HiAPI requiere autenticación con una clave de API. Crea una clave en el panel de tu cuenta de HiAPI y guárdala en un lugar seguro, preferiblemente en una variable de entorno en lugar de un archivo de código fuente. Trátala como una contraseña: si se filtra, rótala de inmediato.

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

El endpoint base

Todas las llamadas de esta guía van dirigidas al endpoint base de la API de HiAPI, y cada modelo se accede mediante la misma forma de ruta de solicitud. No necesitas un host ni un SDK separado para cada modelo: gpt-6-sol se selecciona en el cuerpo de la solicitud, no cambiando la configuración del cliente.

Un cliente HTTP

Necesitas uno de los siguientes:

  • curl, disponible por defecto en la mayoría de los sistemas Linux y macOS, así como en las terminales de Windows.
  • Python con la biblioteca requests instalada (pip install requests), o la biblioteca estándar urllib si prefieres no añadir dependencias.

No hace falta nada más. No necesitas un SDK de un proveedor específico ni instalar nada relacionado con el modelo. Basta con que puedas enviar una solicitud HTTPS POST con un cuerpo JSON y cabeceras para llamar a gpt-6-sol.

Un hábito que conviene adoptar ahora: mantén un archivo de borrador donde registres la solicitud que funciona que estás usando, de modo que cuando algo falle puedas comparar la llamada fallida con la última llamada que sabes que funciona.

Autenticarse con una clave bearer

La autenticación es donde más se falla en la primera llamada, así que conviene tratarla con cuidado.

La cabecera Authorization

La API de HiAPI espera tu clave en la cabecera bearer estándar:

Authorization: Bearer $HIAPI_API_KEY

Es la palabra literal Bearer, un espacio y luego la clave. Los errores habituales incluyen: omitir la palabra Bearer, arrastrar un salto de línea adicional al copiar el valor, o poner comillas alrededor de la clave cuando el cliente ya las añade.

El tipo de contenido debe ser JSON

La solicitud lleva un cuerpo JSON, por lo que la cabecera de tipo de contenido debe coincidir:

Content-Type: application/json

Si falta esta cabecera, algunos servidores aún analizarán el cuerpo, pero no deberías depender de ello: configúrala explícitamente. Un tipo de contenido incorrecto es una causa habitual de errores de validación de la solicitud que parecen errores del cuerpo.

El conjunto mínimo de cabeceras

Solo necesitas las dos cabeceras anteriores:

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

Mantén el conjunto de cabeceras lo más pequeño posible. Las cabeceras especulativas tomadas de ejemplos de otras API tienden más a confundir que a ayudar. Una vez que la llamada con estas dos cabeceras funciona, tienes una base limpia con la que comparar más adelante.

Evita pegar la clave directamente en el historial del shell o en archivos ya confirmados. Hacer referencia a la variable de entorno como arriba mantiene la clave fuera de tu código fuente y del historial de la terminal.

Construir el cuerpo de la solicitud para gpt-6-sol

El cuerpo de la solicitud es JSON y su núcleo es una lista de mensajes. Empieza con la configuración mínima; añade campos solo después de que la llamada funcione.

El payload mínimo

El cuerpo útil mínimo debe especificar el modelo y proporcionar un mensaje:

{
  "model": "gpt-6-sol",
  "messages": [
    { "role": "user", "content": "Explica en una frase qué es un token bearer de API." }
  ]
}

Aquí intervienen dos campos:

  • model selecciona gpt-6-sol, de modo que el mismo endpoint pueda servir también a otros modelos más adelante.
  • messages es la lista ordenada de turnos de la conversación. Cada entrada tiene un role (system, user o assistant) y un content de tipo cadena.

Valores predeterminados seguros y añadidos opcionales

Considera model y messages como obligatorios. Todo lo demás es opcional y debe añadirse con intención:

  • Un mensaje system al principio de messages establece el comportamiento o el tono de la conversación. Es un mensaje normal, no un campo separado de nivel superior.
  • Si es necesario, el control de la longitud de salida se configura como parámetros del cuerpo de la solicitud. Añádelos solo cuando la salida predeterminada sea demasiado corta o demasiado larga para tu caso de uso.
  • Los parámetros de muestreo cambian la forma de la salida, no su validez. Evita modificarlos mientras depuras una llamada fallida, porque no pueden corregir errores de autenticación ni de estructura del cuerpo.

Una regla práctica

Cuando algo falla, el payload debe parecerse lo más posible al ejemplo mínimo. Elimina los campos opcionales uno por uno hasta que la llamada funcione y luego vuelve a añadirlos. Esto aísla el problema rápidamente: un parámetro defectuoso es más fácil de encontrar que uno malo enterrado entre cinco buenos.

Enviar una solicitud que funciona con curl

El siguiente es un comando completo que puedes ejecutar directamente siempre que hayas exportado tu clave. Usa una ruta de endpoint de marcador de posición que sigue las convenciones de la API de HiAPI descritas arriba.

curl -sS -X POST "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "user", "content": "Explica en una frase qué es un token bearer de API." }
    ]
  }'

Configura HIAPI_BASE_URL con el endpoint base de tu panel de HiAPI. Estas opciones son importantes:

  • -X POST establece el método; estas llamadas son todas POST.
  • -H añade cada cabecera, una por línea.
  • -d proporciona el cuerpo JSON. Las comillas simples evitan que el shell lo interpole.
  • -sS mantiene la salida silenciosa pero sigue mostrando los errores, que es justo lo que necesitas al automatizar.

Leer la respuesta

Una respuesta correcta es JSON. Normalmente verás un objeto de nivel superior con el nombre del modelo y una lista de choices, cada choice con un mensaje cuyo content guarda el texto generado. Lee primero la estructura y luego el cuerpo: confirma que el objeto se puede analizar y después localiza el campo content.

Para mejorar la legibilidad, puedes canalizarla a una herramienta de formato JSON:

... | python -m json.tool

Si tu terminal imprime en cambio un objeto de error, la llamada no tuvo éxito: pasa a la sección de errores en lugar de ajustar el prompt. Cuando la solicitud ni siquiera llega al modelo, el problema no está en el prompt.

Enviar la misma solicitud con Python

El payload que acabas de validar en curl se puede trasladar directamente. Mantén el cuerpo idéntico, de modo que las correcciones validadas en la terminal también se apliquen en el código.

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-6-sol",
    "messages": [
        {"role": "user", "content": "Explica en una frase qué es un token bearer de API."}
    ],
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{base_url}/chat/completions",
    headers=headers,
    json=payload,
    timeout=60,
)

response.raise_for_status()
data = response.json()

for choice in data.get("choices", []):
    message = choice.get("message", {})
    print(message.get("content", ""))

Por qué esta versión es más segura en el código de la aplicación

  • El cuerpo es un diccionario. Cuando pasas json=payload, requests lo serializa y configura el tipo de contenido por ti, pero mantener la cabecera explícita evita sorpresas al cambiar de cliente.
  • La clave viene de una variable de entorno. No hay secretos codificados de forma rígida, por lo que el archivo se puede confirmar.
  • raise_for_status() se ejecuta primero. Una respuesta no 2xx lanza una excepción de inmediato, antes de que intentes leer campos que no existen en el cuerpo de la respuesta de error.
  • Se establece un tiempo de espera. Sin él, una conexión atascada podría dejar colgado indefinidamente un proceso de trabajo.

El bucle sobre choices también evita errores por claves ausentes, lo que hace que el ejemplo tolere respuestas con poco o ningún contenido. Construye tu envoltorio de producción sobre este esqueleto: validar, enviar, comprobar el estado y luego analizar.

Recibir la respuesta en streaming en lugar de esperar

De forma predeterminada, la API devuelve la respuesta completa en un único objeto JSON. Para salidas largas o interfaces interactivas, puedes solicitar en su lugar que la respuesta se entregue de forma progresiva a medida que se genera.

El interruptor de streaming

El streaming se habilita con un indicador en el cuerpo de la solicitud, no con un endpoint diferente:

{
  "model": "gpt-6-sol",
  "messages": [
    { "role": "user", "content": "Escribe un párrafo breve sobre los códigos de estado HTTP." }
  ],
  "stream": true
}

Añade este indicador al final, después de que la llamada no streaming ya funcione. Cambia cómo se organiza la respuesta, no si la solicitud es válida.

Consumir la salida incremental

Con el streaming activado, la respuesta ya no es un único documento JSON. Llega como una serie de eventos, normalmente separados por líneas, y cada evento lleva un pequeño fragmento de salida. Tu cliente debe leerlos a medida que llegan en lugar de llamar a .json() sobre todo el cuerpo de la respuesta.

with requests.post(
    f"{base_url}/chat/completions",
    headers=headers,
    json=payload,
    stream=True,
    timeout=60,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line.decode("utf-8"))

En la terminal, el mismo interruptor se comporta de forma distinta a una llamada no streaming: la salida aparece de forma progresiva, por lo que una tubería truncada puede parecer una solicitud fallida cuando en realidad solo se interrumpió el flujo.

Cuál usar

Usa la modalidad no streaming para tareas por lotes, pruebas y cualquier caso en que necesites el objeto completo de una vez. Usa streaming cuando alguien está esperando texto o cuando la salida es tan larga que la latencia se nota. Mantén ambas rutas en el código, porque la no streaming es más fácil de depurar.

Leer y corregir los códigos de error comunes

Diagnostica primero por el código de estado y luego por el cuerpo de la respuesta. No cambies el modelo ni reescribas el prompt hasta que sepas qué capa está fallando.

401 Unauthorized

Causa: la clave falta, tiene un formato incorrecto o fue revocada. Solución: confirma que la cabecera dice exactamente Authorization: Bearer <key>, comprueba si hay espacios ocultos o una variable de entorno obsoleta, y verifica que la clave siga activa en tu panel. Imprime la longitud de la variable en lugar de su valor para detectar variables vacías.

400 Bad Request

Causa: el cuerpo no se puede analizar o le faltan campos obligatorios. Solución: vuelve a enviar el payload mínimo con solo model y messages. Valida el JSON con python -m json.tool antes de enviarlo; las comas finales o un error tipográfico en model son causas habituales. Confirma que Content-Type sea application/json.

403 Forbidden

Causa: la clave es válida pero falta permiso de acceso al recurso solicitado. Solución: comprueba si tu cuenta tiene acceso a gpt-6-sol y si el nombre del modelo en el cuerpo coincide con el configurado para tu cuenta.

404 Not Found

Causa: la ruta de la URL es incorrecta, normalmente por un error tipográfico en el endpoint, o porque falta o se duplica la ruta base. Solución: compara la URL completa carácter por carácter con la llamada curl que funciona.

429 Too Many Requests

Causa: envías solicitudes más rápido de lo que permite tu cuenta. Solución: retrocede y reintenta con un retardo creciente. Respeta cualquier indicación de reintento en las cabeceras de respuesta y nunca reintentes en un bucle ajustado: eso empeora el problema. Distingue esto de los 5xx, que indican un problema del lado del servidor, no de tu tasa de solicitudes.

Errores 5xx del servidor

Causa: el servicio no puede procesar una solicitud que por lo demás es válida. Solución: reintenta con retroceso; si el problema persiste, captura el cuerpo de la respuesta y el ID de la solicitud, y evita cambiar el payload, porque ya funcionaba.

Un orden de depuración repetible

  1. Código de estado: ¿es un problema de autenticación, de ruta o del cuerpo?
  2. Cuerpo de la respuesta: ¿señala el campo problemático?
  3. Estructura del payload: vuelve al ejemplo mínimo.
  4. El prompt o los parámetros, solo al final.

Este orden acorta continuamente el tiempo entre el fallo y la corrección. Una vez que tus llamadas se estabilicen, conserva las versiones de curl y Python que funcionan una al lado de la otra, de modo que cada prueba futura parta de un estado que sabes que funciona.

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