Cómo llamar a gpt-image-2.5-sunburst/text-to-image mediante la API de HiAPI: curl y Python

Qué te ofrece este endpoint de modelo

gpt-image-2.5-sunburst/text-to-image es un modelo de generación de imágenes expuesto a través de la API unificada de HiAPI. Lo llamas mediante el ID del modelo, envías el prompt en un cuerpo de solicitud con la misma forma que chat-completions que usan los modelos de texto y luego obtienes los datos de la imagen generada en la respuesta.

La implicación práctica es: si tu base de código ya procesa texto a través de HiAPI, no necesitas un segundo SDK, ni un esquema de autenticación aparte, ni aprender una nueva familia de endpoints. Lo único que cambia es el ID del modelo.

Elige este endpoint cuando tu tarea sea la generación de prompt a imagen: crear una imagen nueva a partir de una descripción textual y, opcionalmente, guiada por imágenes de referencia proporcionadas en la solicitud. Si necesitas analizar o describir imágenes existentes en lugar de generarlas, un modelo de chat con capacidad de visión es más adecuado; deja la generación de imágenes en este endpoint y la comprensión de imágenes en otro lugar.

Hay una expectativa que conviene fijar de antemano: las llamadas de imagen son más lentas que las completaciones de texto. Es normal que el tiempo de respuesta llegue a varios segundos, y el tiempo de espera de tu cliente debe ajustarse a esta realidad, no heredarse de una configuración pensada para texto puro.

Antes de enviar tu primera solicitud

Necesitas tener tres cosas listas.

Una clave de API

Crea una clave en tu cuenta de HiAPI y guárdala como variable de entorno, no escrita en el código fuente:

export HIAPI_API_KEY="your-key-here"

El ID exacto del modelo

La cadena es gpt-image-2.5-sunburst/text-to-image. Trátala como un identificador opaco: cópiala, no la vuelvas a escribir de memoria. La barra forma parte del ID. Un error tipográfico aquí es la causa más común de fallo en la primera llamada, y se manifiesta como un error de modelo no encontrado en lugar de un problema de carga útil.

Un cliente capaz de hacer solicitudes HTTPS

Para una primera verificación basta con curl, que viene preinstalado en la mayoría de los sistemas. Para el código de la aplicación, Python con la biblioteca requests (o cualquier cliente HTTP) es suficiente. Este endpoint no exige que el cliente use una biblioteca de imágenes especializada; simplemente envías JSON y recibes JSON.

No necesitas subir imágenes previamente ni configurar almacenamiento antes de la primera llamada de texto puro. Empieza con la solicitud mínima de abajo y añade imágenes de referencia solo cuando el viaje de ida y vuelta básico funcione.

Una solicitud mínima funcional con curl

Esta es la llamada correcta más pequeña:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
      {
        "role": "user",
        "content": "A sunlit coastal cliff at golden hour, wide angle, high detail"
      }
    ]
  }'

Campo por campo:

• URL: la ruta estándar de chat-completions de HiAPI. Los modelos de imagen usan la misma ruta que los modelos de texto.
• Authorization: token bearer con la clave de API. Si el formato de esta cabecera es incorrecto, recibirás un 401 antes de que se llame al modelo.
• Content-Type: debe ser application/json.
• model: el ID exacto del modelo de la sección anterior.
• messages: un arreglo estándar de objetos role/content. Tu prompt es el content del mensaje de user.

Si tiene éxito, recibirás una respuesta JSON que contiene los datos de la imagen generada junto con los metadatos habituales de completación. Guarda primero la respuesta sin procesar en un archivo y, tras revisarla, conecta la lógica de análisis al script:

curl -sS ... -o response.json

En cuanto esto devuelva una imagen, tus credenciales y la forma de la carga útil serán correctas, y todos los problemas posteriores serán de lógica de aplicación, no de configuración.

Escribir la misma solicitud en Python

El contrato de la solicitud no cambia; solo cambian la configuración del cliente, el tiempo de espera y el manejo de la respuesta.

import os
import requests

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

payload = {
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
        {
            "role": "user",
            "content": "A sunlit coastal cliff at golden hour, wide angle, high detail",
        }
    ],
}

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

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

Hay tres detalles que merecen atención:

Los tiempos de espera son explícitos y asimétricos

La tupla (10, 180) establece un tiempo de espera de conexión corto y uno de lectura más amplio. La generación de imágenes tarda por naturaleza; un único tiempo de espera plano copiado de un cliente de texto producirá fallos falsos. Mantén corto el tiempo de conexión para que los problemas de red fallen rápido.

Usa json=payload en lugar de data=

Pasar un diccionario mediante json= se encarga de la serialización y establece el tipo de contenido por ti. Si pasas una cadena ya serializada con data=, establece la cabecera manualmente.

Análisis defensivo

La respuesta es JSON; antes de indexar, registra el cuerpo completo de la respuesta ante formas inesperadas. No asumas una profundidad de anidamiento fija hasta haber visto la respuesta real, y nunca asumas una forma de éxito para estados que no sean 2xx.

Si prefieres una biblioteca de cliente configurada para HiAPI, la carga útil enviada es exactamente la misma; solo cambia el lugar desde el que se llama.

Pasar imágenes de referencia correctamente

Las imágenes de referencia deben proporcionarse dentro del contenido del mensaje, no como un campo temporal de nivel superior. Esta es la parte de la integración más propensa a errores sutiles, porque una referencia mal formada a menudo no produce error: la solicitud simplemente tiene éxito y la salida ignora tu imagen.

