Genera imágenes de productos de comercio electrónico con z-image mediante la API de hiapi

La mayoría de los modelos de imagen pueden dibujar un producto. Pero los modelos que logran dibujar bien el producto y además escribir correctamente el precio son mucho menos. En el comercio electrónico —etiquetas de precio, banners promocionales, tarjetas de descuento, etiquetas de embalaje— el texto de la imagen es lo decisivo: un solo carácter ilegible significa que el material se rechaza.

z-image es un modelo de texto a imagen de nivel Turbo en hiapi, creado precisamente para este nicho: imágenes fotorrealistas rápidas, texto dentro de la imagen (en inglés y chino) preciso, a un precio de $0.008 por imagen, menos de un tercio de lo que cuestan la mayoría de las alternativas. Cada imagen de esta guía se generó con el mismo prompt que se muestra junto a ella, mediante la misma llamada a /v1/tasks que copiarás más abajo, y cada renderizado tardó entre 30 y 60 segundos de principio a fin.

Por qué elegir z-image para imágenes de producto

Hay tres atributos que importan en un flujo de trabajo de comercio electrónico, y z-image destaca en los tres:

• Renderizado de texto. Siguiendo las reglas de prompts que se describen más abajo, las tarjetas promocionales, los banners de logística y las etiquetas de botellas vuelven con cada palabra bien escrita.
• Velocidad. Es un modelo ajustado para Turbo; nuestros renderizados de prueba terminaron siempre en mucho menos de un minuto, lo que permite procesar por lotes cientos de imágenes de SKU en el tiempo que lleva tomarse un café.
• Precio. A $0.008 por imagen (verificado en la página de precios), renovar un catálogo de 1,000 imágenes cuesta $8. La misma tarea con gpt-image-2 ($0.03 por imagen) costaría $30.

Si quieres una visión más completa del modelo —configuración de claves, ejemplos genéricos, cuándo no usarlo— consulta Z-Image API: precios, claves de API, ejemplos y casos de uso. Esta guía se centra en el flujo de trabajo de comercio electrónico.

Interfaz de API verificada

z-image funciona sobre el endpoint de tareas asíncronas de hiapi. Envías una tarea, consultas su estado hasta que se complete y luego descargas el resultado. Confirmamos dos hechos del esquema contra la API en producción (ambos difieren de algunos otros modelos de la plataforma):

1. input solo acepta prompt y aspect_ratio. Enviar un campo resolution devuelve HTTP 400 (additional properties not allowed), a diferencia de gpt-image-2, que requiere ese campo.
2. aspect_ratio debe ser uno de 1:1, 4:3, 3:4, 16:9, 9:16. Cualquier otro valor (probamos 3:2) se rechaza con un 400 que enumera los valores válidos.

La resolución de salida es fija según la proporción; nuestros renderizados se devolvieron como PNG: 1536×1536 (1:1), 1344×768 (16:9), 928×1232 (3:4) y 1728×1296 (4:3).

Enviar una tarea

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "Studio e-commerce product photo: a matte black insulated steel water bottle on a seamless light-gray background...",
      "aspect_ratio": "1:1"
    }
  }'

La respuesta incluye un id de tarea:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG"}}

Sondear y descargar

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Sondea cada pocos segundos hasta que data.status sea success y exista data.output; considera fail como estado terminal. Un consejo práctico: poco después de generar, la tarea puede informar brevemente un estado intermedio (observamos archiving) antes de que aparezca el array output, así que tu bucle debe condicionarse a si existe la URL de salida, no solo a la cadena de estado.

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt: str, ratio: str = "1:1") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "z-image",
        "input": {"prompt": prompt, "aspect_ratio": ratio},
    }, timeout=60)
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        output = task.get("output") or []
        if output and output[0].get("url"):
            return requests.get(output[0]["url"], timeout=120).content
        if task.get("status") == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...your product prompt...", "1:1")
open("product.png", "wb").write(png)

Descarga de inmediato. output[0].url es un enlace temporal con una marca de tiempo expireAt; persiste los bytes en tu propio almacenamiento (S3/R2/CDN) en cuanto la tarea se complete. Si una tarea parece atascada, aquí se explica cómo diagnosticar tareas de hiapi colgadas o agotadas por tiempo de espera.

Cinco recetas de comercio electrónico con resultados reales

Todas las imágenes siguientes son renderizados reales de z-image generados con los mismos prompts que se muestran. Sin ningún retoque.

1. Imagen principal con etiqueta de precio

Studio e-commerce product photo: a matte black insulated steel water bottle centered
on a seamless light-gray background with soft shadow. A rectangular coral paper card
leans against the bottle. The card contains ONLY these two lines of bold clean
sans-serif text and no other words: "SUMMER SALE" on line one, "$19.99" on line two.
Text flat-on to camera, large, perfectly legible. Photorealistic.

