Cómo usar flux-1.1-pro a través de la API de HiAPI: curl, Python y solicitudes ejecutables

Qué ofrece flux-1.1-pro antes de que escribas código

flux-1.1-pro es un modelo de texto a imagen que se invoca a través de HiAPI.ai como endpoint alojado. Envías el prompt y los parámetros de generación en formato JSON, y lo que devuelve es la imagen generada. No hay nada que instalar, no necesitas alojar los pesos tú mismo ni administrar recursos de GPU. Tu superficie de integración es un endpoint HTTP, más las credenciales para la autenticación.

Para un desarrollador, esto significa que antes de escribir la primera línea de código hay tres cosas que condicionan tu diseño.

Primero, la solicitud es JSON de entrada e imagen de salida. Tu prompt, la relación de aspecto y unos pocos parámetros de control van en el cuerpo de la solicitud. La respuesta transporta los datos de la imagen o una referencia a ellos, según cómo se entregue la tarea. Trata el cuerpo de la solicitud como un contrato y centralízalo en un solo lugar, de modo que las rutas de curl y Python nunca se desvíen entre sí.

Segundo, en comparación con una llamada API normal, la generación de imágenes es una operación lenta. Unos segundos es lo normal; los prompts complejos a alta resolución pueden tardar más. Cualquier cliente en producción debe asumir que hay latencia y planificarla, en lugar de tratar la llamada como una lectura de base de datos.

Tercero, la calidad de la salida la determina principalmente el prompt, no el cableado. La integración es la parte sencilla. El verdadero esfuerzo está en describir con precisión lo que quieres y validar tu receta con salidas reales antes de salir a producción.

Con estas tres cosas en mente, el resto de esta guía es un proceso mecánico: construir la solicitud, confirmar que funciona, portarla y luego endurecerla y ajustarla. De principio a fin, todo se enruta a través de la API de HiAPI: una credencial, una URL base, una estructura JSON que aprender.

Tu primera solicitud curl

Empieza con curl. Elimina todas las capas de abstracción entre tú y el endpoint, de modo que cuando algo falle tengas claro que el problema está en tu cuerpo de solicitud, no en tu framework.

Una llamada mínima tiene tres partes: el endpoint, la cabecera de autenticación y el cuerpo JSON.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1.1-pro",
    "prompt": "a ceramic coffee mug on a weathered wooden table, soft morning window light, shallow depth of field, product photography",
    "aspect_ratio": "1:1"
  }'

Lee el cuerpo de la solicitud campo por campo:

• model especifica el modelo que vas a usar. Escríbelo explícitamente, para que un cambio futuro en los valores predeterminados nunca altere silenciosamente tu salida.
• prompt es la descripción en lenguaje natural. Aquí está casi todo tu presupuesto de calidad.
• aspect_ratio controla el encuadre. Elígelo de forma deliberada, en lugar de confiar en un valor predeterminado que no hayas verificado.

Coloca la clave en una variable de entorno (HIAPI_API_KEY) en lugar de pegarla directamente en el comando. Este hábito se traslada directamente a Python y a cualquier paso de CI que añadas después.

Si la llamada tiene éxito, obtendrás una respuesta JSON que describe la imagen completada. Antes de cerrar la terminal, revísala y localiza la referencia o los datos de la imagen. Si la llamada falla, obtendrás un cuerpo de error con un código de estado y un mensaje; lee el mensaje al pie de la letra, porque un formato de campo incorrecto es la causa más común de los primeros fallos.

Una advertencia que te ahorra una hora: no pegues en el shell prompts de varias líneas con comillas sin escapar. Para cualquier cosa más larga que una frase corta, usa un heredoc o un archivo.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

Ese request.json es el artefacto que deberías subir al repositorio. Es la única fuente de verdad del cuerpo de la solicitud, y la siguiente sección lo reutiliza tal cual.

Portar la misma llamada a Python

El objetivo de la portabilidad no es escribir lógica nueva, sino enviar exactamente el mismo cuerpo JSON. Carga el mismo request.json, de modo que ambas rutas no puedan desviarse.

import json
import os

import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"

with open("request.json") as f:
    payload = json.load(f)