Mantén la estructura de la carga útil coherente entre lenguajes: el mensaje de user lleva el arreglo de contenido, donde la parte de texto contiene el prompt y la parte de imagen lleva los datos de referencia. El mismo cuerpo de solicitud JSON que construyes en Python debe poder expresarse byte a byte en curl; si no puedes escribir el equivalente en curl de tu carga útil de Python, la estructura se ha desviado.

Cuando el resultado parezca ignorar tu imagen de referencia, comprueba en este orden:

1. Ubicación. ¿La parte de imagen está dentro de messages[].content o se ha filtrado al nivel superior del cuerpo de la solicitud? El modelo solo ve lo que está en los mensajes.
2. Codificación. La imagen de referencia se transmite en la solicitud como datos codificados. Confirma que los datos están completos y bien formados, y que no se han truncado por una concatenación manual o un copiar y pegar descuidado.
3. Acoplamiento con el prompt. La imagen de referencia guía la generación; no sustituye a las instrucciones. Indica explícitamente qué papel desempeña la imagen (estilo, composición, sujeto) en lugar de suponer que el modelo lo deducirá.
4. Tamaño. Las referencias muy grandes inflan la solicitud y ralentizan el viaje de ida y vuelta. Redúcelas al tamaño que la tarea realmente necesita antes de codificarlas.

Un hábito de depuración práctico

Construye una vez la carga útil con imagen de referencia, guarda el cuerpo de solicitud JSON exacto que funciona y reutilízalo como muestra fija. Cuando más adelante una llamada se comporte de forma anómala, compara el cuerpo actual con la muestra fija mediante un diff. La mayoría de las regresiones con imágenes de referencia son estructurales y un diff las encuentra en segundos.

Manejar errores, tiempos de espera y reintentos

Los endpoints de imagen fallan de forma distinta a los de texto: son más lentos, por lo que más llamadas caen en la ventana que activa el tiempo de espera, y reintentar a ciegas cuesta más porque el trabajo es más pesado.

Distinguir errores de cliente de fallos transitorios

• 4xx (excepto 429): carga útil mal formada, ID de modelo incorrecto, autenticación ausente. Reintentar la misma solicitud fallará igual. Corrige la solicitud.
• 401/403: problemas de credenciales. Revisa la clave y el formato de la cabecera Authorization.
• 429: limitación de tasa. Reintenta, pero con retroceso exponencial y jitter, no de inmediato.
• 5xx y errores de conexión: transitorios. Reintenta.
• Tiempo de espera de lectura: ambiguo: puede que la generación ya se haya completado en el servidor. Trata el tiempo de espera como reintentable solo si tu flujo de trabajo tolera posibles duplicados.

Reintentar solo lo que es seguro

Usa retroceso exponencial con jitter y fija un límite pequeño al número de intentos; tres suele ser suficiente. Un patrón sencillo:

import time, random

def post_with_retry(session, url, payload, attempts=3):
    for i in range(attempts):
        try:
            r = session.post(url, json=payload, timeout=(10, 180))
            if r.status_code == 429 or r.status_code >= 500:
                raise RuntimeError(f"retryable: {r.status_code}")
            r.raise_for_status()
            return r.json()
        except (RuntimeError, requests.ConnectionError, requests.Timeout):
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.random())

No reintentes errores de carga útil 4xx dentro de este bucle; expónlos de inmediato para que una solicitud incorrecta falle de forma ruidosa en lugar de desperdiciar intentos.

Dimensionar el tiempo de espera según el modelo

El tiempo de espera de lectura que asignes a las llamadas de imagen debe ser varias veces el valor predeterminado de texto, y debe establecerse por llamada en lugar de globalmente, para que el tráfico de texto no se vea penalizado. Si tu plataforma tiene un límite estricto de solicitudes, mantén los prompts de generación y las imágenes de referencia dentro de un presupuesto que puedas cumplir realmente.

Lista de verificación de producción antes del lanzamiento

Una lista breve que previene la mayoría de los incidentes:

• El ID del modelo en un solo lugar. Define gpt-image-2.5-sunburst/text-to-image como constante o valor de configuración, no como literales de cadena dispersos.
• La clave desde una variable de entorno, nunca confirmada en el repositorio. Rótala como cualquier otro secreto.
• Tiempos de espera explícitos, con una ventana de lectura amplia, establecidos en la solicitud y no en los valores predeterminados de la sesión.
• Reintentar solo en 429/5xx/tiempos de espera, con retroceso y jitter, y con un límite de intentos.
• Registrar la respuesta completa cuando haya fallos: estado, cuerpo de la respuesta e ID de la solicitud antes de analizarla, para que la conversación con soporte empiece con evidencia.
• Guardar muestras fijas de cargas útiles que funcionan, que cubran el caso normal y el caso con imagen de referencia, para compararlas con un diff cuando cambie el comportamiento.
• Las imágenes de referencia dentro del contenido del mensaje, reducidas según la tarea y con su papel indicado en el prompt.
• Una prueba de humo en CI que haga una llamada real al ID del modelo, para que un modelo renombrado o retirado se detecte antes de que lo hagan los usuarios.

Ninguno de estos hábitos es exclusivo de la generación de imágenes, pero cada uno apunta a un modo de fallo que las llamadas de imagen encuentran con más frecuencia que las de texto. Configúralos una vez y el endpoint funcionará como el resto de tu stack. Para conocer los parámetros y límites actuales del modelo, consulta la página del modelo en HiAPI antes de finalizar tu configuración.