flux-2 para imágenes de productos de comercio electrónico: guía práctica de la API de hiapi

TL;DR

• Qué es esto: una guía práctica para generar imágenes de productos de comercio electrónico con flux-2/text-to-image en hiapi. Cada imagen de esta página se generó con el prompt exacto que se imprime justo encima de ella —sin demostraciones prestadas—, así que puedes reproducir cada una.
• Por qué flux-2 encaja en imágenes de producto: se apoya en el cumplimiento del prompt y la alta fidelidad, justo lo que exige el trabajo de catálogo: número exacto de artículos, colores concretos, fondos limpios y sin costuras, y etiquetas en blanco (sin texto), todo respetado al pie de la letra.
• Datos del modelo (verificados en la API): flux-2 funciona sobre el endpoint de tareas asíncrono (/v1/tasks). input.resolution usa el formato de megapíxeles: 0.5 MP, 1 MP, 2 MP o 4 MP, no 1K/2K. aspect_ratio es opcional y acepta valores como 1:1, 3:2, 16:9.
• Precios (por imagen): 0.5 MP cuesta $0.0375, 1 MP $0.05, 2 MP $0.075 y 4 MP $0.125. Consulta los precios en tiempo real en Precios.
• Cómo ejecutarlo: envía una solicitud POST a la API de tareas, consulta el estado hasta que sea success y descarga la imagen desde output[0].url (esa URL caduca; guarda los bytes de inmediato). El script completo para copiar y pegar está al final, con un bucle por lotes.

Por qué flux-2 encaja en fotografía de producto

Casi cualquier modelo de texto a imagen sabe dibujar una taza bonita. El problema en comercio electrónico no es la «belleza», sino la precisión. Un listado de producto necesita el color correcto, el número correcto de artículos, un fondo limpio con espacio para que superpongas tu propio texto y etiquetas en blanco para colocar el copy real después. Cuando el modelo se toma libertades —dibuja una botella de más, inventa texto en la etiqueta, tiñe el fondo blanco—, la imagen no se puede publicar.

flux-2 está etiquetado como cumplimiento del prompt y alta fidelidad, lo que en la práctica significa que tiende a ejecutar el prompt de forma estrictamente literal. Eso es precisamente lo clave en imágenes de catálogo: tú escribes las restricciones y el modelo las respeta en lugar de «interpretarlas con creatividad». Las recetas de abajo se construyen justo sobre eso: cada una se apoya en una restricción concreta (cantidad, color, composición) para que veas el cumplimiento por ti mismo.

Cómo leer estas recetas

Cada receta tiene tres partes: una línea de objetivo, el prompt exacto (cópialo tal cual) y la imagen que genera. Cada prompt lo escribí yo y lo ejecuté en flux-2 a través de la API de tareas real. Algunos hábitos que funcionan de forma constante con este modelo:

• Especifica el fondo. «Fondo de estudio gris claro sin costuras» supera a dejarlo al azar y hace que la imagen sea directamente utilizable en la página de detalle del producto (PDP).
• Escribe «sin texto, sin logotipo» cuando quieras etiquetas en blanco. flux-2 lo respeta, lo que significa que puedes añadir tu marca real después.
• Dale restricciones contables y verificables. «Exactamente tres botellas», «ámbar a la izquierda, transparente en el centro, turquesa a la derecha»: las instrucciones concretas son donde el cumplimiento se nota.
• Reserva espacio negativo en el prompt («amplio espacio en blanco en la parte superior para el titular»), sobre todo cuando la imagen irá debajo de texto superpuesto.

Receta 1: fondo blanco limpio

Objetivo: la imagen de listado más básica: un producto, fondo sin costuras, márgenes uniformes, lista para colocarla en la página del producto.

A single matte-white ceramic coffee mug centered on a seamless light-grey studio background, three-quarter front angle, empty and unbranded. Soft even top-light with one subtle rim highlight down the left edge, a soft grounded contact shadow beneath. Studio e-commerce packshot, perfectly centered, wide even margins on all sides, photoreal, high detail, no text, no logo.

Los márgenes y el centrado provienen directamente del prompt: pídelos de forma explícita para que el recorte funcione en la cuadrícula del listado.

Receta 2: prueba de cumplimiento del prompt

Objetivo: demostrar que el modelo sigue instrucciones precisas y contables, que es justo la razón por la que se elige flux-2 para trabajo de producto.

Product photo of exactly three glass spray bottles standing in a row on a white acrylic surface: the left bottle filled with pale amber liquid, the middle bottle filled with clear liquid, the right bottle filled with soft teal liquid. All three have matte-black fine-mist pump tops and blank labels with no writing. Even frontal studio light, soft reflections on the acrylic, seamless white background. Photoreal commercial product photography, sharp focus, no text anywhere in the image.

Cuéntalas: tres botellas, no cuatro. De izquierda a derecha los líquidos son ámbar, transparente y turquesa, en el orden correcto. Las bombas son negro mate. Las etiquetas están en blanco, así que puedes añadir el copy real después. Ese es el beneficio: tú lo especificas, el modelo lo respeta y la imagen queda lista para usar.

Receta 3: imagen de estilo de vida/escena

Objetivo: situar el producto en una escena sin que se pierda: la imagen «en uso» que acompaña a la de fondo blanco en el listado del producto.

Lifestyle e-commerce shot of a tan leather crossbody bag resting on a pale oak cafe table beside a folded newspaper and a cup of espresso, soft morning window light from the left, warm out-of-focus cafe interior in the background with creamy bokeh. The bag is the clear hero, sharp and well-lit, staged naturally but uncluttered. Photoreal, editorial product-in-use photography, warm neutral palette, shallow depth of field, no visible brand marks or text.