response = requests.post(
    API_URL,
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

if response.status_code != 200:
    print(response.status_code)
    print(response.text)
    response.raise_for_status()

print(response.json())

Tres detalles importantes aquí.

La cabecera de autenticación es el mismo conjunto de cabeceras. Usar json=payload hace que requests serialice el cuerpo y establezca el tipo de contenido por ti; escribir la cabecera explícitamente no hace daño y deja constancia de la intención.

Establece un tiempo de espera. Nunca dejes una solicitud de generación colgada de un valor predeterminado sin límite. Un tiempo de espera explícito y holgado está bien: lo importante es que sea explícito.

Revisa el cuerpo del error antes de lanzar la excepción. Si ejecutas raise_for_status() primero, descartarás el cuerpo de la respuesta en tus registros. Imprime el código de estado y el texto y luego lanza la excepción. Cuando se rechace un campo, necesitarás ese texto.

Si estás unificando todo en un cliente HTTP asíncrono, la estructura no cambia: misma URL, mismas cabeceras, mismo cuerpo, solo que con await client.post(...) y el mismo tiempo de espera. El contrato del cuerpo es la constante; el cliente es un detalle de implementación.

Mantén el cuerpo de la solicitud fuera del código fuente de Python. Cuando una receta de prompt funciona, debería vivir en un archivo o en una fila de base de datos, no en un literal de cadena enterrado dentro de una función, para que puedas compararla con diferencias y volver a ejecutarla.

Manejar tareas asíncronas sin bloquear tu aplicación

Trata la generación como una tarea, no como una llamada a función. Ya sea que tu ruta de entrega parezca síncrona o devuelva una tarea que debes consultar, la consecuencia práctica es la misma: tu aplicación nunca debe ocupar un hilo de solicitud sin límite esperando una imagen.

Un patrón viable consta de cuatro pasos.

1. Envía desde un worker, no desde la solicitud del usuario

Acepta la acción de generación del usuario en la capa web, persiste un registro de la tarea, encólala y devuelve inmediatamente. Es un worker en segundo plano el que realiza la llamada real a la API. El usuario consulta tu endpoint, no el modelo.

2. Pon límite a la espera

Establece un tiempo de espera que elijas deliberadamente para cada intento. Si la plataforma devuelve una tarea que debes consultar, hazlo a intervalos fijos, con un número máximo de intentos y una fecha límite calculada desde el momento en que comenzó la tarea (no desde el número de intentos). Prefiere un retroceso moderado en lugar de un bucle apretado.

3. Reintenta solo los fallos que vale la pena reintentar

Para errores de transporte, tiempos de espera y fallos del servidor, reintenta con retroceso exponencial y jitter, limitado a un número reducido de intentos. No reintentes errores de validación: un campo rechazado o un prompt vacío fallarán de la misma forma cada vez, y reintentar solo hará que el usuario espere más antes de ver el mensaje real.

4. Haz idempotente la tarea de tu lado

Registra en la base de datos el cuerpo exacto de la solicitud y el ID de la tarea. Si tu worker se cae después de enviar pero antes de registrar el éxito, puedes volver a consultar esa tarea en lugar de reenviarla a ciegas. Cuando debas reenviarla, añade una breve clave de deduplicación del lado del cliente, para que un fallo transitorio no encolar tres veces la misma generación.

import time

def poll_until_done(fetch_status, job_id, deadline_seconds=180):
    start = time.monotonic()
    delay = 2.0
    while True:
        status = fetch_status(job_id)
        if status["state"] in ("succeeded", "failed"):
            return status
        if time.monotonic() - start > deadline_seconds:
            raise TimeoutError(f"generation {job_id} exceeded deadline")
        time.sleep(delay)
        delay = min(delay * 1.5, 10.0)

Este helper se mantiene deliberadamente genérico: recibe una función que obtiene el estado, de modo que el mismo bucle sirve para cualquier endpoint basado en tareas que integres después. Las propiedades importantes son la fecha límite, el retroceso acotado y la comprobación del estado terminal, no el transporte concreto.

Construir prompts que se rendericen de forma estable

Un prompt largo no es igual a un prompt mejor. La estructura es lo que importa. Un esqueleto repetible te da resultados consistentes y, cuando algo sale mal, un lugar donde cambiar una sola variable a la vez.

Usa cuatro ranuras en este orden:

1. Sujeto: qué hay en la imagen, con concreción. «Una taza de café de cerámica» es mejor que «algo para la cafetería».
2. Estilo: el tono visual: fotografía, ilustración, acuarela, renderizado 3D, fotografía de producto. Especifica el medio y, cuando sea útil, la iluminación.
3. Composición: encuadre y cámara: relación de aspecto, distancia de disparo, ángulo, profundidad de campo, posición del sujeto en el encuadre.
4. Restricciones: lo concreto que quieres y lo que no quieres, breve.

[subject] a single ceramic coffee mug, matte glaze, small handle
[style] product photography, soft diffused window light, muted palette
[composition] 1:1, eye-level, subject centered, shallow depth of field, plain background
[constraints] no text, no logos, no hands

Al enviarlo, aplánalo en un solo prompt; los corchetes son para ti, no para el modelo. El valor de escribir por ranuras es que, cuando la salida no es correcta, sabes qué ranura editar.

Algunas reglas prácticas:

• Pon el sujeto al principio. La primera cláusula es la que más pesa.
• Prefiere sustantivos y adjetivos concretos antes que palabras emocionales abstractas. «Esmalte mate» cambia píxeles; «sensación premium» básicamente no.
• Coloca el lenguaje de cámara en la ranura de composición, no en la del sujeto. Mezclarlos genera instrucciones ansiosas y contradictorias.
• Al iterar, cambia una sola ranura a la vez y conserva el texto exacto del prompt que produjo la salida aceptada.

La relación de aspecto es una decisión de composición, no un parche posterior. Elígela para que coincida con el lugar donde aparecerá la imagen —cuadrada para una cuadrícula, más alta para un banner principal— y adapta el resto del prompt a ese marco.

Usar eficazmente las listas de términos negativos

Una lista de términos negativos le dice al modelo qué evitar. Es una herramienta afilada, útil en un rango estrecho: excelente para suprimir defectos recurrentes, pero pésima como cajón de sastre donde enumeras todas las imperfecciones que se te ocurren.

Los términos negativos deben ser breves y concretos. Para la mayoría de los prompts, de cinco a ocho entradas cortas son suficientes. Escribe cosas concretas:

no text, no watermark, no logos, no extra fingers, no harsh shadows

Esta lista funciona porque cada entrada nombra algo visible y comprobable. Compárala con negaciones vagas como «not ugly» o «bad quality»: apenas aportan señal accionable y diluyen las entradas que realmente importan.

Donde los términos negativos realmente ayudan:

• Suprimir defectos que ves repetidamente. Si las manos o el texto aparecen una y otra vez, escribirlos explícitamente es la solución más directa.
• Higiene de marca y legal. Excluye logos y marcas de agua antes de que la imagen llegue a la interfaz de usuario.
• Forzar fondos limpios en imágenes de producto o cercanas a la UI.

Donde juegan en tu contra:

• Contradecir el prompt positivo. Un «sin sombras» en los negativos contra una «iluminación lateral dramática» en el sujeto es un conflicto que el modelo resolverá de forma impredecible. Corrige el prompt positivo.
• Negar cosas que probablemente no aparecerían. Una larga lista de fallos improbables solo añade ruido y no cambia el renderizado.
• Usar negativos para compensar un sujeto difuso. Si el sujeto no está claro, ninguna lista de negativos lo salvará.

Un detalle práctico: algunos clientes aceptan los términos negativos como campo separado en lugar de texto anexado. Confirma cuál de las dos formas admite tu solicitud y conserva ese campo en el cuerpo que guardas, para que curl y Python se comporten exactamente igual.

Recetas de prompts con salidas reales

Las recetas siguientes son puntos de partida, no garantías. El flujo honesto es: ejecutar la receta a través de tu propia integración, revisar la salida y luego ajustar una ranura. Cualquier salida que no hayas generado tú mismo debe considerarse no validada.

Receta 1: imagen de producto limpia

A single matte-black wireless earbud case on a light concrete surface,
studio product photography, soft key light from the left, 1:1, centered,
shallow depth of field, plain background. No text, no logos, no hands.

Características esperadas: sujeto claro y centrado, caída suave y un fondo sin desorden. Si la superficie parece demasiado recargada, aprieta «plain background» y elimina cualquier palabra de textura. Si la luz es demasiado plana, añade una palabra clave direccional, y nada más.

Receta 2: retrato editorial

Portrait of a person in a wool coat, natural window light, calm expression,
3:4, chest-up framing, subject slightly off-center, muted film palette.
No text, no watermark.

Características esperadas: luz direccional suave, color contenido. Si el encuadre resulta más amplio de lo esperado, adelanta «chest-up framing» y elimina palabras de composición que compitan.

Receta 3: ilustración isométrica

Isometric illustration of a small reading nook: armchair, floor lamp, bookshelf,
flat vector style, limited palette of warm neutrals and one accent color,
1:1, centered composition, clean white background. No text, no gradients.

Características esperadas: geometría clara y relleno plano. Si la paleta se desvía, especifica el color de acento y mantén «clean white background» como última cláusula, para que sea la que prevalezca.

Receta 4: banner principal

A wide misty mountain ridge at sunrise, layered depth, minimal detail,
16:9, subject occupying the lower third, generous empty sky for overlaid text.
No text, no watermark.

Características esperadas: una imagen tranquila, de bajo detalle, con espacio negativo utilizable. La expresión «overlaid text» reserva el espacio; no renderiza letras, y la lista de negativos mantiene el texto fuera de la imagen en sí.

Para cada receta, registra el cuerpo exacto de la solicitud, la relación de aspecto y la fecha. Al revisarlo un mes después, puedes volver a ejecutar el cuerpo registrado y comparar con la salida registrada, en lugar de adivinar por qué cambió el resultado.

Errores, límites y qué comprobar primero

Cuando una generación falla o la salida no es correcta, antes de tocar el código recorre esta lista de comprobación punto por punto.

Primero revisa el cuerpo de la solicitud

• ¿El cuerpo es JSON válido? Las comas finales o las comillas sin escapar son la causa más común de los primeros fallos. Valida tu request.json guardado antes de enviarlo.
• ¿Los nombres de los campos son exactamente correctos? Los parámetros mal escritos suelen rechazarse o ignorarse en silencio. Contrasta con la estructura de solicitud de la documentación, no con la memoria.
• ¿El nombre del modelo es correcto y existe? No confíes en los valores predeterminados.
• ¿El prompt no está vacío y está dentro de la longitud especificada en la documentación? La documentación de la plataforma indica los límites; léelos allí, no supongas un número.

Luego revisa la autenticación y el transporte

• ¿La clave API existe y es válida actualmente? Un 401 normalmente significa que falta la cabecera, está mal formada o que la clave se ha rotado.
• ¿La URL del endpoint y el método son correctos? Enviar un POST a una ruta GET falla con un aspecto similar a un problema de clave.
• ¿Tu tiempo de espera es demasiado ajustado? Si tu cliente abandona antes de que se complete la tarea, el tiempo de espera que ves no tiene que ver con el modelo.

Después revisa la estructura de la solicitud

• La clase del código de estado te indica dónde mirar. Un 4xx es casi siempre un problema de tu solicitud; un 5xx suele ser transitorio y merece un reintento acotado.
• Lee el mensaje de error al pie de la letra. Imprime el cuerpo de la respuesta antes de lanzar la excepción. El campo que menciona el mensaje es el campo que hay que corregir.
• Una respuesta de limitación de velocidad o cuota significa que debes bajar el ritmo y reintentar con retroceso, no reescribir el prompt.

Por último, revisa el prompt

Si la llamada tiene éxito pero la imagen no es la correcta, estás en el terreno del prompt, no en el del error:

• ¿Falta el sujeto o es demasiado genérico? Muévelo a la primera cláusula y hazlo concreto.
• ¿La composición es incorrecta? Corrige a la vez la relación de aspecto y las palabras de encuadre; no uses una para compensar la otra.
• ¿Los defectos se repiten? Añade un término negativo breve y concreto.
• ¿Hay contradicciones? Encuentra el término negativo que combate el prompt positivo y elimínalo.

Lo más importante es mantener un hábito: registra el cuerpo exacto de la solicitud, el estado de la respuesta y la referencia de la imagen generada para cada generación que te importe. La reproducibilidad convierte la depuración de una adivinanza en una comparación de diferencias. Construye tu primera solicitud, confirma la salida y luego aprieta el prompt antes de salir a producción; y conserva el cuerpo de la solicitud que usaste en producción, para que el próximo cambio tenga una base real con la que comparar.