Guía de uso
Generación de imágenes de productos de comercio electrónico con qwen-image-2.1-turbo mediante la API de HiAPI
Flujo de trabajo visual de catálogo rápido para desarrolladores: salida PNG transparente y una solicitud de API ejecutable
En esta página
Casos de uso de qwen-image-2.1-turbo
El trabajo con imágenes de catálogos de productos parece un problema creativo, pero en realidad es un problema de rendimiento. Una sola imagen principal se puede retocar a mano, pero una tienda con miles de SKU necesita una composición coherente, plazos de entrega predecibles y una salida que se integre directamente en la canalización de recursos existente. El modelo de imagen que elijas determina cuánta canalización tendrás que reconstruir.
Normalmente hay tres criterios que rigen esta decisión:
- Latencia bajo carga. Las tareas nocturnas de catálogo son tareas por lotes; un modelo que funciona bien en escenarios interactivos puede hacer que la actualización de 10.000 SKU resulte dolorosa.
- Adaptación del formato de salida. Si tu fase de composición necesita un canal alfa y el modelo solo devuelve imágenes opacas, tendrás que añadir tú mismo un paso de segmentación.
- Rendimiento con el lenguaje de las descripciones de productos. Los prompts de producto son breves, concretos y repetitivos; un modelo que maneja estos prompts de forma estable supera a uno que destaca con prompts artísticos abiertos.
Esta guía se centra en los dos primeros criterios y en el patrón de solicitud que conecta ambos. Analizaremos cómo se posiciona la variante turbo en la canalización de imágenes de productos, cómo cambia la salida PNG transparente tu cadena de posprocesamiento y ofreceremos una solicitud que se puede colocar directamente en un worker. Por último, trataremos los aspectos a tener en cuenta al escalar por lotes y compararemos brevemente con el enfoque de imagen a imagen cuando la generación basada en texto no sea adecuada.

Salida PNG transparente y tu cadena de posprocesamiento
Puedes concebir la canalización de imágenes de productos como cuatro etapas: construcción de la solicitud → generación → procesamiento de la salida → publicación. La variante turbo es una apuesta deliberada: hacer que la segunda etapa sea lo suficientemente rápida y económica como para soportar la escala del catálogo, de modo que puedas invertir tu presupuesto de ingeniería en la primera y la tercera etapa.
Cuándo es la opción predeterminada correcta
Elige qwen-image-2.1-turbo en los siguientes casos:
- Tus prompts están estructurados y son repetibles: una plantilla por categoría, con espacios para el material, el color, el ángulo y la intención del fondo.
- Necesitas generar muchas variantes por SKU (ángulos, combinaciones de colores, escenarios) en lugar de una única imagen con una dirección artística cuidada.
- Tu composición posterior ya está automatizada, por lo que un recorte limpio aporta más valor que una escena completamente terminada.
- Quieres obtener primero una base basada en texto antes de introducir imágenes de referencia.
Cuándo se necesita un modelo más potente
Si un SKU requiere una composición muy específica que coincida estrictamente con una foto de referencia, o si el cuello de botella es la calidad de la salida en escenas complejas y no la cantidad, el nivel turbo no es la opción predeterminada adecuada. En ese caso, mantén turbo para la mayoría de las variantes del catálogo y envía un pequeño conjunto de imágenes principales a una ruta de generación más pesada: la forma de la canalización no cambia, solo se sustituye el identificador del modelo.
Diseñar un espacio de modelo intercambiable
Dado que el nivel turbo está pensado para la escala, el nombre del modelo debe tratarse como configuración, no como una constante codificada dispersa por el código base. Leer una variable de entorno IMAGE_MODEL al iniciar el worker significa que puedes hacer pruebas A/B con otro modelo en algunas categorías sin modificar el código de la solicitud. Esa decisión es la que hace portátil el resto de esta guía.