Señalar al protagonista («el bolso es el protagonista claro y nítido») y desenfocar todo lo demás mantiene el producto reconocible y a la vez cuenta una historia: exactamente el equilibrio que necesita una imagen de estilo de vida.

Receta 4: conjunto de ángulos para la PDP

Objetivo: un conjunto de ángulos para la página de detalle del producto: varias vistas coherentes del mismo artículo, con iluminación y proporciones que coincidan.

A clean product-detail-page angle set of one pair of low-top canvas sneakers in off-white, shown as three separate views arranged left to right on a seamless light-grey background: a straight side profile, a three-quarter front angle, and a top-down overhead view. Consistent soft studio lighting and identical scale across all three, even spacing, soft contact shadows. Catalog-grade e-commerce photography, photoreal, crisp, unbranded, no text or labels.

Pedir «iluminación coherente y la misma escala en las tres vistas» hace que el conjunto parezca un mismo producto y no tres renders sueltos. No sustituye a un equipo real de fotografía 360, pero es un atajo útil para maquetar la PDP antes de la sesión definitiva.

Ejecutar flux-2 en la API de tareas

flux-2 usa el protocolo asíncrono de tareas de hiapi: creas una tarea, la consultas y luego descargas el resultado. Lo único que hay que acertar es esto: resolution usa el formato de megapíxeles. Envía "1 MP", no "1K", o la API devolverá un 400 indicando que el valor debe ser uno de 0.5 MP / 1 MP / 2 MP / 4 MP.

1. Crear la tarea

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "input": {
      "prompt": "A single matte-white ceramic coffee mug centered on a seamless light-grey studio background, three-quarter front angle, soft even top-light, photoreal e-commerce packshot, no text, no logo",
      "aspect_ratio": "1:1",
      "resolution": "1 MP"
    }
  }'
# -> {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

2. Consultar hasta que termine y luego descargar

import os, time, requests

TOKEN = os.environ["HIAPI_TOKEN"]
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}


def generate(prompt, aspect_ratio="1:1", resolution="1 MP"):
    # create
    r = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/text-to-image",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
    }).json()
    task_id = r["data"]["taskId"]

    # poll (a single image usually lands well under two minutes)
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS).json()["data"]
        if task["status"] == "success":
            # output[0].url is a temporary link — download the bytes now
            url = task["output"][0]["url"]
            return requests.get(url, timeout=120).content
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)


img = generate("A single matte-white ceramic coffee mug on a seamless light-grey background, photoreal e-commerce packshot, no text")
open("mug.jpg", "wb").write(img)

La URL de output[0].url lleva una marca de tiempo expireAt: es un enlace de corta duración. Descarga los bytes de inmediato y envíalos a tu propio almacenamiento; no la enlaces en caliente desde un listado de producto en producción.

Generar todo el catálogo por lotes

Para una tienda real no haces una sola imagen, sino una por cada SKU. Mantén una lista de prompts, reutiliza la función generate() de arriba y guarda cada resultado con el nombre de su SKU:

catalog = {
    "SKU-1001": "A single matte-white ceramic coffee mug on a seamless light-grey studio background, three-quarter angle, soft even top-light, photoreal e-commerce packshot, no text, no logo",
    "SKU-1002": "A tan leather crossbody bag on a seamless light-grey studio background, front-on, soft studio light, grounded contact shadow, photoreal packshot, no visible brand marks",
    "SKU-1003": "A pair of off-white low-top canvas sneakers, side profile, seamless light-grey background, crisp catalog lighting, photoreal, unbranded, no text",
}

for sku, prompt in catalog.items():
    img = generate(prompt, aspect_ratio="1:1", resolution="1 MP")
    open(f"{sku}.jpg", "wb").write(img)
    print(f"{sku} done")

Antes de escalar, conviene saber algunas cosas:

• La resolución determina el coste. Con 1 MP, cada imagen cuesta $0.05; sube a 2 MP ($0.075) o 4 MP ($0.125) solo en las imágenes insignia donde el detalle extra lo merezca. Un catálogo de 200 SKU a 1 MP cuesta aproximadamente $10. Consulta Precios para ver las cifras actuales antes de presupuestar.
• Ejecuta tareas en paralelo. Cada SKU es una tarea independiente: crea varias tareas y consúltalas en paralelo en lugar de una a una; los lotes grandes terminan en mucho menos tiempo real.
• Mantén una cláusula de «estilo» coherente. Fíjate en el sufijo compartido de cada prompt de arriba («fondo de estudio gris claro sin costuras... packshot fotorrealista, sin texto»). Fija esa redacción para que un lote de imágenes parezca un catálogo y no una mezcolanza.

Conclusiones

• La ventaja de flux-2 en trabajo de producto es que ejecuta estrictamente lo que pides literalmente: cantidades exactas, colores exactos, etiquetas en blanco; así que escribe las restricciones de forma explícita para que las respete.
• Especifica siempre el fondo en el prompt y reserva espacio negativo; eso hace que el render sea directamente utilizable en el listado de producto.
• En la API de tareas, envía resolution en megapíxeles (1 MP), consulta /v1/tasks/{id} hasta success y descarga antes de que caduque output[0].url.
• El precio sube con la resolución: usa 1 MP para lotes de catálogo y reserva 2 MP/4 MP para las imágenes insignia.

¿Listo para probarlo? Consigue una clave, apunta model a flux-2/text-to-image y consulta las tarifas en tiempo real en la página de precios antes de generar el catálogo por lotes.