Genera imágenes de producto de comercio electrónico con qwen-image-2.0 a través de la API de hiapi

qwen-image-2.0 es el modelo de texto a imagen de segunda generación de Alibaba, disponible a través de la interfaz /v1/tasks de hiapi, con un precio de $0.025 por imagen y una salida predeterminada de 2K. Para el comercio electrónico tiene dos aspectos especialmente interesantes: dentro de este rango de precio, su renderizado de texto en chino es el más limpio entre todos los modelos de texto a imagen actuales; además, su fidelidad al prompt con briefs de producto largos y detallados es muy estable — justo lo que realmente necesitan los listings transfronterizos.

Esta guía es la versión ejecutable de este flujo de trabajo. Cada llamada a la API es algo que puedes pegar directamente en la terminal, las plantillas de prompt han sido probadas y renderizadas en el endpoint en vivo, y el precio por imagen es una cifra en tiempo real de la tarifa de HiAPI. Aquí no hay nada teórico: las cifras de coste asumen los valores de size que qwen-image-2.0 acepta realmente, no cifras de marketing.

Por qué elegir qwen-image-2.0 para imágenes de producto transfronterizas

Cuando tienes que lanzar 200 SKU a un listing de mercado de una sola vez, hay tres cosas que importan.

1. Renderizado de texto en chino. La mayoría de los listings de comercio electrónico dirigidos a China continental, Hong Kong, Taiwán o el sudeste asiático necesitan texto en chino legible en el envase, el banner o la etiqueta. qwen-image-2.0 es el único modelo en hiapi con el que puedes escribir un prompt como "la etiqueta del frasco dice 玫瑰精华水 en chino con serifa en negrita" y el modelo renderizará exactamente esos glifos en la posición exacta que describes.
2. Fidelidad al prompt con briefs de producto largos. Los briefs de comercio electrónico son largos: material, color hexadecimal, acabado superficial, dirección de la luz, forma de la sombra, color de fondo, ángulo de cámara. Cuando el brief se alarga, qwen-image-2.0 mantiene la coherencia general — el modo de fallo habitual suele ser solo omitir un accesorio, no inventar un producto de la nada.
3. Un rango de coste que soporta la explosión de variantes. Una página de SKU típica quiere 4–6 imágenes (toma de estudio, imagen de escena, vista cenital, imagen de comparación de escala, dos variantes). A $0.025 por imagen, eso son $0.10–$0.15 por SKU. Un lanzamiento de 200 SKU cuesta $20–$30. Es precisamente este rango de coste el que hace que "generar todo desde cero" sea más barato que encargar parte de la fotografía y rellenar huecos con imágenes de stock.

Si quieres ver experimentos de ajuste de prompt uno por uno, y seis recetas orientadas al estilo en lugar del comercio electrónico, consulta el artículo complementario Recetas de prompt para qwen-image-2.0. Este artículo se centra en los casos de uso de catálogo.

El esquema de entrada de qwen-image-2.0 en hiapi

qwen-image-2.0 funciona bajo la interfaz unificada /v1/tasks, que es también el único endpoint de imagen que hiapi ofrece actualmente. Antes de escribir cualquier código, hay una regla especial que conviene acertar desde el principio:

• El parámetro de tamaño se llama size — no aspect_ratio, no resolution, ni image_size. Otros modelos en hiapi (nano-banana, la serie flux) aceptan aspect_ratio; qwen-image-2.0 no lo acepta.
• El separador dentro de size es *, no x. "size": "2688x1536" devuelve un 400; "size": "2688*1536" funciona correctamente.
• Solo se aceptan cinco valores de size. Todos son 2K:

Relación de aspecto	Valor de size	Uso
16:9 (aprox. 1.75:1)	2688*1536	Imagen principal, banners, portada de listing
4:3 (aprox. 1.37:1)	2368*1728	Doble página tipo revista, espacio publicitario a dos columnas
1:1	2048*2048	Toma de estudio cuadrada, miniatura de mercado
3:4 (aprox. 0.73:1)	1728*2368	Páginas de producto orientadas a móvil
9:16 (aprox. 0.57:1)	1536*2688	Portada de vídeo vertical, fotograma de TikTok/Reels

Si envías cualquier otro valor, la API devuelve la lista literal de valores permitidos en el error:

{"code": 400, "message": "invalid input: size: value must be one of '2688*1536', '2368*1728', '2048*2048', '1728*2368', '1536*2688'"}

Trata este mensaje de error como la fuente autoritativa de verdad — si en el futuro ves un valor nuevo aparecer ahí, significa que la plataforma ha ampliado el esquema.

