Blog

Tutorial

Cómo llamar a flux-2/text-to-image mediante la API de HiAPI: tutorial con curl y Python

Ejercicio de solicitud funcional: identificador de modelo, prompt y parámetro de relación de aspecto, campos de respuesta y manejo de errores

Nov 12, 2026
Imagen de portada: sobre un fondo índigo profundo, flechas anchas anidadas en capas avanzan sucesivamente hacia la derecha, con el borde frontal en naranja albaricoque, planas y precisas como un diagrama de flujo de señales.
En esta página

Qué expone flux-2/text-to-image a través de la API

Antes de escribir la primera línea de código, conviene tener claro a qué te estás conectando. En HiAPI, flux-2/text-to-image no es un SDK independiente que debas instalar ni un servicio nuevo con autenticación propia. Es un identificador de modelo que se pasa, junto con el prompt que describe la imagen que deseas, al endpoint compartido de generación de imágenes.

Este modelo mental importa porque delimita el alcance de la integración. Tu código necesita tres cosas:

  • Credenciales de autenticación para la API de HiAPI.
  • El endpoint que acepta solicitudes de generación de imágenes.
  • Una carga útil JSON que contenga model (establecido en flux-2/text-to-image) y prompt.

Todo lo demás —la relación de aspecto, las preferencias de salida y cualquier otro ajuste que exponga el modelo— existe como campos adicionales dentro de esa carga útil. Por eso cambiar de otro modelo de texto a imagen a flux-2/text-to-image suele requerir solo modificar una línea de configuración, en lugar de reescribir el código: el sobre de la solicitud se mantiene y solo cambia el valor de model.

El endpoint recibe tu solicitud, la ejecuta a través del modelo y devuelve una respuesta estructurada que contiene la imagen generada (normalmente una URL o una carga codificada) junto con metadatos del trabajo. Para una llamada básica no necesitas consultar una cola de trabajos separada: desde la perspectiva del cliente, el ciclo de solicitud y respuesta es síncrono, pero la generación subyacente sigue llevando tiempo, así que el tiempo de espera de tu cliente HTTP debería ser generoso.

Quédate con esta idea: un endpoint, una carga útil, una cadena de modelo. El resto de este tutorial rellenará la carga útil y reforzará la llamada.

Construir una solicitud funcional con curl

La forma más rápida de confirmar que las credenciales y la estructura de la carga útil son correctas es una llamada con curl. Consigue una respuesta exitosa en la terminal antes de pasar a Python: esto aísla los problemas de autenticación y de carga útil de los errores propios del lenguaje.

Primero, define la clave como variable de entorno para que no quede en texto plano en el historial del shell:

export HIAPI_API_KEY="your_api_key_here"

Después envía la solicitud:

curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "prompt": "a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
    "aspect_ratio": "16:9"
  }'

Puntos a revisar al ejecutar:

  • El endpoint y la clave provienen del panel de tu cuenta de HiAPI. Copiar el endpoint desde el panel en lugar de volver a escribirlo evita el fallo silencioso más común: que la solicitud se envíe a un lugar inesperado.
  • -sS mantiene la salida limpia, pero sigue mostrando errores de nivel de curl, como fallos de DNS o TLS.
  • La cabecera Authorization usa el esquema bearer estándar. No debe haber espacios finales ni comillas alrededor de la expansión de la variable.
  • Content-Type: application/json es obligatorio; sin él, el cuerpo puede rechazarse antes de que el modelo lo vea.

Si la llamada tiene éxito, verás el cuerpo JSON de la respuesta en la terminal. Pásalo por un formateador para mejorar la legibilidad:

curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-2/text-to-image","prompt":"a red fox in fresh snow, eye level","aspect_ratio":"1:1"}' \
  | python3 -m json.tool

Cuando esto funcione, tendrás una línea base que sabes que funciona. Cualquier fallo posterior en Python podrá compararse con esta llamada que confirmaste como válida.

El prompt y el parámetro de relación de aspecto

Hay dos campos de la solicitud que más influyen en la salida: prompt y aspect_ratio. Ajusta solo uno a la vez; de lo contrario, no podrás saber cuál de los dos provocó el cambio que observas.

Prompt

El prompt es la descripción en lenguaje natural de la imagen. Escríbelo como una descripción compacta de la escena, no como una lista de palabras clave: aproximadamente en el orden de sujeto, escenario, iluminación y composición. Compara:

  • Vago: a lighthouse
  • Concreto: a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot

Mantén la redacción explícita y estable durante la experimentación. Si reescribes el prompt y la relación de aspecto en la misma iteración, tendrás dos variables y una sola observación. Congela el prompt, ajusta una palabra a la vez y registra el cambio real.

