Blog

Tutorial

Cómo llamar a gpt-image-2.6-flare/text-to-image mediante la API de HiAPI: curl, Python y una solicitud funcional

Nov 10, 2026
Portada abstracta con láminas de vidrio translúcido superpuestas que transforman un campo pálido en franjas de azul frío, acabado mate y arquitectónico, sin texto.
En esta página

Qué construye este tutorial

La mayoría de los tutoriales de texto a imagen se detienen en una captura de pantalla de una respuesta exitosa. Eso no es suficiente para poner nada en producción. Este tutorial te lleva desde cero hasta establecer una integración reutilizable y funcional mediante la API unificada de HiAPI y el modelo gpt-image-2.6-flare/text-to-image.

Al terminar tendrás tres cosas:

  • Una solicitud confirmada que funciona, presentada primero como comando curl y luego como un script Python equivalente.
  • Un modelo mental claro de cómo HiAPI organiza las llamadas de texto a imagen —la ruta del endpoint, la cabecera de autenticación, la carga del prompt y el cuerpo de la respuesta— para que puedas adaptar el ejemplo a tus propios prompts en lugar de memorizarlo.
  • Patrones para ampliar esa llamada única a un procesamiento por lotes, y un método para determinar qué fallos deben reintentarse y cuáles deben corregirse.

Mantendremos el código conciso y con mínimas dependencias. El ejemplo de Python usa solo la biblioteca estándar, así que puedes ejecutarlo en cualquier entorno con Python instalado; una vez que domines la estructura de la solicitud, adáptalo a requests o a un cliente asíncrono. Si quieres ir directamente a una llamada funcional, salta a la sección de curl y vuelve después a leer las explicaciones.

Requisitos previos y credenciales

Antes de tu primera llamada, confirma que cuentas con lo siguiente:

  1. Una cuenta de HiAPI. Inicia sesión en el panel para generar y gestionar credenciales.
  2. Una clave de API. Créala en la sección de claves de API del panel. Trátala como una contraseña: autoriza cada solicitud que se factura a tu cuenta.
  3. Una forma de enviar solicitudes HTTP. Ya sea un shell con curl instalado, o Python 3 con su biblioteca estándar (urllib y json vienen incluidos con Python).

Gestionar la clave mediante variables de entorno

Nunca pegues la clave directamente en un archivo fuente que se vaya a confirmar en el repositorio. En su lugar, expórtala en el shell:

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

En Windows PowerShell, usa $env:HIAPI_API_KEY = "your-api-key-here". En CI, inyéctala como secreto. En un servicio de larga duración, cárgala al iniciar desde un gestor de secretos.

Saber dónde está la URL base

HiAPI ofrece una única superficie de API unificada, por lo que la URL base se mantiene estable entre modelos. Guárdala en un valor de configuración —una variable de entorno es adecuada— en lugar de dispersarla por el código. Así, cambiar entre preproducción y producción, o apuntar las pruebas a un servidor simulado, requiere cambiar solo una línea.

El identificador de modelo que vas a llamar es gpt-image-2.6-flare/text-to-image. Ten en cuenta que contiene una barra diagonal; mantén el identificador completo y colócalo en la posición de la ruta que espera el constructor de solicitudes, exactamente como se muestra en el ejemplo siguiente.

Con la clave exportada y la URL base registrada, ya puedes revisar la solicitud en sí.

Anatomía de una solicitud de texto a imagen

Cada llamada de texto a imagen de HiAPI tiene los mismos cuatro componentes. Una vez que los entiendas, cambiar de modelo o de prompt se vuelve mecánico.

1. La ruta del endpoint

La solicitud incluye el identificador de modelo como parte de la ruta: gpt-image-2.6-flare/text-to-image, añadido después de tu URL base. Esta es la dirección que enruta tu llamada al modelo correcto detrás de la interfaz unificada.

2. La cabecera de autenticación

La autenticación es un token bearer en la cabecera Authorization:

Authorization: Bearer $HIAPI_API_KEY

Cada solicitud debe incluir esta cabecera. Su ausencia o un formato incorrecto es la causa más común de fallos en la primera llamada.

3. El cuerpo de la solicitud

Una llamada de texto a imagen es un POST con un cuerpo JSON. El núcleo es el prompt: la descripción en lenguaje natural de la imagen que deseas. El cuerpo también incluye ajustes de generación. Como HiAPI normaliza la estructura de las solicitudes entre modelos, puedes reutilizar el constructor de solicitudes y cambiar el identificador de modelo cuando quieras comparar salidas.

