Blog

Guía de uso

muse-image-1.0/text-to-image para imágenes de productos de comercio electrónico: guía de flujo de trabajo para desarrolladores

Plantillas de indicación para ángulos e iluminación, selección de tamaño y solicitudes por lotes a través de la API de HiAPI

Nov 9, 2026
Cintas de latón plano entrelazadas con cintas de verde profundo que forman una celosía abierta sobre un fondo verde casi negro — portada de esta guía.
En esta página

Por qué text-to-image encaja en cargas de trabajo de productos de comercio electrónico

Un catálogo es, por naturaleza, repetitivo: el mismo producto, fotografiado desde unos pocos ángulos, con la misma iluminación, sobre el mismo fondo, en varios tamaños. Esa repetición es exactamente lo que los modelos text-to-image hacen bien: no para sustituir la sesión de estudio del producto estrella, sino para cubrir la cola larga del catálogo de forma económica y consistente.

Escenarios en los que la generación aporta valor real:

  • Variantes a gran escala. Combinaciones de colores, diferencias menores entre SKU y rediseños de packaging en los que volver a fotografiar cuesta más que el valor de la propia imagen.
  • Marcadores de posición y material previo al lanzamiento. Páginas de listado, materiales de revisión interna y pruebas A/B que necesitan contenido verosímil antes de que llegue la fotografía definitiva.
  • Exploración de composición. Probar vistas cenitales planas frente a tomas principales a 45 grados antes de comprometer al fotógrafo y la agenda del estudio.

Escenarios no adecuados: declaraciones publicitarias reguladas, texto de packaging que debe ser nítido y exacto, e imágenes principales en las que el cliente comparará texturas finas. Esas siguen requiriendo cámara y persona.

Para el desarrollador, el modelo mental es una línea de producción. Entra una descripción estructurada del producto, se renderiza una plantilla de indicación, el modelo devuelve una o varias imágenes y una revisión de QA decide qué puede publicarse en la tienda. Cada sección siguiente trata de hacer que esta línea sea aburrida y repetible, en lugar de inteligente.

La línea de producción del catálogo es como un tejido plano: una indicación entra en la estructura de cuadros y la misma estructura produce varias imágenes de producto independientes.

Llamar a muse-image-1.0/text-to-image a través de HiAPI

Todas las solicitudes pasan por la misma interfaz de HiAPI, así que te autenticas una vez y mantienes un único cliente para todos los modelos que llames. El identificador del modelo es muse-image-1.0/text-to-image; tu solicitud lleva la indicación, la elección de tamaño de salida y cualquier opción de generación única que quieras fijar.

Estructuralmente, una generación individual consiste en: construir la carga útil de la solicitud, enviarla por POST mediante el cliente de HiAPI, leer el objeto de resultado devuelto y persistir la referencia de la imagen junto con el ID de producto al que pertenece. Dos hábitos que merece la pena adoptar desde la primera llamada:

  1. Guardar la indicación en una variable, no en línea dentro de la solicitud. La vas a reutilizar y comparar cientos de veces.
  2. Registrar la indicación renderizada exacta de cada salida. Cuando las imágenes parezcan mal dentro de tres semanas, la indicación será tu única base de depuración.
import os
from hiapi import HiAPI

client = HiAPI(api_key=os.environ["HIAPI_API_KEY"])

prompt = render_product_prompt(product, angle="three-quarter", light="softbox-left")

result = client.images.generate(
    model="muse-image-1.0/text-to-image",
    prompt=prompt,
    size="1024x1024",
)

save_asset(product_id=product.id, angle="three-quarter", result=result)

Trata size como parte de la plantilla, no como una ocurrencia tardía: la misma indicación puede recomponer el sujeto en distintas relaciones de aspecto. Las secciones siguientes cubren tanto la estructura de la indicación como la decisión del tamaño.

La solicitud va del cliente al endpoint y al modelo; las cintas trenzadas devuelven una imagen de resultado.

Plantillas de indicación para ángulos de cámara consistentes