Una petición ejecutable

Todo el plano de llamadas consta solo de dos endpoints: POST /v1/tasks para encolar, y GET /v1/tasks/{taskId} para hacer polling. La siguiente es la petición mínima que produce la toma de estudio de abajo.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "input": {
      "prompt": "A clear glass cosmetic dropper bottle on a clean off-white seamless paper background, soft daylight from camera left, gentle elliptical shadow, the label reads 玫瑰精华水 in bold serif Chinese with a small line of English Rose Essence Water below, the liquid inside has a faint pink tint, studio product photography, sharp focus on the label, no other props, square 1:1 composition",
      "size": "2048*2048"
    }
  }'

Respuesta:

{"code": 200, "data": {"taskId": "tk-hiapi-01KW8R..."}, "message": "success"}

Para el polling:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01KW8R... \
  -H "Authorization: Bearer $HIAPI_TOKEN"

El campo status pasa por handling → archiving → success. En nuestras pruebas, el tiempo real total por imagen a 2K fue de 25–45 segundos. Cuando status es success, output[0].url guarda la imagen — pero apunta a temp.hiapi.ai y lleva una marca de tiempo Unix expireAt, así que descárgala de inmediato. No la incrustes en una página ni la fijes en una base de datos; dará 404 en pocas horas.

Este prompt de estudio, ejecutado en el endpoint en vivo, genera un frasco gotero de vidrio con los caracteres chinos 玫瑰精华水 renderizados limpiamente en la etiqueta, y justo debajo el inglés Rose Essence Water en un peso tipográfico menor. El modelo coloca las dos líneas de texto en la zona de etiqueta canónica, sin necesidad de ninguna pista de maquetación en el prompt — basta con la formulación "the label reads X".

Un bucle de Python que convierte una hoja de SKU en tomas de estudio subidas

Este es el bucle que ejecutamos al generar las imágenes de esta página. Acepta un conjunto de tuplas (slug, prompt, size), las envía de forma concurrente con un límite de concurrencia bajo, hace polling de cada tarea hasta que termina, descarga el resultado y lo sube como webp a tu propio almacenamiento. El patrón es deliberadamente aburrido — requests más concurrent.futures — porque la parte interesante es el modelo.

import os, time, io, requests, concurrent.futures as cf
from PIL import Image

TOKEN = os.environ["HIAPI_TOKEN"]
BASE = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def submit(prompt, size):
    r = requests.post(BASE, headers=H, json={
        "model": "qwen-image-2.0",
        "input": {"prompt": prompt, "size": size},
    }, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]


def wait(task_id, deadline_s=240):
    deadline = time.time() + deadline_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/{task_id}", headers=H, timeout=30)
        d = r.json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {d.get('error')}")
        time.sleep(4)
    raise TimeoutError(f"task {task_id} not done in {deadline_s}s")


def render_one(item):
    slug, prompt, size = item
    task_id = submit(prompt, size)
    url = wait(task_id)
    png = requests.get(url, timeout=60).content
    buf = io.BytesIO()
    Image.open(io.BytesIO(png)).convert("RGB").save(buf, "WEBP", quality=88, method=6)
    return slug, buf.getvalue()


JOBS = [
    ("packshot-rose-water",  "A clear dropper bottle, label 玫瑰精华水…", "2048*2048"),
    ("packshot-tea-canister","A pale grey ceramic tea canister, label 龙井…", "2048*2048"),
    # … 200 more rows from your sheet …
]

with cf.ThreadPoolExecutor(max_workers=6) as pool:
    for slug, webp in pool.map(render_one, JOBS):
        with open(f"out/{slug}.webp", "wb") as f:
            f.write(webp)
        print(f"saved {slug}.webp ({len(webp)} bytes)")

Sobre este código, hay algunas notas breves que no se ven en el propio código.

• max_workers=6 es el punto óptimo que observamos. En 8–10, la profundidad de cola empieza a manifestarse como latencia adicional en lugar de rendimiento. Del lado del modelo, la concurrencia parece repartirse de forma justa por cuenta.
• Antes de almacenar, convertimos a webp con calidad 88. Los png de 2K que produce este endpoint pesan unos 3–4 MB; el webp queda en 200–400 KB, visualmente idéntico a tamaños de página de producto. La transferencia es más barata, y el modelo ya ha codificado mucha textura, que JPEG maneja mal.
• La URL temporal solo se puede descargar una vez. Si tu paso de subida falla (fallo de S3, inestabilidad de red), tienes que volver a renderizar — no hay una segunda oportunidad para obtener la salida de la misma tarea.

