Imagen 4 para imágenes de producto de comercio electrónico: prompts, código por lotes y control de calidad

Resumen

• Imagen 4 estándar funciona en HiAPI como imagen-4.0, con un precio de $0.06 por imagen; cada solicitud genera una imagen y solo admite texto a imagen. Abre la página del modelo Imagen 4 para probar primero un prompt.
• Para catálogos de productos, es muy útil para generar imágenes de producto sobre fondo blanco y escenas de estilo de vida que de otro modo requerirían una sesión fotográfica por cada variante de color. No puede reproducir tu SKU real, porque no admite imágenes de referencia como entrada.
• aspect_ratio es obligatorio (no tiene valor predeterminado) y seed debe ser una cadena numérica. En nuestras pruebas, "seed": "sku-dripper-01" pasó la validación, pero aproximadamente un segundo después todas las tareas fallaron con TASK_FAILED.
• Incluye una etapa de control de calidad. En un lote de 4 imágenes obtuvimos una jarra de vidrio que no habíamos pedido, un esmalte brillante donde pedimos mate y texto falso en las etiquetas de los atrezos, a pesar de configurar negative_prompt: "text, logo".

Qué cubre esta guía

Este es un flujo de trabajo práctico para tiendas en línea, pensado para generar un conjunto de imágenes por cada línea de producto: una imagen de catálogo sobre fondo blanco por SKU, una escena de estilo de vida para la página de producto y un recorte vertical para stories de móvil. Todo lo siguiente se ejecutó el 2026-11-04 contra la API en vivo, usando un producto ficticio: un gotero de cerámica verde salvia y una taza a juego.

Si solo necesitas que tu primera solicitud funcione, empieza por Cómo usar la API de Imagen 4. Para plantillas de prompts genéricas, consulta Prompts de Imagen 4. Esta guía trata sobre cómo generar conjuntos de imágenes de tienda por lotes y revisarlos antes de publicarlos.

Elige el nivel antes de escribir prompts

Los tres niveles de Imagen 4 en HiAPI son texto a imagen y comparten la misma estructura de solicitud: cambiar el id de model basta para cambiar de nivel. Los precios provienen de Precios de HiAPI del día de la prueba.

Nivel	Id del modelo	Precio por imagen	Página del modelo
Fast	imagen-4.0-fast	$0.03	Imagen 4 Fast
Standard	imagen-4.0	$0.06	Imagen 4
Ultra	imagen-4.0-ultra	$0.09	Imagen 4 Ultra

Para un catálogo de productos, la aritmética es sencilla. 200 SKU × (1 imagen de producto + 1 imagen de estilo de vida) = 400 imágenes, lo que cuesta $24 en el nivel estándar, $12 en Fast y $36 en Ultra, sin contar reintentos. En este artículo solo probamos el nivel estándar, así que no hacemos ninguna afirmación sobre la calidad de Fast o Ultra. Para el desglose completo de precios, consulta Precios de la API de Imagen 4.

La solicitud: cuatro campos, dos de ellos propensos a errores

El esquema de entrada de imagen-4.0 es cerrado. Estos son los casos límite que encontramos al construir el procesamiento por lotes, con los mensajes de error exactos:

Campo	Regla	Lo que observamos
prompt	Cadena obligatoria	—
aspect_ratio	Obligatorio, con uno de estos valores: 1:1, 16:9, 9:16, 3:4, 4:3, auto	Si se omite: aspect_ratio: missing required field "aspect_ratio". Con "2:1": value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'
negative_prompt	Cadena opcional	Se acepta. Reduce el texto en los atrezos, pero no lo elimina (ver control de calidad)
seed	Cadena opcional	Número (12): seed: got number, want string. Cadena no numérica ("sku-dripper-01"): se acepta con HTTP 200 y luego la tarea termina con TASK_FAILED. Cadena numérica ("1042"): funciona correctamente
Cualquier otra cosa	Se rechaza	additional properties 'foo' not allowed

El problema de seed nos costó una ronda extra. Resulta tentador usar el código de SKU como seed para poder rastrear las reejecuciones, y el validador lo permitía. Las cuatro tareas de nuestro primer lote devolvieron lo siguiente:

{"code":200,"data":{"error":{"code":"TASK_FAILED","message":"task failed"},"model":"imagen-4.0","status":"fail"}}

Después fuimos quitando campos uno a uno. El mismo prompt solo con negative_prompt tuvo éxito; solo con "seed": "sku-dripper-01" falló; y "seed": "1042" tuvo éxito. Mantén el seed como número y guarda la correspondencia de SKU en tu propia tabla de tareas.