Fíjate en la redacción: el texto mostrado va entre comillas y el prompt dice que la tarjeta contiene solo esas palabras. En nuestro primer intento describimos el texto en línea ("...reads exactly: SUMMER SALE on the first line and $19.99 on the second line") y el modelo compuso fielmente la palabra "ON" entre las dos líneas: las palabras de instrucción se filtraron al resultado. Cita las cadenas literales; deja las instrucciones fuera de las comillas.

2. Banner promocional panorámico

Wide e-commerce promo banner, photorealistic flat-lay of white sneakers and a kraft
shipping box on a pastel blue background. On the right side, bold navy sans-serif
text with exactly these four words and amount, nothing else: "FREE SHIPPING OVER $50".
All four words must appear. Text large, straight, perfectly legible. Clean commercial
studio lighting.

16:9 te da un banner de 1344×768 que puedes colocar directamente en el espacio principal de la página de inicio de tu tienda.

3. Tarjeta de descuento vertical para redes sociales

Vertical social-media product card: a small brown glass cosmetic dropper bottle on a
warm beige podium, soft daylight. Above the bottle, bold black modern sans-serif
headline text reads exactly: 30% OFF TODAY ONLY. Text flat to camera, large and
perfectly legible. Minimalist premium e-commerce style, photorealistic.

3:4 (928×1232) es la proporción más cercana al formato de publicación en el feed; si tu plataforma lo exige, puedes recortarla después a 4:5.

4. Etiqueta de embalaje legible

Macro e-commerce product photo of a frosted glass skincare bottle with a clean white
label. The label text, printed in elegant dark sans-serif, reads exactly: GLOW SERUM
on the first line and VITAMIN C 10% on the second line. Straight-on angle, label
fully visible and sharp, soft studio lighting, photorealistic, white background.

Esta es la prueba más difícil del conjunto —texto pequeño sobre vidrio curvo— y la etiqueta volvió impecable, incluido "10%".

5. Gama de colores (sin texto)

E-commerce catalog photo: three identical ceramic coffee mugs lined up left to right
in sage green, terracotta orange, and navy blue, on a plain white studio background
with soft even shadows. No text anywhere in the image. Photorealistic, consistent
product geometry across all three mugs.

La geometría uniforme entre variantes es justo lo que la hace utilizable como tira de catálogo: z-image mantuvo idénticas las formas de las tres tazas de colores en una sola generación.

Reglas de prompts para que el texto sobreviva

Destiladas de lo que funcionó (y falló) en nuestras pruebas reales:

1. Pon las cadenas literales entre comillas. text reads exactly: "SUMMER SALE": el modelo trata las palabras circundantes sin comillas como candidatas a copia.
2. Añade "and no other words" (y ninguna otra palabra). De lo contrario, el modelo puede inventar texto adicional de insignias para rellenar el espacio.
3. Mantén el texto de frente a la cámara. Nuestro único renderizado ilegible fue texto colgado en ángulo sobre una etiqueta; el mismo texto en una tarjeta plana salió perfecto. La deformación por perspectiva es donde primero se rompen los glifos.
4. Uno o dos bloques de texto por imagen. Cada bloque de texto adicional multiplica la probabilidad de fallo; para diseños complejos, compón después.
5. Verifica antes de publicar. A este precio, puedes permitirte un bucle de reintentos: renderiza, haz OCR o inspecciona visualmente el texto, y regenera si no coincide. Incluso reintentando una vez cada imagen fallida, el coste sigue siendo una fracción del de los modelos alternativos.

Coste por lotes

Un escenario concreto: 200 SKU × 3 materiales por SKU (imagen de listado, banner promocional, tarjeta social) = 600 imágenes.

Modelo	Precio/imagen	600 imágenes	Notas
z-image	$0.008	$4.80	Velocidad Turbo, buen rendimiento de texto en imagen
flux-schnell	$0.005	$3.00	El más barato, pero no está orientado al renderizado de texto
qwen-image-2.0	$0.025	$15.00	Buena calidad general
gpt-image-2	$0.03	$18.00	Requiere el campo resolution; guía de comercio electrónico aquí

(Precios tomados de la página de precios de hiapi en el momento de la publicación.)

El modo por lotes consiste simplemente en poner la función generate() anterior en un bucle: envía unas cuantas tareas de forma concurrente, recoge los ids de tarea y luego sondea en grupos. Si vas a aumentar mucho el volumen, lee primero cómo gestiona hiapi los límites de velocidad y los picos de tráfico.

Empezar

Obtén una clave de API en tu consola y luego apunta los fragmentos de código anteriores a tu propio catálogo de productos: la página del modelo z-image tiene la ficha del modelo, y la documentación de hiapi cubre la API de tareas en detalle. A $0.008 por renderizado, la forma más barata de saber si encaja en tu flujo de trabajo es probarlo esta misma tarde con tus diez SKU más complicados.