Seis patrones de prompt adecuados para comercio electrónico

Estas son las formas de prompt que sobrevivieron a nuestras comparaciones A/B internas frente a alternativas más verbosas. Están escritas para usuarios de inglés que usan etiquetas de producto en chino — el escenario transfronterizo más habitual.

Patrón 1 — Toma de estudio de un solo producto con etiqueta en chino

La imagen de producto por defecto. Especifica el color de fondo en inglés sencillo, especifica el texto de la etiqueta en chino literal junto con la familia tipográfica en inglés, y especifica una sola fuente de luz.

A pale grey ceramic tea canister on a clean off-white seamless paper background. The label reads 龙井 in bold black serif Chinese with the small English subtitle Longjing Green Tea below. Soft daylight from camera right, gentle elliptical shadow, no other props. Sharp focus on the label, studio product photography, square 1:1 composition.

Las dos cosas que funcionan son "reads X in bold serif Chinese" (qwen-image-2.0 lo coloca en la posición esperada de la etiqueta) y "sharp focus on the label" (hace que el modelo trate el texto como foco, no como decoración).

Patrón 2 — Imagen de escena construida alrededor de una mesa vacía

Para fotografía de escena, describe primero la escena y coloca el producto al final, no al revés. El modelo es más propenso a desviarse en la escena que en el producto, así que ancla primero la escena.

A wooden Japanese-style table near a wide window in late-morning daylight. The window casts a soft rectangle of light onto the table. In the center of the table is the pale grey ceramic tea canister from the previous shot, with a small wisp of steam rising from a cup beside it. Loose tea leaves are scattered to the right. Wabi-sabi aesthetic, soft shadows, shallow depth of field with focus on the canister. 16:9 widescreen composition.

En nuestro render de prueba, la lata lleva los caracteres 龙井 y justo debajo el inglés Longjing Green Tea — la misma disciplina de etiqueta que en la toma de estudio — y el vapor, las hojas de té esparcidas y la luz de la ventana aparecen tal como se describen.

Patrón 3 — Cuadrícula de variantes de color en un solo render

Cuando las variantes comparten la misma geometría de producto, puedes renderizar toda la cuadrícula en una sola llamada en lugar de tres. Más barato, y la iluminación de cada celda es coherente por construcción.

Three pairs of low-top canvas sneakers shot from a slight top-down angle, arranged in one horizontal row on a clean light-grey seamless background. From left to right: dusty rose, sage green, ivory cream. Identical sneaker silhouette, identical lighting, identical shadow. Each pair faces the camera with toes pointing forward. Studio product photography, 1:1 composition, evenly spaced.

Este patrón te ahorra renderizar cada variante por separado e intentar igualar la iluminación en postproducción. La restricción "identical sneaker silhouette, identical lighting, identical shadow" es la clave para mantener la fila cohesionada.

Patrón 4 — Banner promocional bilingüe

Para campañas de marca compartida en Shopee, Lazada y Taobao, normalmente necesitas un titular en chino y un subtítulo en inglés en la misma imagen. qwen-image-2.0 es el único modelo en hiapi que hace bien ambos en un mismo render.

A horizontal ecommerce promotional banner on a soft pink gradient background. The main headline reads 双十一大促 in large bold black sans-serif Chinese in the center-left. Below the Chinese headline in smaller dark grey English serif: Double 11 Sale — Up to 50% Off. To the right is a clear glass dropper bottle of pink serum with a small white label. Subtle confetti texture in the background, clean and modern, 16:9 widescreen.

El truco para que esto funcione de forma consistente es poner el chino al principio del prompt y darle el calificador "large bold", y luego dar al inglés el calificador "smaller". Si inviertes el orden, el modelo a menudo hace que el inglés también tenga tamaño de titular. La etiqueta del producto dentro del banner es donde puedes relajarte — en nuestro render de prueba, qwen eligió para la botella una etiqueta genérica "Vitamin C Serum" porque no deletreamos los caracteres; para campañas de marca, incluye el texto literal de la etiqueta en el prompt o compón la etiqueta real en postproducción.

Patrón 5 — Tarjeta de listing para mercado transfronterizo

Para un compuesto que parezca un mosaico de listing de Amazon o Tmall — producto, título, precio, insignia — el prompt debe leerse como un brief de maquetación, no como un brief de fotografía.

A square ecommerce listing card on a white background. In the top two-thirds, a clear glass dropper bottle of pink rose-essence water labeled 玫瑰精华水 / Rose Essence Water. In the bottom third, on the left, the price 99 元 in large bold black Chinese characters with a small English subtitle Rose Essence 30ml below. On the right, a small green badge that reads 新品 in white. Clean modern layout, soft drop shadow under the product, 4:3 composition.