La consistencia en un catálogo proviene de un esqueleto de indicación fijo en el que solo se sustituyen unas pocas ranuras. Si cada indicación se escribe desde cero, cada imagen saldrá desplazada. Crea una plantilla por tipo de toma y mantén el lenguaje de descripción de cámara idéntico byte a byte entre todos los productos.

Un esqueleto que funciona:

{subject_block}. {camera_block}. {light_block}. {background_block}. {style_block}

Solo subject_block cambia según el producto. camera_block es una constante por ángulo:

  • Toma principal / tres cuartos: product photographed at a 45-degree three-quarter view, slightly above eye level, full product in frame with even margins
  • Alzado frontal: straight-on front view, camera at product mid-height, centered, no perspective tilt
  • Cenital plana: directly overhead top-down view, product centered, flat lay composition
  • Primer plano de detalle: close-up macro view of the product surface, shallow depth of field

Dos reglas hacen que esto funcione en la práctica:

  • Indica el ángulo dos veces. Un ángulo explícito más una cláusula de composición (como "full product in frame with even margins") es más fiable que cualquiera de los dos por separado.
  • Evita referencias relativas. "Same angle as the last image" no significa nada para un modelo text-to-image; cada indicación debe sostenerse por sí sola.

Guarda la plantilla en control de versiones junto al código de renderizado. Cuando modifiques camera_block, sube el número de versión y regenera una pequeña muestra antes de hacer commit: un cambio de redacción es un cambio en todo el catálogo.

Plantillas de indicación para iluminación y fondo

La iluminación y el fondo son lo que hace que un conjunto de imágenes generadas parezca una sola sesión y no una pila de imágenes no relacionadas. Ambos forman parte de las constantes de la plantilla y necesitan dirección y suavidad explícitas.

Lenguaje de iluminación que se transfiere de forma fiable:

  • Dirección: key light from camera left, light from upper right, soft overhead light. La dirección es la palanca de consistencia más directa: fíjala para cada tipo de toma.
  • Calidad: soft diffused light, large softbox, gentle shadows, hard directional light with defined shadow edge.
  • Relleno y derrame: subtle fill from the right, low-contrast shadows, clean highlight on the top surface.

Lenguaje de fondo:

  • Estudio sin costuras: on a seamless light grey studio backdrop, no horizon line, soft contact shadow beneath the product.
  • Superficie de estilo de vida: resting on a matte stone surface, softly out-of-focus neutral background.
  • Apto para recorte: isolated on a plain white background, product fully in frame, generous margins for cropping.

Dos recordatorios prácticos. Primero, cuanto más superficie y reflejos tenga el producto, más precisa debe ser la descripción de la iluminación, porque la posición de los reflejos especulares es el aspecto del producto. Segundo, no mezcles fondos dentro del mismo tipo de toma: un conjunto de mosaicos de una cuadrícula debe compartir fondo, o la cuadrícula parecerá un collage de tres proveedores distintos. Fija estos bloques como constantes y cámbialos solo de forma deliberada.

Elegir el tamaño de salida y la relación de aspecto

Antes de procesar por lotes, decide el tamaño según la ubicación de destino, porque volver a ejecutar con otro tamaño es una regeneración completa, no un cambio de escala. Primero asigna la ubicación de destino a una relación de aspecto y luego a la dimensión en píxeles que el front-end renderiza realmente.

  • Cuadrículas y mosaicos de categoría: cuadrado. El recorte de las cuadrículas de producto es impredecible, así que una composición cuadrada con márgenes amplios se adapta a la mayoría de diseños de mosaico.
  • Página de detalle de producto: cuadrado o 4:3, dimensionado para el visor con zoom, no para la miniatura. Si la página de detalle recorta a una proporción fija, cópiala exactamente; no luches contra ella en CSS.
  • Banners y franjas principales: formato ancho con una zona segura planificada explícitamente. Pide el producto centrado y con espacio negativo a ambos lados para que el texto de marketing tenga sitio.
  • Correo electrónico y redes sociales: usa la proporción nativa de la plataforma; regenerar es más barato que añadir relleno.

