FLUX 1.1 Pro para imágenes de productos de e-commerce: guía de la API de hiapi

Si vendes cosas online, ya conoces la cuenta: una página de detalle de producto necesita una foto sobre fondo blanco, una imagen de estilo de vida y, preferiblemente, una serie de ángulos múltiples; para cada SKU y cada color. Una sesión de estudio resuelve diez productos al día; una API de imágenes resuelve mil.

flux-1.1-pro (FLUX.1.1 [pro] de Black Forest Labs) es el caballo de batalla del fotorrealismo en hiapi: renderiza materiales convincentes —metal cepillado, vidrio, tela, bokeh suave— a un precio uniforme de $0.05 por imagen. Esta guía es una receta de e-commerce lista para usar: cada imagen a continuación se generó con el prompt impreso literalmente justo encima, mediante las mismas llamadas a /v1/tasks que puedes copiar y pegar, y documentamos los rangos de parámetros reales, incluidos los que parecen deberían existir pero devuelven 400 al enviarlos.

La API en 60 segundos

En hiapi, flux-1.1-pro se ejecuta en el endpoint de tareas asíncronas. Creas una tarea, la consultas por sondeo y descargas el resultado:

# 1. Create the task
curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1.1-pro",
    "input": {
      "prompt": "Studio packshot of an unbranded stainless steel wristwatch...",
      "aspect_ratio": "1:1",
      "output_format": "jpg",
      "seed": 6607
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01KWK3JG..."},"message":"success"}

# 2. Poll until status is "success" (typically 10–40s for flux-1.1-pro)
curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWK3JG... \
  -H "Authorization: Bearer $HIAPI_API_KEY"

# 3. Download output[0].url — it carries an expireAt timestamp,
#    so save the file to your own storage immediately.

Antes de entrar en materia, dos advertencias operativas:

• Las URL de salida son temporales. Descarga y vuelve a alojar en cuanto la tarea tenga éxito; consulta qué ocurre cuando caduca una URL de salida de hiapi.
• Si una tarea permanece en estado processing más de lo esperado, no la reenvíes a ciegas; aquí tienes una guía de diagnóstico de tareas colgadas o con timeout.

El rango de parámetros real (y los 400 que obtienes si adivinas)

Si has usado modelos FLUX en otras plataformas, la memoria muscular te llevará a ajustar steps y guidance. Pero en el esquema de tareas de hiapi para flux-1.1-pro, esos campos no existen; la API valida la entrada de forma estricta y rechaza propiedades desconocidas:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'steps', 'guidance' not allowed"
}

Esto no es un bug; FLUX 1.1 [pro] se ofrece como endpoint gestionado y la mecánica interna de muestreo la fija el proveedor. Esto es lo que sí puedes enviar, verificado contra el esquema en producción:

Campo	Tipo	Valores / rango aceptables
prompt	string	obligatorio
aspect_ratio	string	1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 4:5, 5:4, custom
width, height	integer	256–1440 px (se usan en lugar de la relación de aspecto, o junto con la relación custom)
seed	integer	cualquier entero; fija la composición para lograr reproducibilidad
output_format	string	jpg, png, webp
prompt_upsampling	boolean	hace que el backend reescriba/amplíe tu prompt
safety_tolerance	integer	0–6

Valores predeterminados prácticos para fotos de producto: output_format: "jpg", especifica un aspect_ratio claro según la ubicación (1:1 para la cuadrícula de la tienda, 4:5 para feed/estilo de vida, 3:2 o 1440×960 para banners), fija un seed por serie de SKU y mantén prompt_upsampling desactivado; en e-commerce quieres que el modelo siga estrictamente tu redacción, no que improvise.

Receta 1 — Foto limpia sobre fondo blanco

La imagen más básica: un producto, fondo continuo, luz principal suave. Di explícitamente el color del fondo, pide un reflejo en el suelo y, algo importante con cualquier modelo realista, incluye siempre “sin marca, sin logo, sin texto”. Esferas de reloj y etiquetas son justo donde FLUX puede inventar garabatos con formas de marca registrada que luego tendrías que retocar.

Studio packshot of an unbranded stainless steel wristwatch with a plain deep green dial and brushed metal bracelet, the dial completely clean with simple baton hour markers and no logo, no brand name, no text or numerals anywhere, standing upright on a seamless light grey background, centered composition, soft diffused key light from the upper left, subtle reflection beneath the watch, photorealistic e-commerce product photography

Envíalo con aspect_ratio: "1:1", seed: 6607. La textura del metal cepillado y el reflejo suave en el suelo son exactamente lo que pagas en el nivel profesional de $0.05; los modelos baratos son precisamente los que aplanan esos detalles.

Receta 2 — Imagen de estilo de vida

La cuadrícula de la tienda pide fondo blanco; las páginas de producto y las redes sociales convierten con escenas. Coloca el producto en un entorno, deja la etiqueta en blanco y usa una profundidad de campo reducida para transmitir “premium”. 4:5 coincide con el recorte del feed.