Para listings, renderiza en 4:3 (2368*1728), no en 1:1 — la ranura de imagen principal de la mayoría de los componentes de listing de mercado es 4:3, y un cuadrado produce un recorte incómodo.

Patrón 6 — Generación bajo demanda para personalización

El último patrón cambia la economía unitaria. Una vez que cada render cuesta menos de tres centavos, puedes dejar de pre-renderizar banners para campañas y renderizarlos por cliente en el momento de la solicitud — "Hola Sra. Wang, su combinación mensual está lista" — y hornear el nombre real del cliente en el banner. Con caché por hash del nombre y un TTL, obtienes banners personalizados con una factura de CDN mínima.

La restricción es la latencia. 25–45 segundos por render es demasiado lento para un flujo de solicitud síncrona, pero perfectamente aceptable para un envío de correo o una notificación push — genera al encolar, incrusta cuando se envía el mensaje.

En qué no destaca qwen-image-2.0

Por equilibrio, estos cuatro tipos de trabajo los seguimos dejando a otros modelos en el mismo endpoint /v1/tasks.

• Tomas en mano con desenfoque de movimiento. La toma de estudio es el punto óptimo. Si necesitas algo que parezca no posado — estilo UGC, ligero movimiento, composición imperfecta — prueba nano-banana-pro, que entiende mejor las composiciones "casuales".
• Variantes de producto idénticas a nivel de píxel. qwen-image-2.0 renderiza variantes similares entre llamadas, pero si necesitas exactamente el mismo frasco gotero bajo cinco configuraciones de iluminación distintas, necesitas un modelo con condicionamiento por imagen de referencia. Ningún modelo puramente de texto a imagen en hiapi garantiza consistencia de píxeles entre llamadas.
• Rostros fotorrealistas de cuerpo completo. Los primeros planos de rostros están bien; los cuerpos completos o las fotos de grupo suelen suavizar los detalles faciales. Para comercio electrónico centrado en personas — pruebas de ropa, demostraciones de belleza — combina qwen-image-2.0 con un modelo de vídeo con condicionamiento por referencia para las tomas en movimiento.
• Respuesta por debajo del segundo. Si necesitas generar imágenes en el bucle interno de una solicitud síncrona (el usuario espera frente a la pantalla), 25–45 segundos es demasiado. flux-schnell responde en unos 5 segundos a $0.005 por imagen, pero no renderiza texto en chino. Elige primero según el presupuesto de latencia.

El coste real de un lanzamiento de 200 SKU

Con un caso representativo, echemos números al flujo de trabajo de extremo a extremo.

Paso	Cantidad	Precio unitario	Total
Imagen principal/toma de estudio por SKU	200 × 1	$0.025	$5.00
Imagen de escena por SKU	200 × 1	$0.025	$5.00
Cuadrícula de variantes por SKU (unos 3 variantes por render)	200 × 1	$0.025	$5.00
Banner bilingüe por categoría (10 categorías)	10 × 1	$0.025	$0.25
Tarjeta de listing por SKU	200 × 1	$0.025	$5.00
Coste total de generación de imágenes	810 renders	—	$20.25

Con la tarifa actual de hiapi, el presupuesto total de imágenes de un lanzamiento transfronterizo de 200 SKU es de unos $20. El mismo trabajo con modelos de gama alta (desde $0.04 por imagen) se sitúa entre $30 y $140, con tiempos de ejecución mayores por imagen. Esa es la brecha que qwen-image-2.0 está diseñado para cubrir: trabajo de comercio electrónico con conciencia del chino, a un rango de coste tan bajo que dejas de contar renders.

Adónde ir después

• Lee las recetas de prompt para qwen-image-2.0 para conocer seis recetas orientadas al estilo, no específicas de comercio electrónico.
• Toma la página de precios de hiapi como fuente de verdad para cualquier cifra de coste — qwen-image-2.0 está actualmente a $0.025 por imagen, pero prevalece esa página.
• Para flujos sensibles a la latencia que no necesitan texto en chino, cambia a flux-schnell manteniendo la misma forma de /v1/tasks — la comparación está en Generar imágenes de producto de comercio electrónico con FLUX.1 schnell.

Todo el sentido del endpoint unificado /v1/tasks es que cambiar de modelo es cambiar una cadena. Una vez que tengas montado el bucle para qwen-image-2.0, el mismo script de Python puede renderizar con cualquier modelo de imagen de hiapi simplemente editando el campo "model" y ajustando el esquema de size de ese modelo.