Una solicitud ejecutable de imágenes de productos en HiAPI
El PNG transparente es la opción de salida con mayor apalancamiento en las canalizaciones de catálogo, porque adelanta a la fase de generación el paso costoso: separar el producto del fondo. En lugar de segmentar una imagen renderizada opaca, recibes un recurso con canal alfa y luego lo compones tú mismo.
Qué cambia en las etapas posteriores
Con un canal alfa, el fondo pasa a ser una preocupación de la fase de renderizado, no de la de modelado. El mismo recorte se puede colocar sobre un fondo de estudio blanco como imagen principal de la página de producto, en una escena de estilo de vida para un espacio de marketing, o sobre un color de marca plano como mosaico de categoría, todo a partir de una sola generación. Esa es la economía central: un recurso de producto, múltiples variantes publicadas.
En la práctica, planifica los siguientes pasos:
- Validar el canal alfa. Comprueba que la imagen tenga realmente un canal alfa no trivial y que el sujeto no esté recortado en el borde del encuadre. Que el recorte toque el borde es un fallo de generación, no un problema de composición.
- Normalizar el lienzo. Antes de componer, redimensiona y rellena el recorte en un lienzo coherente para que la posición de los distintos SKU sea predecible.
- Componer por separado para cada ubicación de publicación. Guarda los ajustes predefinidos de fondo como datos (dimensiones, color, recursos de fondo opcionales) y renderiza cada ubicación de publicación a partir del mismo PNG de origen.
- Almacenar el archivo de origen y publicar los renderizados. Conserva la imagen original transparente como recurso canónico y trata cada variante compuesta como un derivado que se puede volver a generar.
Ten en cuenta el compromiso con el tamaño de archivo: el canal alfa hace que los PNG sean más grandes, y el almacenamiento del catálogo lo multiplica por cada variante. Si tu CDN ofrece WebP o AVIF, convierte en el momento de la publicación y conserva el archivo PNG de origen.

