Generar imágenes de producto para e-commerce con qwen-image-2.1-pro: uso de la API y recetas de prompts

Por qué vale la pena elegir qwen-image-2.1-pro para imágenes de producto de e-commerce

El trabajo de imágenes para e-commerce rara vez consiste en una sola cosa. Puede ser una sesión de catálogo para un SKU nuevo, un recorte para la ficha de producto de un marketplace, una imagen de estilo de vida para una landing page y un banner con una etiqueta de promoción; normalmente todo dentro de la misma semana. Lo que hace que qwen-image-2.1-pro merezca evaluarse es que, cuando tu flujo necesita producir todo lo anterior a partir de los mismos datos de producto, resuelve en un único modelo la generación, la edición de recursos existentes, la salida de PNG transparentes y el renderizado de texto en la imagen, en lugar de depender de una cadena de herramientas especializadas.

Tres tipos de tarea cubren la mayor parte del volumen de trabajo:

• Recorte transparente: el producto queda separado limpiamente sobre un fondo transparente, listo para colocarse en cualquier ubicación del CMS.
• Composición de escena: el producto se sitúa en un entorno de estilo de vida o de estudio creíble, generado a partir de una descripción textual más una imagen de referencia.
• Maquetación con texto: etiquetas, insignias y banners donde el texto debe ser legible y estar bien posicionado.

Donde no sustituye al estudio: en la imagen principal con requisitos estrictos de iluminación de marca y en cualquier recurso cuya geometría del producto esté regulada (por ejemplo, envases sujetos a normativa). Considera la generación como un medio para ampliar la cobertura y acelerar la iteración, y luego conserva una puerta de aprobación humana; para eso sirve precisamente el proceso de revisión que aparece más adelante en esta guía.

La razón práctica para decidir esto pronto es la arquitectura de prompts. Si sabes desde el principio que el mismo modelo va a servir para recortes, escenas y maquetaciones con texto, puedes crear un pequeño conjunto de plantillas de prompts versionadas en lugar de escribir prompts improvisados en cada solicitud. Esa decisión no cuesta nada al principio y evita tener que reescribirlo todo más adelante.

Solicitudes ejecutables: curl y Python

Antes de diseñar prompts, consigue primero una imagen. En HiAPI la forma de las solicitudes es consistente entre modelos: una clave de API, un nombre de modelo y los parámetros de entrada en el cuerpo de la solicitud. El parámetro mínimo que requiere qwen-image-2.1-pro es el prompt, además, si la tarea es una edición en lugar de una generación desde cero, la imagen de entrada que quieres editar.

curl

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-pro",
    "prompt": "Fotografía de producto de estudio de una taza de café de cerámica negra mate, vista de tres cuartos, luz principal suave y difusa desde la izquierda, ligero reflejo sobre un fondo continuo gris claro, sin texto",
    "size": "1024x1024"
  }'

Python requests

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-image-2.1-pro",
        "prompt": "Fotografía de producto de estudio de una taza de café de cerámica negra mate, "
                  "vista de tres cuartos, luz principal suave y difusa desde la izquierda, "
                  "ligero reflejo sobre un fondo continuo gris claro, sin texto",
        "size": "1024x1024",
    },
    timeout=120,
)
resp.raise_for_status()
print(resp.json())

Vale la pena adquirir dos hábitos en esta etapa. Primero, lee la clave de API desde una variable de entorno, nunca la codifiques directamente; pronto la ejecutarás desde trabajos por lotes. Segundo, conserva el cuerpo completo de la respuesta al registrar logs, incluidos los campos de uso que devuelva el endpoint; eso es lo que usarás después para medir el «coste por recurso aprobado» en lugar de adivinarlo.

Ejecuta primero una solicitud con un prompt genérico como el anterior. Confirma que obtienes la imagen y que la estructura de la respuesta coincide con lo que espera tu código posterior. Solo entonces pasa a las recetas: el diseño de prompts lleva tiempo y no querrás descubrir a mitad de camino que hay un problema en la tubería.

Recetas de prompts para PNG transparentes y escenas de producto

Los prompts improvisados tienden a desviarse. Los equipos de catálogo obtienen resultados consistentes manteniendo un pequeño conjunto de plantillas con huecos de variables explícitos, versionándolas en el repositorio junto con el código que llama a la API y sustituyendo solo los huecos por cada SKU.

Receta 1: recorte transparente