Hábitos prácticos:

  • Coloca el sujeto más importante al principio de la cadena.
  • Describe la iluminación y la atmósfera con palabras concretas, no abstractas.
  • Mantén un pequeño conjunto de prompts de referencia en tu base de código y vuelve a ejecutarlos cada vez que cambies cualquier otra cosa, para poder distinguir un cambio de comportamiento del modelo de un cambio en el prompt.

Relación de aspecto

aspect_ratio controla la forma de la salida: panorámica para paisajes y banners, cuadrada para avatares y miniaturas, vertical para pósteres y diseños móviles. El modelo acepta cadenas de proporción como 16:9, 1:1 o sus equivalentes verticales; usa las proporciones documentadas para el modelo, no inventes otras.

Como la relación de aspecto es un único campo discreto, es el parámetro más fácil de explorar. Escribe un bucle que mantenga el prompt fijo y solicite la misma imagen en tres proporciones, y luego compara las composiciones en paralelo. Pronto sabrás qué proporciones recortan el sujeto y cuáles le dan espacio.

Una advertencia: la relación de aspecto cambia la composición efectiva, no solo el lienzo. Un prompt escrito para una toma panorámica puede quedar escaso en un encuadre cuadrado. Una vez que decidas la proporción, revisa el prompt una vez para compensarlo.

Trasladar la llamada a Python

La llamada con curl se traduce directamente a Python. El objetivo es escribir una función pequeña que reciba el prompt y la relación de aspecto, lea la clave del entorno y devuelva el JSON analizado: una forma apta para producción, no un script desechable.

import os
import requests

IMAGE_ENDPOINT = os.environ["HIAPI_IMAGE_ENDPOINT"]
MODEL = "flux-2/text-to-image"