Escalar a tareas por lotes y evitar trampas de integración
Todo lo siguiente se ejecuta sobre la interfaz unificada de HiAPI: una URL base, una credencial y una forma de solicitud coherente entre modelos. Antes de fijar el esquema, consulta la lista exacta de parámetros y los nombres de campo actuales en la página del modelo qwen-image-2.1-turbo; lo importante aquí es el patrón en sí.
Forma de la solicitud
La llamada de imágenes de productos consta de un prompt y una especificación de salida. Construye el prompt a partir de una plantilla para que cada SKU solo aporte sus propias variables:
import os, requests
HIAPI_KEY = os.environ["HIAPI_API_KEY"]
MODEL = os.environ.get("IMAGE_MODEL", "qwen-image-2.1-turbo")
def product_prompt(sku):
return (
f"studio product photo of {sku['name']}, {sku['material']}, "
f"{sku['color']} finish, three-quarter view, soft even lighting, "
"centered on a plain background, no text, no props"
)
def generate(sku):
resp = requests.post(
"https://api.hiapi.ai/v1/images/generations",
headers={"Authorization": f"Bearer {HIAPI_KEY}"},
json={
"model": MODEL,
"prompt": product_prompt(sku),
"transparent_background": True,
"n": 1,
},
timeout=120,
)
resp.raise_for_status()
return resp.json()
Dos observaciones sobre el cuerpo de la solicitud. Primero, solicita explícitamente el fondo transparente: es un parámetro de la llamada, no algo que se deduzca después de la descarga. Segundo, mantén un valor bajo de n en cada llamada y paraleliza a nivel de tarea; reintentar un lote de solicitudes de una sola imagen es mucho más limpio que una solicitud de veinte imágenes, ya que en esta última basta con que falle una para perder todo el grupo.
Gestionar la respuesta de forma defensiva
La respuesta contiene los datos de la imagen (una URL o una carga codificada, según los parámetros que envíes). Trata la obtención como un dominio de fallo separado de la generación: una vez que la generación devuelve el resultado, descarga, valida y sube a tu propio almacenamiento. A partir de ahí, tu canalización hace referencia a tu bucket, no a un resultado temporal, y eso es precisamente lo que permite controlar los reintentos y las regeneraciones.
Comparación con el enfoque de imagen a imagen
La diferencia entre un script ejecutable y una tarea de catálogo ejecutable casi siempre aparece en las partes aburridas.
Convertir las plantillas de prompts en datos
Coloca los fragmentos de prompts en archivos de configuración por categoría, no en el código. Cada SKU aporta los espacios; la categoría aporta la estructura de las frases y las restricciones negativas ("no text, no watermarks, no props"). Cuando la composición de una categoría no sea la correcta, solo tendrás que corregir una plantilla en lugar de miles de líneas de datos.
Reintentar con criterio
Distingue los fallos reintentables (tiempos de espera agotados, errores temporales del servidor, límites de velocidad) de los fallos terminales (parámetros no válidos, prompts rechazados). Reintenta los primeros con retroceso exponencial y un límite de reintentos; falla inmediatamente y expón el motivo en los segundos, porque reintentar una solicitud mal formada solo consume la cola. La idempotencia es importante aquí: usa el SKU más un hash del prompt como clave de cada tarea, de modo que una tarea reintentada sobrescriba en lugar de duplicar.
Validar antes de que sea visible en la tienda
Inserta una barrera de validación entre la generación y la publicación. Las comprobaciones automáticas de bajo coste detectan la mayoría de las salidas defectuosas:
- Existe un canal alfa y el sujeto no está recortado en los bordes.
- La resolución cumple el requisito mínimo de la ubicación de publicación más grande.
- Se realiza un hash perceptual frente a los recursos actuales para marcar duplicados cercanos inesperados.
Envía el contenido que no supera la barrera a una cola de revisión en lugar de descartarlo directamente. Los fallos silenciosos son justamente la forma en que un catálogo se llena sin aviso con productos de colores incorrectos.
Atención a los límites de concurrencia
Las tareas por lotes suelen alcanzar los límites de velocidad de forma repentina, no gradual. Limita la concurrencia de los workers por debajo del límite que consideres, haz que ese límite sea configurable y deja que la cola absorba la acumulación. Una canalización limitada por velocidad pero que termina es mejor que una que oscila de un lado a otro.
Presupuestar por salida, no por solicitud
La facturación depende de las salidas que generas, así que registra el número de recursos generados por SKU como señal de coste. Cuando una categoría empieza a generar muchas variantes por producto, se trata de una decisión de diseño de prompts que debes tomar deliberadamente, no de algo que debas descubrir en la factura.
Comparación con el enfoque de imagen a imagen
Cuando el producto todavía no dispone de una foto utilizable (un SKU nuevo que aún no se ha fotografiado, un producto con un color nuevo que nunca se ha fotografiado, o recursos provisionales para el lanzamiento), la generación basada en texto es la opción predeterminada correcta. El prompt describe el resultado por completo y la salida transparente te proporciona un recurso que puedes componer sin necesidad de un paso de segmentación.
El enfoque de imagen a imagen invierte la entrada. Proporcionas una imagen de referencia, el modelo trabaja a partir de ella y eso es exactamente lo que se necesita cuando la fidelidad al producto real no es negociable: coincidir con las costuras reales, los acabados reales de los herrajes y el tono exacto que recibirá el cliente. En este modo, la imagen de referencia es la restricción que mantiene fiel la generación.
Para la mayoría de los catálogos, una división práctica:
- Texto a imagen turbo para la escala: variantes, fondos, mosaicos de categoría e imágenes provisionales para las primeras publicaciones.
- Imagen a imagen para cualquier situación en la que el cliente vaya a tomar una decisión de compra y la precisión visual sea fundamental.
Ambos comparten el mismo esqueleto de canalización, por lo que cambiar supone solo un identificador de modelo y un campo de entrada, no una reescritura. Cuando necesites salidas guiadas por una imagen de referencia, el modelo de imagen a imagen qwen-image-3.0 se puede conectar al mismo worker simplemente adjuntando la imagen de referencia junto al prompt.
Ejecuta primero la ruta turbo en una categoría, mide la tasa de aprobación de la validación y luego amplía de forma gradual; la página del modelo enumera los campos que necesitas conectar.
Artículos relacionados
Ver todos los artículos →-
Guía de uso
Guía de inicio de Tripo H3.1: cómo elegir entre tres modos de entrada, parámetros y precios
Guía práctica de decisiones de integración y control de costes de la generación 3D para desarrolladores
-
Guía de uso
Uso de topaz-upscale/video con la API de HiAPI: flujo de trabajo para mejorar la calidad de videos cortos
Interpolación de fotogramas, ajustes de mejora y una solicitud de HiAPI funcional para video vertical
-
Guía de uso
Generación de imágenes de productos de comercio electrónico con gpt-image-2.5-sunburst/image-to-image mediante la API de HiAPI
Imágenes de referencia, sustitución de fondos, escenas de estilo de vida y una solicitud funcional de HiAPI