Algunas reglas prácticas:

  1. Elige un tamaño canónico por ubicación de destino y reutilízalo. Mezclar tamaños en una cuadrícula de mosaicos produce diferencias de calidad visibles.
  2. No amplíes imágenes generadas para llenar un espacio mayor. Genera un tamaño mayor y redúcelo.
  3. Vuelve a comprobar la composición cuando cambie la proporción. Una toma principal a 45 grados compuesta para cuadrado puede perder la base del producto en un recorte ancho; ajusta en consecuencia la cláusula de composición en camera_block.
  4. Conserva el tamaño en el registro del trabajo. Cuando revises las salidas más tarde, el tamaño forma parte del contexto, no es ruido de metadatos.

Solicitudes por lotes y manejo de resultados individuales

A escala de catálogo, la unidad de trabajo es el trabajo, no la solicitud: un producto, un tipo de toma, un tamaño, una indicación renderizada. Modela primero los trabajos como datos y envíalos mediante una cola acotada, de modo que un fallo sea una fila que se puede volver a ejecutar y no una tarde perdida.

Un bucle robusto hace cuatro cosas:

  • Renderiza la indicación de forma determinista: a partir de la plantilla más los campos del producto, y guarda la cadena renderizada en el trabajo.
  • Limita la concurrencia: a lo que tu cuenta y el almacenamiento posterior puedan soportar; no lances todo el catálogo de una vez.
  • Procesa los resultados uno a uno. Las operaciones por lotes tienen éxito o fallan elemento a elemento, así que escribe cada resultado bajo su job_id y nunca asumas que el lote completo es atómico.
  • Reintenta con retroceso solo los errores transitorios. Los errores de validación —indicaciones mal formadas, tamaños no admitidos— fallarán igual al reintentar, así que clasifícalos antes de reintentar.
for job in queue.fetch_pending(limit=50):
    try:
        result = client.images.generate(
            model="muse-image-1.0/text-to-image",
            prompt=job.prompt,
            size=job.size,
        )
        db.record_success(job.id, result)
    except TransientError as e:
        queue.requeue(job.id, backoff=e.retry_after)
    except ValidationError as e:
        db.record_failure(job.id, reason=str(e))

Mantén una columna de estado por trabajo (pending, done, failed) y una vista de cola de mensajes muertos para los fallos. Cuando termine un lote, informa de los recuentos por tipo de toma y tamaño, no solo un total: ahí es donde se esconden las regresiones.

Lista de comprobación de QA antes de publicar imágenes generadas

Las imágenes generadas necesitan una barrera, y la barrera debe ser una lista de comprobación con una persona detrás. Las comprobaciones automatizadas capturan los problemas baratos; los revisores capturan los caros.

Comprobaciones automatizadas antes de la revisión:

  • Relación de aspecto y dimensiones en píxeles correctas para la ubicación de destino.
  • Sin salidas visiblemente corruptas; los archivos se abren y decodifican correctamente.
  • Los colores coinciden con lo esperado cuando la indicación especifica la combinación de colores del producto.
  • Hay márgenes en los mosaicos de cuadrícula para la tolerancia de recorte.

Revisión humana antes de publicar:

  • ¿El producto parece este producto: forma, proporciones, herrajes y acabado?
  • ¿Hay texto, logotipos o textos de packaging inventados? El texto generado es un punto de fallo habitual y también un riesgo legal en la tienda.
  • ¿La iluminación y el fondo coinciden con el resto del grupo a tamaño de miniatura, no solo a tamaño completo?
  • ¿No hay objetos extraños, componentes adicionales ni reflejos ilógicos en la escena?
  • ¿Las declaraciones publicitarias y las etiquetas reguladas no han sido alteradas por la generación? Esas imágenes deben pasar por el flujo fotográfico.

Registra el revisor y la versión de la indicación de cada recurso aprobado. Cuando llegue una queja de cliente o una solicitud de retirada, ese rastro te permite encontrar de una vez todas las imágenes afectadas y regenerar o retirar el conjunto completo.

Empieza con un tipo de toma, un tamaño y una pequeña muestra de productos, ejecútalos a través de la interfaz de HiAPI y amplía la plantilla solo cuando las salidas pasen la revisión.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API