Recorte de producto de {product_name}, {distinguishing_detail}, completamente separado sobre un fondo transparente.
Vista {view_angle}, producto centrado y completamente dentro del encuadre, con un pequeño margen alrededor.
Iluminación de estudio suave y uniforme, sin sombras duras proyectadas sobre el fondo, solo una ligera sombra de contacto justo debajo del producto.
Fotorrealista, bordes nítidos, sin texto, sin atrezo, sin elementos de fondo.

Huecos: {product_name} («una taza de café de cerámica negra mate»), {distinguishing_detail} («el grosor visible del borde y un asa pequeña»), {view_angle} («de tres cuartos», «frontal», «cenital»). La cláusula de transparencia y la de «no proyectar sombra sobre el fondo» deben conservarse tal cual; esas dos líneas hacen la mayor parte del trabajo en las tareas de recorte.

Receta 2: escena de estilo de vida

Fotografía de producto de estilo de vida de {product_name} en {scene_description}.
El producto es el sujeto principal: enfoque nítido, proporciones correctas, {brand_color_note}.
{lighting_note}. Profundidad de campo reducida, fondo con desenfoque suave.
Estilo natural y editorial. Sin texto, sin logotipos, sin marcas visibles en el fondo.

Huecos: {scene_description} («una encimera de cocina luminosa y minimalista, con una servilleta de lino y una ventana de luz matinal»), {brand_color_note} («color sin modificar, sin dominante de color aplicada»), {lighting_note} («luz matinal cálida y direccional proveniente de la derecha»).

Receta 3: imagen principal de estudio

Fotografía de producto de estudio de {product_name}, vista {view_angle}.
{background_description}. Luz principal desde {key_light_direction}, relleno suave, reflejos controlados.
Fotorrealista, gran detalle en materiales y textura superficial. Sin texto.

Dos reglas mantienen sana la biblioteca de plantillas. Nunca modifiques la plantilla directamente en el script: modifica el archivo de plantilla, incrementa la versión y vuelve a generar. Y registra qué versión de receta produjo cada recurso aprobado, de modo que cuando cambie una plantilla puedas determinar si las aprobaciones antiguas siguen siendo válidas.

Editar imágenes de producto existentes

Las solicitudes de edición son donde surgen la mayoría de los problemas de calidad, porque un prompt ambiguo hace que el modelo regenere el producto en lugar de modificar su entorno. Divide cada prompt de edición explícitamente en tres partes:

1. Qué cambiar: la escena, el fondo, la iluminación o el atrezo añadido.
2. Qué conservar: la forma, las proporciones, el patrón de la etiqueta, el material y el color del producto.
3. Qué evitar: texto nuevo, logotipos nuevos, geometrías distorsionadas, piezas duplicadas.

Una plantilla que funciona:

Edita esta fotografía de producto.
Cambiar: sustituye el fondo por {new_background}; ajusta la iluminación a {new_lighting}.
Conservar: la forma exacta, las proporciones, el material superficial y cualquier patrón de etiqueta del producto, exactamente como están.
No: añadir texto, añadir logotipos, cambiar el color del producto ni alterar su geometría.
Resultado fotorrealista que parezca una fotografía tomada de forma continua.

Ejemplo de relleno: {new_background} = «un fondo continuo gris cálido y limpio», {new_lighting} = «luz cenital suave y difusa, con un degradado suave detrás del producto».

Las cláusulas de conservación no son una garantía. Las ediciones extensas —sustituir el fondo, ajustar la iluminación y añadir atrezo en un solo prompt— dan al modelo más margen para desviarse en el propio producto. Hazlo por partes: primero la sustitución del fondo, revísala, y luego aplica cambios secundarios editando el resultado intermedio ya aprobado. Cada paso es una comparación que un revisor puede evaluar de verdad.

Además, conserva una imagen de referencia estándar para cada SKU. Cuando el revisor dude si el producto ha cambiado, la referencia es la verdad de base, no la última generación.

Renderizado de texto y control de maquetación

El texto en la imagen es la función que más decepciona cuando se pide de forma improvisada. El texto que debe aparecer en el recurso final tiene que ir entre comillas, posicionado y acotado.

Banner de e-commerce de {product_name}.
Maquetación: producto en el tercio derecho, bloque de texto en los dos tercios izquierdos, con márgenes amplios.
Texto: renderiza exactamente «{headline}» como titular principal en negrita sans serif, y exactamente «{subline}» debajo con un peso más ligero.
Estilo: {color_scheme}, limpio y moderno, alto contraste para garantizar la legibilidad.
No debe aparecer texto en ninguna otra parte de la imagen. Todas las palabras escritas exactamente como se indican.

Por qué importa cada línea:

• Texto entre comillas más una instrucción explícita de «exactamente» reduce las reescrituras y las palabras inventadas.
• Posición y proporción («tercio derecho», «dos tercios izquierdos») impiden que el modelo entierre el producto bajo el titular.
• «No debe aparecer texto en ninguna otra parte de la imagen» es la cláusula que suprime el modo de fallo habitual: texto de relleno verosímil en las esquinas.
• Un titular corto y un subtítulo corto son mucho más fiables que un párrafo. Si tu maquetación necesita un bloque de copy, genera primero la imagen sin ese copy y maqueta el texto en el CMS o en la herramienta de diseño.

Para insignias y etiquetas (marcas de «New», indicadores de talla), trátalas como sus propios prompts pequeños en lugar de añadirlas a la imagen principal: un prompt de insignia con una sola palabra entre comillas es mucho más fácil de verificar en la revisión que un banner completo. Revisa siempre la ortografía a resolución completa antes de aprobar; un error de texto es barato de detectar y caro cuando ya está publicado.

Revisar la salida: el ciclo de comparación y aprobación

Los recursos generados no deben publicarse en la tienda sin una revisión humana. El ciclo más barato y fiable es una comparación antes/después recurso por recurso: coloca la foto de entrada (o la especificación, cuando sea una generación desde cero) junto a la salida generada, y registra la versión de la receta de prompt y los valores de las variables.

Un ciclo práctico para equipos pequeños:

1. Genera un lote pequeño: unos pocos variantes por SKU, no el catálogo entero.
2. Monta una tabla comparativa en paralelo: a la izquierda la imagen de origen, a la derecha la candidata, y debajo el prompt.
3. Revisa con una lista de comprobación breve y fija: forma del producto sin cambios, patrón de la etiqueta intacto, fondo limpio, texto bien escrito, márgenes suficientes.
4. Marca cada candidata como aprobada o rechazada, y registra la versión de receta que produjo el resultado aprobado.
5. Solo entonces despliega al lote completo reutilizando las recetas aprobadas. Si una receta cambia después de la aprobación, considera las aprobaciones existentes como temporales hasta volver a comprobarlas.

Mantén la lista de comprobación breve y siempre idéntica. Una lista constante de cuatro puntos detecta más problemas que un formulario largo aplicado de forma irregular. Guarda también las candidatas rechazadas: son la evidencia de por qué se descartó una versión de receta y evitan que la siguiente persona tenga que redescubrir los mismos fallos.

Este ciclo es también tu mecanismo de control de costes. Como la aprobación está vinculada a la receta, puedes calcular cuántas generaciones necesita cada recurso aprobado e iterar en las plantillas que consumen más intentos.

Consideraciones de coste, latencia y procesamiento por lotes

Planifica con tus propias mediciones, no con supuestos. En los modelos de imagen de HiAPI la facturación es por imagen de salida, así que la variable que domina el gasto es el «número de intentos por recurso aprobado», que depende por completo de la calidad del prompt y del rigor de la revisión. El precio actual por imagen está en la página de precios del sitio web; no incrustes cifras en el código ni en los documentos de presupuesto.

Un método de trabajo sensato:

• Mide una línea base. Ejecuta diez SKU con recetas aprobadas, cuenta el total de generaciones y el total de aprobaciones, y deriva los intentos por recurso aprobado. Esa ratio dice más que cualquier benchmark.
• Itera de una en una, aprueba y luego procesa por lotes. La iteración de prompts debe hacerse imagen a imagen. Una vez aprobada una receta, procesa por lotes con una concurrencia moderada y una política de reintentos que registre los fallos en lugar de facturar repeticiones silenciosas.
• Trata la latencia como un parámetro de planificación. La generación de imágenes se mide en segundos, no en milisegundos. Lanza los trabajos de forma asíncrona, escribe los resultados en una cola y deja que los revisores los procesen desde ahí en lugar de bloquearse en cada llamada.
• Presupuesta por ratio, no por precio unitario. Con los intentos por recurso aprobado en la mano, estimar el catálogo es una aritmética simple basada en tus propias mediciones.

Un último hábito de higiene: versiona tus recetas y registra la versión de la receta en cada solicitud. Cuesta un solo campo, pero convierte «¿por qué este recurso del mes pasado se ve distinto?» de una investigación en una consulta.

Construye el flujo mínimo que te permita ejecutar recortes, escenas y maquetaciones con texto a través de la API, mantén la biblioteca de prompts versionada y deja que el ciclo de revisión, y no la esperanza, decida qué se publica.