El tamaño de salida depende de la proporción. En nuestras pruebas, 1:1 devolvió 1024×1024, 4:3 devolvió 1152×864 y 9:16 devolvió 720×1280, todos en WebP. Si tu tienda necesita imágenes ampliadas a 2000 px, planifica un paso de escalado. La salida no tendrá ese tamaño por sí sola.

Prompts para conjuntos de imágenes de catálogo

Escribe las plantillas de prompt por tipo de toma y no por producto, y luego rellena la descripción del producto. Mantén la iluminación, el ángulo de cámara y el fondo consistentes entre SKU para que la cuadrícula de imágenes de producto parezca parte del mismo catálogo.

Imagen de producto (1:1). Especifica el fondo, la composición, una única dirección de luz y la sombra que quieres:

Studio packshot of a matte sage-green ceramic coffee mug with a thin loop handle
on a seamless pure white background, centered, handle pointing right, eye-level view,
soft diffused key light from the left, gentle contact shadow, e-commerce catalog photography

El resultado de la taza fue limpio: el asa apuntaba a la derecha como se pidió, la sombra era suave y el fondo uniforme. No hizo falta ninguna edición.

Escena de estilo de vida (4:3). Indica el sujeto, la superficie, la dirección de la luz y qué atrezos deben estar desenfocados. Luego reitera que el producto es el sujeto nítido:

Lifestyle product photo: a matte sage-green ceramic pour-over dripper sitting on a glass carafe
on a light oak kitchen counter, morning window light from the right, a bag of coffee beans and a
gooseeneck kettle softly out of focus in the background, warm natural tones, shallow depth of field,
the dripper is the sharp hero of the frame

Ese prompt generó la imagen que aparece al principio de este artículo.

Imagen vertical para stories (9:16). Si vas a poner un titular arriba, pide explícitamente espacio negativo:

Vertical lifestyle product photo for a mobile story: overhead flat lay of a matte sage-green ceramic
pour-over dripper on a linen napkin, scattered roasted coffee beans, a small ceramic cup of black coffee,
on a pale stone surface, soft even daylight, generous empty space in the top third for a headline

El tercio superior quedó vacío como se pidió. Pero fíjate en que los granos de café enteros están dentro del gotero: nadie prepara café así, y los compradores de café lo notarán. Más detalles abajo.

Código de procesamiento asíncrono por lotes

La generación de imágenes de HiAPI es asíncrona: POST /v1/tasks devuelve un taskId y luego se consulta GET /v1/tasks/{taskId} hasta que status sea success o fail (ver la documentación de la API asíncrona). Para un catálogo de productos, envía todas las tareas a la vez y consulta en paralelo. Este es el script que ejecutamos, con los prompts abreviados. Las dos imágenes de escena provienen directamente de ese script. Las dos imágenes de producto se generaron una a una con los mismos prompts mientras investigábamos el fallo de seed mencionado antes (la imagen de producto del gotero sin seed).

import os, time, json, concurrent.futures as cf
import requests

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

NEG = "text, logo, watermark, hands, people, clutter, reflections of camera"

JOBS = [
    {"sku": "dripper-white", "aspect_ratio": "1:1", "seed": "1041", "prompt": "Studio packshot of ..."},
    {"sku": "mug-white",     "aspect_ratio": "1:1", "seed": "1042", "prompt": "Studio packshot of ..."},
    {"sku": "dripper-scene", "aspect_ratio": "4:3", "seed": "2041", "prompt": "Lifestyle product photo: ..."},
    {"sku": "dripper-story", "aspect_ratio": "9:16", "seed": "3041", "prompt": "Vertical lifestyle product photo ..."},
]