A lit soy candle in a clear glass jar with a plain blank kraft-paper label, on a rustic oak nightstand next to a stack of two linen-bound books, warm evening window light, softly blurred bedroom background, cozy lifestyle product photography for an online store, photorealistic

Envíalo con aspect_ratio: "4:5", seed: 7301. Observa que la etiqueta en blanco se conserva; ese es el lienzo donde luego compondrás tu gráfico de marca real.

Receta 3 — Variantes de color con seed fija

Este es el truco que más ahorra en la producción de catálogos. seed fija la inicialización del ruido, así que si mantienes la seed y la estructura del prompt idénticas y solo cambias la palabra del color, obtienes la misma composición con el nuevo color; sin reshoots, sin flujo img2img.

Ambas imágenes siguientes usan seed: 5150, aspect_ratio: "1:1" y prompts que difieren exactamente en dos palabras (navy blue → coral pink):

A single insulated stainless steel water bottle in matte navy blue, standing on a round travertine stone slab against a soft warm beige studio background, centered, soft diffused lighting, minimalist e-commerce product photo, photorealistic

La misma silueta de botella, la misma losa, la misma composición, pero un SKU diferente. Eso es una seed fija sustituyendo un día de sesión de variantes.

Por lotes: renderiza todo el catálogo por SKU

Este es el patrón que ejecutamos realmente: enviar, sondear, descargar, reintentar. Las ejecuciones en producción revelaron algo que debes planificar: las tareas de flux-1.1-pro fallan ocasionalmente con un genérico {"code": "TASK_FAILED"}; es transitorio y reenviar la misma entrada suele funcionar. Reserva hasta 3 intentos por imagen (solo pagas las imágenes renderizadas con éxito).

import json, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_HIAPI_KEY",
           "Content-Type": "application/json"}

CATALOG = [
    {"sku": "bottle-navy",  "colour": "matte navy blue"},
    {"sku": "bottle-coral", "colour": "matte coral pink"},
    {"sku": "bottle-sage",  "colour": "matte sage green"},
]
TEMPLATE = ("A single insulated stainless steel water bottle in {colour}, "
            "standing on a round travertine stone slab against a soft warm "
            "beige studio background, centered, soft diffused lighting, "
            "minimalist e-commerce product photo, photorealistic")

def render(prompt, seed, retries=3):
    for attempt in range(retries):
        task = requests.post(API, headers=HEADERS, json={
            "model": "flux-1.1-pro",
            "input": {"prompt": prompt, "aspect_ratio": "1:1",
                      "output_format": "jpg", "seed": seed},
        }).json()
        task_id = task["data"]["taskId"]
        while True:
            state = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
            if state["status"] == "success":
                return requests.get(state["output"][0]["url"]).content
            if state["status"] == "fail":          # transient TASK_FAILED happens;
                break                              # resubmit with the same input
            time.sleep(5)
    raise RuntimeError(f"gave up after {retries} attempts")

for item in CATALOG:
    img = render(TEMPLATE.format(colour=item["colour"]), seed=5150)
    with open(f"{item['sku']}.jpg", "wb") as f:
        f.write(img)                               # re-host immediately; task URLs expire
    print(item["sku"], "done")

Si vas a enviar cientos de SKU, controla el ritmo de envío; límites de tasa de las API de generación de imágenes explicados cubre el comportamiento de limitación y el nivel razonable de concurrencia.

Precios y cuándo elegir flux-1.1-pro

Verificado en la página de precios de hiapi:

Modelo	Precio por imagen	Cuándo usarlo
flux-schnell/text-to-image	$0.005	Borradores, composición de maquetas, miniaturas en grandes lotes
flux-1.1-pro	$0.05 uniforme	Packshots fotorrealistas y escenas de estilo de vida, hasta 1440 px en cualquier resolución
flux-2/text-to-image	$0.0375–$0.125 (por MP)	Máxima adherencia al prompt, texto legible dentro de la imagen

El precio uniforme es la ventaja discreta: un banner hero de 1440×960 cuesta lo mismo que una miniatura de 512×512 a $0.05, mientras que flux-2 factura por megapíxel. Si tu carga de trabajo es “fotos de producto realistas, tamaños mixtos”, flux-1.1-pro es la opción predeterminada de coste predecible; si necesitas recuentos exactos de objetos o texto impreso legible dentro de la imagen, sube a flux-2 — aquí lo probamos con la misma receta de e-commerce.

Una PDP de cinco imágenes (hero, fondo blanco, estilo de vida, dos colores) suma $0.25 por producto. Renovar un catálogo de 200 SKU: $50, una tarde, un script.

Conclusión

flux-1.1-pro en hiapi te ofrece fotos de producto fotorrealistas con un flujo de trabajo asíncrono de dos llamadas: un rango de parámetros estricto pero sencillo (relación de aspecto, tamaño, seed, formato; sin pelearte con steps/guidance), variantes de color con seed fija y un precio uniforme de $0.05 que hace que el presupuesto del catálogo sea muy fácil de predecir. Consigue tu API key, empieza en la página del modelo flux-1.1-pro y renderiza tu primera foto sobre fondo blanco con la llamada curl de arriba; antes de que se enfríe el café tendrás una imagen lista para tu PDP.