4. El cuerpo de la respuesta

Una respuesta exitosa devuelve la imagen generada (o una referencia a ella) junto con metadatos sobre la generación. Tu cliente debe comprobar el estado HTTP antes de intentar analizar la imagen. Trata la respuesta como datos, no como algo para mirar a simple vista; para la automatización necesitas los bytes o la URL de la imagen, y necesitas almacenar cualquier identificador de solicitud junto con ellos para poder relacionar el archivo con la llamada que lo produjo.

Ese es todo el modelo. Todo lo que sigue son instanciaciones concretas de estas cuatro partes.

Enviar una solicitud funcional con curl

Esta es la llamada completa. Sustituye el prompt por tu propio texto y ejecútala:

curl -X POST "$HIAPI_BASE_URL/gpt-image-2.6-flare/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A quiet library at dusk, warm lamp light, deep shadows, cinematic"
  }' \
  --output response.json

Explicación línea por línea:

  • -X POST: la generación es una llamada que modifica el estado, por lo que se usa POST.
  • URL: la URL base de la variable de entorno, seguida del identificador de modelo y /text-to-image. Las comillas evitan que el shell malinterprete caracteres especiales.
  • Authorization: Bearer ...: la credencial. La forma $HIAPI_API_KEY evita que la clave literal aparezca en el historial del shell.
  • Content-Type: application/json: indica al servidor que analice el cuerpo de la solicitud como JSON. Omitirla es una causa común de errores 4xx confusos.
  • -d '{...}': la carga JSON. El campo prompt es el que cambiarás con más frecuencia; añade ajustes de generación aquí mientras optimizas la salida.
  • --output response.json: escribe el cuerpo de la respuesta en un archivo para que una carga de imagen binaria no inunde la terminal. Ábrelo, o procésalo con jq si la respuesta está codificada en JSON.

Verificación rápida de sanidad

Si el comando vuelve rápidamente y response.json no está vacío, tienes una integración funcional. Si en su lugar obtienes un 4xx, revisa el cuerpo de la respuesta: HiAPI devuelve errores descriptivos, y la sección de manejo de errores a continuación cubre los sospechosos habituales.

Una vez que esto funcione, guarda el comando en un script de shell junto al proyecto. Es la forma más rápida de probar cambios de credenciales o confirmar si un fallo está de tu lado.

Enviar la misma solicitud con Python

La llamada de curl se traduce directamente a Python. Este script usa solo la biblioteca estándar, lee la clave de las variables de entorno y escribe la respuesta de imagen en disco:

import json
import os
import urllib.error
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
MODEL = "gpt-image-2.6-flare/text-to-image"