def submit(job):
    body = {"model": "imagen-4.0",
            "input": {"prompt": job["prompt"], "aspect_ratio": job["aspect_ratio"],
                      "negative_prompt": NEG, "seed": job["seed"]}}  # seed: digits only
    r = requests.post(API, headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        data = r.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(4)
    raise TimeoutError(task_id)

def run(job):
    t0 = time.time()
    task_id = submit(job)
    data = wait(task_id)
    if data["status"] != "success":
        return {"sku": job["sku"], "status": "fail", "error": data.get("error")}
    url = data["output"][0]["url"]
    img = requests.get(url, timeout=60).content
    path = f"{job['sku']}.webp"
    open(path, "wb").write(img)          # download now: output URLs expire
    return {"sku": job["sku"], "status": "success", "task_id": task_id,
            "seconds": round(time.time() - t0, 1), "bytes": len(img), "file": path}

with cf.ThreadPoolExecutor(max_workers=4) as pool:
    for result in pool.map(run, JOBS):
        print(json.dumps(result))

Tres detalles importantes en producción:

1. Las tareas fallidas siguen devolviendo HTTP 200. Comprueba data.status == "fail" y data.error.code. No confíes solo en raise_for_status().
2. Descarga de inmediato. output[0].url es un enlace temporal con una marca de tiempo expireAt (en nuestras respuestas, unos 7 días). Copia los bytes en tu propio almacenamiento o CDN. No enlaces directamente esa URL desde tu tienda.
3. Registra el id de tarea junto al SKU. Cuando un revisor rechace una imagen, necesitarás saber el prompt, el seed y el id de tarea que la generaron.

En nuestras pruebas, una tarea individual se completó en el servidor en 7–8 segundos (created → completed). Dos tareas de escena en paralelo tardaron 31 y 42 segundos en tiempo real, incluyendo el intervalo de sondeo de 4 segundos y la descarga. Con max_workers=4, en lotes pequeños domina la sobrecarga del sondeo más que el tiempo de generación.

Control de calidad: qué revisar antes de publicar las imágenes

La generación de texto a imagen produce productos verosímiles, no fotografías del artículo que tienes en tu almacén. Cada imagen debe revisarse manual o automáticamente contra el SKU real. Estos son los problemas que encontramos en un lote de 4 imágenes:

Comprobación	Lo que ocurrió en nuestro lote	Cómo solucionarlo
Solo aparece el producto indicado	La imagen de producto del gotero añadió una jarra de vidrio verde a juego con asa que el prompt nunca pidió (ver arriba).	Añade «single object, nothing else in frame» y vuelve a intentarlo. Nunca publiques un conjunto que no vendes.
Acabado superficial y material	Pedimos un esmalte «mate». Las dos imágenes del gotero devolvieron un acabado brillante. La taza se acercó más a un acabado satinado.	Trata las palabras de material como sugerencias. Compáralas con el producto real y rechaza las que no coincidan.
Texto en los atrezos	La bolsa de café de la escena de estilo de vida tenía una marca similar a un logo y texto de etiqueta ilegible, incluso con negative_prompt: "text, logo".	No incluyas atrezos con etiquetas en el prompt, o desenfócalos o recórtalos. Nunca dejes que aparezca texto falso en una ficha de producto.
Lógica del producto	La imagen cenital colocaba granos de café enteros dentro del gotero.	Haz que alguien que conozca la categoría del producto revise las imágenes de escena.
Consistencia entre imágenes	El patrón de nervaduras y la forma de la base del gotero variaban entre la imagen de producto, la escena y la imagen cenital.	No mezcles imágenes generadas del «mismo» SKU en una misma página de producto, a menos que coincidan con el artículo real.
Tamaño y proporción	Todas las salidas respetaron las proporciones solicitadas (1024², 1152×864, 720×1280).	Comprueba automáticamente las dimensiones en píxeles tras la descarga.

El último punto es la decisión clave para la tienda. Usa Imagen 4 para banners de categoría, imágenes de ambiente de estilo de vida, creatividades publicitarias y marcadores de posición para productos que solo existen como especificaciones. Para las fotos de ficha que deben mostrar tu artículo exacto, empieza con fotografías reales del producto y cambia a un modelo de imagen a imagen. Nuestra guía de comercio electrónico de imagen a imagen con Seedream 4.5 detalla ese flujo de trabajo.

Preguntas frecuentes

¿Puede imagen-4.0 colocar mi producto real en una escena nueva? No. En HiAPI solo acepta prompt, aspect_ratio, negative_prompt y seed. No hay campo de entrada de imagen, así que no puedes usar la foto de tu producto como referencia.

¿negative_prompt elimina todo el texto? En nuestras pruebas, no. Vale la pena enviarlo, pero en los atrezos de fondo de la escena de estilo de vida seguía apareciendo texto falso en las etiquetas. La solución fiable es evitar los atrezos con etiquetas.

¿Por qué mi tarea falla inmediatamente con TASK_FAILED? Revisa primero tu seed. Cadenas no numéricas como "sku-dripper-01" pasan la validación, pero en nuestras pruebas todas las tareas fallaron. Usa números en forma de cadena, por ejemplo "1042".

¿Google-Imagen4 es otro modelo? En nuestras pruebas, las solicitudes enviadas con "model": "Google-Imagen4" tuvieron éxito, mientras que la carga de la tarea informaba "model": "imagen-4.0". Usa imagen-4.0 en el código nuevo.

Siguientes pasos

Elige un producto, escribe las tres plantillas de prompt anteriores para él y ejecuta el script por lotes contra el modelo Imagen 4. Si vas a integrarlo en un flujo de trabajo de catálogo, la documentación de la API asíncrona cubre la autenticación y el sondeo.