def generate_image(prompt: str, aspect_ratio: str = "1:1", timeout: int = 120) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # fail fast if unset
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "aspect_ratio": aspect_ratio,
    }
    response = requests.post(
        IMAGE_ENDPOINT,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()

Notas sobre por qué está escrito así:

  • Usa variables de entorno, no literales. os.environ[...] lanza un KeyError inmediatamente si falta la variable, lo cual es mucho mejor que enviar un token bearer vacío y luego tener que descifrar un error de autenticación confuso.
  • json=payload hace que requests serialice el cuerpo y establezca Content-Type por ti. No construyas cadenas JSON a mano.
  • Tiempo de espera explícito. La generación de imágenes no es instantánea; el tiempo de espera predeterminado del cliente te dará problemas bajo carga. Establécelo a propósito.
  • raise_for_status() convierte las respuestas que no son 2xx en excepciones que puedes capturar y clasificar, en lugar de devolver silenciosamente un cuerpo de error que parece datos.

Llámalo así:

result = generate_image(
    "a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
    aspect_ratio="16:9",
)
print(result)

Si prefieres httpx, la forma es idéntica: cambia la importación y conserva las mismas cabeceras, la carga útil con json= y el parámetro de tiempo de espera. Lo importante es la carga útil, que permanece igual que en la versión con curl.

Leer la respuesta

Una llamada exitosa devuelve un objeto JSON. En lugar de adivinar los nombres de los campos, inspecciona primero una respuesta real y luego escribe el analizador según lo que veas realmente. Ejecuta tu función e imprime las claves de nivel superior:

result = generate_image("a red fox in fresh snow, eye level", "1:1")
print(result.keys())

Los campos que normalmente usarás se dividen en dos grupos:

  • La imagen en sí. La respuesta incluye la imagen generada, normalmente una URL que puedes descargar o servir, y a veces datos de imagen codificados. Lee el nombre exacto del campo en tu propia respuesta, guarda ese valor y procésalo según su forma. Si es una URL, trátala como de corta duración: descárgala o cópiala a tu propio almacenamiento a tiempo, en lugar de guardar el enlace en una base de datos y asumir que seguirá resolviéndose el mes que viene.
  • Metadatos. Espera campos acompañantes que describan la generación: el modelo usado, la relación de aspecto o el tamaño solicitados y un identificador de la solicitud. Regístralos junto con la imagen. Cuando un usuario informe de que una imagen "no se ve bien", los metadatos te dirán qué prompt y qué proporción la produjeron sin que tengas que reconstruirlo desde el estado de la aplicación.

Un patrón de extracción seguro:

image_ref = result.get("image") or result.get("data")
if not image_ref:
    raise ValueError(f"no image in response; keys={list(result.keys())}")

Esto es deliberadamente defensivo. Los nombres de los campos son estables dentro del modelo, pero escribir el acceso de forma que falle de manera ruidosa mostrando la lista real de claves evita que un None silencioso se propague a tu interfaz. Una vez confirmados los nombres de los campos a partir de una respuesta real, ajusta el código para leerlos directamente.

Por último, no descartes la respuesta sin procesar. Guárdala (o registra en un log parte de las solicitudes) hasta que tu integración se estabilice: es la fuente de verdad cuando algo falla más adelante.

Errores comunes y cómo solucionarlos

La mayoría de los fallos en la primera ejecución pertenecen a unas pocas categorías. Gestiónalos por clase de estado HTTP, no comparando el texto del mensaje, que cambia sin aviso.

Fallos de autenticación (401 / 403)

Falta la clave, tiene un formato incorrecto o carece de permiso de acceso. Comprueba en orden: si HIAPI_API_KEY está realmente definida en el entorno que ve tu proceso; si la cabecera es exactamente Authorization: Bearer <key>, sin espacios adicionales ni comillas envolventes; y si enviaste por accidente una clave de un entorno distinto. Si curl funciona y Python no, imprime la cabecera que envías y compárala carácter por carácter.

Carga útil mal formada (400)

El cuerpo se rechaza antes de la generación. Causas habituales: JSON inválido (cadenas construidas a mano con comas finales), falta de prompt o un Content-Type incorrecto. La solución es usar json=payload en Python y -d con JSON válido en curl. Muestra en el log la carga útil que estás a punto de enviar y léela como lo haría una persona.

Parámetros no admitidos o inválidos (400 / 422)

Nombres de campo o valores que el modelo no acepta: un aspect_ratio mal escrito, una proporción no documentada para el modelo o un campo adicional copiado del ejemplo de otro modelo. Reduce la carga útil al mínimo (model, prompt) y luego añade los campos uno a uno para localizar el problema.

Límite de velocidad (429)

Estás enviando solicitudes más rápido de lo que permite el límite de tu cuenta. Es temporal. No reintentes en un bucle apretado: usa retroceso exponencial con un límite de intentos. Si procesas por lotes, añade una pequeña pausa entre llamadas en lugar de enviarlas todas de golpe.

Errores del servidor (5xx) y tiempos de espera

Son temporales y están fuera de tu control. Reintenta con retroceso y asegúrate de que el tiempo de espera sea lo bastante largo para que una generación lenta no se clasifique erróneamente como fallo. Un tiempo de espera de lectura que se dispara mientras el modelo sigue trabajando genera un reintento que desperdicia una solicitud.

Mantener la clasificación en un solo lugar facilita el mantenimiento:

def classify(status: int) -> str:
    if status in (401, 403):
        return "auth"        # fix config, do not retry
    if status in (400, 422):
        return "payload"     # fix request, do not retry
    if status == 429:
        return "rate_limit"  # retry with backoff
    if status >= 500:
        return "server"      # retry with backoff
    return "other"

Encapsular la llamada para producción

La función anterior funciona, pero una integración real necesita tres cosas que aún no tiene: reintentos que distingan fallos temporales de permanentes, tiempos de espera que reflejen la realidad y logs que te permitan reconstruir lo ocurrido. Un pequeño envoltorio cubre las tres.

import logging
import time

log = logging.getLogger(__name__)

def generate_with_retry(prompt, aspect_ratio="1:1", attempts=3):
    delay = 1.0
    for attempt in range(1, attempts + 1):
        try:
            return generate_image(prompt, aspect_ratio)
        except requests.HTTPError as exc:
            status = exc.response.status_code
            kind = classify(status)
            log.warning("flux-2 call failed", extra={
                "attempt": attempt, "status": status,
                "kind": kind, "aspect_ratio": aspect_ratio,
            })
            if kind in ("auth", "payload"):
                raise  # retrying will not help
            if attempt == attempts:
                raise
            time.sleep(delay)
            delay *= 2

Por qué cada parte aporta valor:

  • Reintenta solo lo que se puede reintentar. Los errores de autenticación y de carga útil son deterministas: reintentarlos pierde tiempo y oculta el bug real. Los límites de velocidad, los errores del servidor y los tiempos de espera obtienen retroceso exponencial.
  • Registra campos estructurados, no prosa. El número de intento, el estado, la clase de error y los parámetros usados te permiten agrupar fallos después. Nunca registres la clave de la API.
  • Limita el número de intentos. Un bucle de reintentos sin límite convierte un fallo en un proceso de trabajo colgado.
  • Mantén el tiempo de espera explícito y holgado. Pásalo desde la configuración para poder aumentarlo en las franjas lentas conocidas sin tocar el código.

Otros dos hábitos que rinden: guardar un hash de (model, prompt, aspect_ratio) por cada imagen generada, para poder reproducir cualquier salida; y mantener un pequeño conjunto de prompts de referencia en el conjunto de pruebas, ejecutándolos después de cualquier cambio en el envoltorio. Juntos convierten un fragmento de tutorial en algo operable.

Con la forma de la solicitud fijada y el manejo de errores en su sitio, cambiar de modelo más adelante solo requiere una línea en el campo model: exactamente el sentido de llamar a flux-2/text-to-image a través de una interfaz unificada.

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