def generate_image(prompt: str, settings: dict | None = None) -> bytes:
    payload = {"prompt": prompt}
    if settings:
        payload.update(settings)

    request = urllib.request.Request(
        f"{BASE_URL}/{MODEL}",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    try:
        with urllib.request.urlopen(request, timeout=120) as response:
            return response.read()
    except urllib.error.HTTPError as exc:
        detail = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc

if __name__ == "__main__":
    body = generate_image("A quiet library at dusk, warm lamp light, deep shadows, cinematic")
    with open("output.bin", "wb") as f:
        f.write(body)
    print(f"wrote {len(body)} bytes")

Algunas decisiones intencionadas:

  • Tiempo de espera amplio. La generación de imágenes es más lenta que la completación de texto; un límite de 120 segundos evita bloqueos indefinidos y a la vez tolera llamadas lentas pero exitosas.
  • La función devuelve bytes, no una ruta. Esto la hace reutilizable: puedes subir los bytes a un almacenamiento de objetos o devolverlos desde un controlador web.
  • Los errores se envuelven junto con el cuerpo de la respuesta. Cuando algo falla, el mensaje te dice qué dijo el servidor, no solo el código de estado.
  • El constructor de carga acepta ajustes opcionales. Cuando añadas parámetros de generación, amplía el diccionario settings en lugar de codificarlos de forma fija en la función.

Después de exportar las dos variables de entorno, ejecútalo con python generate.py. Si prefieres requests, sustituye la construcción de la solicitud por requests.post(url, json=payload, headers=headers); la estructura es idéntica.

Patrones de procesamiento por lotes y concurrencia

Un prompt es una demostración; muchos prompts son trabajo real. Este cambio introduce dos problemas: rendimiento y depurabilidad.

Iterar prompts desde un archivo

Coloca los prompts en un archivo separado por saltos de línea o en un arreglo JSON. Asigna un ID a cada prompt (slug, índice o hash) y nombra el archivo de salida con ese ID. Cuando termine un lote de cientos de imágenes, podrás relacionar cada archivo con su prompt sin adivinar.

prompts = [
    ("lib-001", "A quiet library at dusk, warm lamp light, cinematic"),
    ("lib-002", "A lighthouse in fog, long exposure, muted palette"),
]
for prompt_id, text in prompts:
    body = generate_image(text)
    with open(f"out/{prompt_id}.bin", "wb") as f:
        f.write(body)

Controlar la concurrencia de forma explícita

Las llamadas de generación están dominadas por E/S, por lo que la concurrencia ayuda al rendimiento; pero la concurrencia ilimitada activa los límites de velocidad y te hunde en errores. Empieza en serie, mide el tiempo de una sola llamada y luego aumenta la concurrencia con un grupo de trabajo acotado. Un grupo de hilos simple con un número pequeño y fijo de hilos de trabajo (de cuatro a ocho al principio) suele ser suficiente.

Para tareas más grandes, usa un cliente asíncrono o una cola con hilos de trabajo. La disciplina clave es la misma: paralelismo acotado, un archivo de salida por ID de prompt y una línea de registro por solicitud con ID, estado y duración.

Conservar un manifiesto

Durante la ejecución del lote, escribe un pequeño manifiesto JSON que registre cada ID de prompt y su resultado. Si el proceso muere a mitad de camino, el manifiesto te dice desde dónde reanudar en lugar de volver a facturar el lote completo. Esta práctica ahorra más tiempo que cualquier optimización inteligente.

Manejo de errores y reintentos

Los fallos se dividen en dos categorías: los que corriges y los que reintentas. Confundirlos pierde tiempo y, en una tormenta de reintentos, también dinero.

Corrige estos

  • 401 / 403: autenticación. La clave falta, ha caducado o carece de permisos de acceso. Comprueba que HIAPI_API_KEY esté realmente exportada en el shell que ejecuta el comando; una trampa común es exportarla en una terminal y ejecutar el script en otra.
  • 400: carga mal formada. JSON inválido, falta de prompt o tipos de campo inesperados. El cuerpo del error suele señalar el campo problemático. Cuida las comillas de tu JSON en la llamada de curl.
  • 404: ruta incorrecta. Verifica que el identificador de modelo esté escrito exactamente como en la documentación y que tu URL base no tenga segmentos de ruta duplicados o faltantes.

Reintenta estos, con retroceso

  • 429: límite de velocidad. Reduce la velocidad. Respeta cualquier indicación de retry-after de la respuesta y usa un retroceso exponencial con jitter. A largo plazo, limita tu concurrencia.
  • 5xx: error del servidor. Suele ser transitorio. Reintenta un número limitado de veces (tres es un valor predeterminado razonable), con un retraso creciente, y luego falla de forma ruidosa.

Un envoltorio de reintentos mínimo

import random, time

def with_retries(fn, attempts=3):
    for i in range(attempts):
        try:
            return fn()
        except RuntimeError as exc:
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.uniform(0, 0.5))

Úsalo para envolver generate_image. La clave es hacer la operación idempotente de tu lado: como los archivos de salida se nombran con el ID de prompt, un reintento sobrescribe en lugar de duplicar. Registra cada fallo junto con el ID de prompt y el mensaje del servidor; cuando realmente necesites escalar, ese registro es exactamente lo que el equipo de soporte necesita para reproducir el problema.

Siguientes pasos

Ahora tienes una solicitud funcional, una función Python que vale la pena conservar y patrones para ejecutarla a escala. Para reforzarla para producción, añade registro estructurado con IDs de solicitud, persiste el manifiesto en un almacenamiento duradero para que los trabajos por lotes se recuperen tras un fallo y valida los prompts antes de enviarlos, para que las entradas mal formadas fallen rápida y económicamente.

El siguiente paso más útil es reutilizar este mismo cliente con otros modelos de la API de HiAPI. Como la ruta del endpoint, las cabeceras de autenticación y la estructura de la carga son compartidas, adaptar el script a un nuevo modelo suele significar cambiar el identificador de modelo y, ocasionalmente, uno o dos ajustes: un pequeño cambio de código puede producir salidas significativamente distintas.

Empieza con un prompt, confirma la generación del archivo y luego deja que el ejecutor por lotes se encargue del resto.

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