Blog

Guía de uso

Generación de imágenes de productos de comercio electrónico con flux-3 a través de la API de HiAPI

Plantillas de prompts, control de fondo e iluminación, y una solicitud de generación de fotos de producto que funciona

Nov 12, 2026
Arte de portada al estilo de grabado a rayas: líneas paralelas de cobre sobre azul medianoche forman marcos de producto abstractos y una tubería escalonada.
En esta página

Por qué flux-3 es adecuado para fotos de productos de comercio electrónico

Los pipelines de catálogo de productos suelen fallar por una razón aburrida: la consistencia. Una página de producto no es una sola imagen principal, sino docenas de imágenes que abarcan múltiples SKU, múltiples ángulos y actualizaciones de temporada, y todas deben parecer tomadas la misma tarde en el mismo estudio fotográfico. Encargar cada una a un fotógrafo es lento y caro; encargar cada una a un generador de imágenes cualquiera suele dar como resultado un conjunto de imágenes que, individualmente, parecen razonables, pero que juntas resultan discordantes.

Ahí es donde flux-3 resulta útil. Es un modelo de generación de imágenes disponible a través de la API de HiAPI, lo que significa que tu pipeline de productos puede tratar la creación de imágenes como una llamada HTTP más: envías un prompt junto con los parámetros del producto, recibes una imagen, la almacenas y pasas al siguiente SKU. Sin SDK exclusivo del proveedor, sin abrir una cuenta separada para cada modelo y sin escribir código de integración para cada proveedor.

Lo que es especialmente importante para el comercio electrónico es que la respuesta de flux-3 a la estructura del prompt es predecible. Una foto de producto es una escena muy restringida: un sujeto, centrado o deliberadamente compuesto, un fondo limpio y una iluminación de estilo de estudio. Esas restricciones son exactamente lo que puedes expresar con palabras, y una vez que se convierten en texto, se convierten en variables de plantilla en lugar de decisiones creativas. Esa es la diferencia entre «pedirle una imagen al modelo» y tener un paso de generación dentro de una tarea de catálogo.

El flujo de trabajo práctico de esta guía es: definir una estructura de prompt reutilizable, ajustar la redacción del fondo y la iluminación hasta que la línea base se vea correcta, y luego sustituir el bloque del sujeto por cada producto. Todo lo demás permanece igual, y eso es precisamente lo que te da consistencia visual en una línea de productos.

Qué necesitas antes de empezar

  • Una clave de API de HiAPI y el identificador de modelo actual de flux-3 obtenido de la lista de modelos de la plataforma.
  • Datos del producto en forma estructurada: nombre, material, color, forma y cualquier detalle destacado que quieras que el modelo represente.
  • Un lugar donde guardar el prompt de línea base y las salidas generadas, para que puedas comparar versiones más adelante.
Un producto, renderizado de forma consistente sobre nueve fondos controlados: esa es la promesa de flux-3 para la consistencia del catálogo.

La composición de un prompt de foto de producto con flux-3

Un prompt que solo funciona para un producto no sirve de mucho. Un prompt que puedes rellenar sí sirve. La forma de lograrlo es descomponer la descripción en bloques fijos, cada uno correspondiente a una variable en tu código.

Los cinco bloques

  • Sujeto. Qué es el objeto, descrito con sustantivos concretos. «Una taza de café de cerámica mate» supera a «una taza bonita». Añade indicaciones de escala cuando importen («alta», «de boca ancha»).
  • Material y superficie. Acabado y textura: aluminio cepillado, cerámica vidriada, algodón tejido, vidrio esmerilado. De aquí provienen los reflejos del modelo, así que sé explícito.
  • Fondo. La superficie y la mesa sobre las que se apoya el producto: papel sin costuras, pizarra, degradado suave, fondo blanco infinito. Mantén este bloque deliberadamente breve y aburrido: es andamiaje, no un espacio creativo.
  • Iluminación. Dirección, calidad y contraste: luz principal suave desde la izquierda, fuente difusa amplia, relleno suave, sombra sutil bajo el objeto. Este bloque determina la mayor parte de la sensación de «estudio» y es el que más ajustarás.
  • Encuadre de cámara. Cómo compone la lente: toma centrada del producto, a la altura de los ojos, ángulo de tres cuartos, recorte ajustado, amplio espacio negativo arriba.

Convertir los bloques en una plantilla

Estos bloques se ensamblan en tiempo de ejecución en una sola cadena, sustituyendo solo el sujeto (y ocasionalmente el material) por cada SKU:

product photo of {subject}, {material}, {background}, {lighting}, {framing}

Un ejemplo rellenado:

product photo of a matte ceramic coffee mug, glazed stoneware with visible clay texture,
on a seamless light gray paper backdrop, soft diffused key light from the upper left
with gentle fill and a soft contact shadow, centered eye-level shot with negative space above

Dos reglas mantienen la plantilla estable. Primera: mantén fijo el orden de los bloques; incluso con el mismo texto, reordenar los bloques cambia el énfasis. Segunda: al pasar de un SKU a otro, mantén los bloques fijos como exactamente la misma cadena, en lugar de reescribirlos cada vez; la deriva sutil en la redacción es la fuente más común de fondos e iluminación inconsistentes en un catálogo.

Dónde no debe aparecer la creatividad

Evita el lenguaje editorial en los bloques fijos: nada de adjetivos emotivos, nada de adornos de estilismo, nada de referencias a escenas. Deja cualquier variación para campañas de marketing deliberadas y mantén limpia la plantilla del catálogo. Una plantilla que se lee como una especificación técnica produce imágenes que parecen una especificación técnica, que es exactamente lo que necesita un listado de productos.

Cada bloque del prompt (sujeto, material, fondo, iluminación, encuadre) es una pieza intercambiable que puedes reordenar y reutilizar.

Controlar el fondo y la iluminación

El fondo y la iluminación son los dos bloques que determinan si un conjunto de imágenes se lee como un catálogo coherente. Ambos responden bien a una redacción concreta y física.

Fondo: busca lo aburrido

Describe el fondo como un montaje físico, no como una estética. «Fondo de papel gris claro sin costuras» y «fondo blanco infinito» son fiables porque describen una configuración de estudio conocida. Palabras como «minimalista» o «estético» son vagas y suelen dejar que se filtren elementos de la escena.

Palancas útiles:

  • Tipo de superficie: papel sin costuras, vinilo mate, pizarra natural, madera clara.
  • Color y tono: gris claro, blanco roto, arena cálida; mantén la luminosidad entre media y clara para que los bordes del producto sigan siendo legibles.
  • Continuidad: «sin costuras» o «infinito» le indica al modelo que quieres que el fondo y el suelo se fundan, eliminando la línea del horizonte que luego resulta difícil de limpiar.
  • Vacío: si los primeros intentos introducen objetos sueltos, vale la pena escribir explícitamente «fondo vacío, sin accesorios».

Si necesitas un PNG con fondo transparente para el mercado, genera primero sobre un fondo limpio de color sólido y luego recorta en posproducción. Pedirle al modelo de imágenes una verdadera canal alfa no es un camino fiable.

Iluminación: primero la dirección, después la calidad

La redacción de la iluminación se divide claramente en dos decisiones. La dirección determina dónde caen los reflejos y las sombras; la calidad determina cuán suaves son los bordes de esos reflejos.

  • Dirección: «luz principal desde arriba a la izquierda», «luz principal suave desde el frente», «luz desde la derecha con relleno suave a la izquierda». Elige una y mantenla en toda la línea de productos.
  • Calidad: «fuente difusa amplia», «sombras suaves», «iluminación uniforme». La luz suave y difusa es un valor predeterminado seguro para fotos de producto porque no sobreexpone los materiales brillantes.
  • Sombra de contacto: «sombra de contacto suave bajo el producto» hace que el objeto se asiente; sin ella, el producto parece flotar.
  • Contraste: «bajo contraste, brillante y uniforme» funciona bien para marketplaces de fondo blanco; un poco más de contraste direccional funciona bien para recortes de estilo de vida premium.

Mantener la consistencia en la línea de productos

La consistencia es menos un problema de prompts que un problema de gestión de versiones. Guarda los bloques de fondo e iluminación como presets con nombre (por ejemplo, un preset «estudio blanco» y un preset «pizarra») y haz referencia a ellos por nombre en cada tarea de generación, en lugar de pegar el texto por SKU. Cuando ajustas un preset, lo ajustas una vez, y el siguiente lote hereda el cambio de forma intencionada en lugar de desviarse.

Cuando un resultado sale mal, cambia un solo bloque a la vez y vuelve a generar el mismo producto. Cambiar el fondo y la iluminación a la vez te impide saber qué fragmento de redacción fue el responsable.

Flechas de dirección de la luz y muestras de color de fondo: cómo la redacción del prompt se traduce en una apariencia coherente de la línea de productos.

Una solicitud HiAPI de flux-3 que funciona

El paso de generación es una llamada a la API. La ruta exacta del endpoint, los identificadores de modelo y los campos de la solicitud están documentados en la plataforma y deben obtenerse de allí, ya que pueden evolucionar; la forma que aparece a continuación es el patrón para integrar en tu script.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]

presets = {
    "white_studio": {
        "background": "on a pure white infinity sweep, no props, empty backdrop",
        "lighting": "soft diffused key light from the upper left, even fill, "
                    "soft contact shadow beneath the product, low contrast",
        "framing": "centered eye-level product shot, generous negative space",
    }
}

def build_prompt(product, preset_name="white_studio"):
    p = presets[preset_name]
    return (
        f"product photo of {product['subject']}, {product['material']}, "
        f"{p['background']}, {p['lighting']}, {p['framing']}"
    )

def generate(product, preset_name="white_studio"):
    payload = {
        "model": "flux-3",           # confirm the current identifier in the model list
        "prompt": build_prompt(product, preset_name),
    }
    response = requests.post(
        "https://api.hiapi.ai/v1/images/generations",  # see docs for exact path
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

product = {
    "subject": "a matte ceramic coffee mug",
    "material": "glazed stoneware with visible clay texture",
}

result = generate(product)
print(result)

Integrarlo en el procesamiento por lotes

Algunos hábitos permiten que esto se ejecute de forma segura en todo un catálogo, en lugar de en un solo producto:

  • Resuelve cada valor desde variables de entorno. Mantén las claves fuera del código fuente y de los registros.
  • Trata la respuesta como no confiable. Lee la referencia o carga útil de la imagen devuelta a partir de los campos documentados y luego descárgala y guárdala en tu propio bucket. No dependas de que ninguna URL temporal sobreviva más que la tarea.
  • Registra la cadena exacta del prompt junto con cada salida. Guárdala con los metadatos de la imagen. Cuando más adelante alguien pregunte por qué la imagen del SKU 1234 se ve diferente, la respuesta debería estar en tu base de datos, no en la memoria.
  • Usa reintentos con retroceso exponencial para fallos transitorios y limita la concurrencia para que los lotes grandes no activen los límites de velocidad.
  • Mantén las solicitudes idempotentes por SKU y versión del prompt, de modo que una nueva ejecución sobrescriba la misma ranura de salida en lugar de esparcir duplicados.

Iterar de la plantilla a un pipeline de producción

El primer prompt validado es una línea base, no un activo terminado. Llevarlo a producción significa convertirlo en algo que tu pipeline pueda reproducir y auditar.

Paso 1: fijar la línea base con una pequeña muestra

Genera de cinco a diez productos de distintas categorías de material: uno brillante, uno mate, uno textil, uno metálico, uno transparente. Estos pondrán a prueba el bloque de iluminación de distintas maneras. Si la plantilla se sostiene con esta muestra, tienes una línea base; si los productos brillantes se sobreexponen o los textiles se ven planos, ajusta ese bloque ahora, no después de que el catálogo se haya ejecutado.

Paso 2: nombrar y versionar los presets

Dale al preset un identificador de versión explícito y trata los cambios como una nueva versión, no como una edición. Un esquema sencillo de white_studio_v1 → white_studio_v2 te permite volver a generar un lote con el preset antiguo y comparar, y también te permite revertir si una «pequeña mejora» resulta ser una regresión en la mitad de tus SKU.

Paso 3: almacenar los prompts donde el pipeline pueda leerlos

Mantén dos capas: la definición del preset compartido (fondo, iluminación, encuadre, versión) en un solo lugar, y los campos de sujeto y material de cada SKU en tu base de datos de productos. Luego, el código de generación combina ambos. Esto significa que un cambio de preset se propaga a cada tarea futura, mientras que los datos del sujeto siguen siendo propiedad del equipo de catálogo.

Paso 4: comparar las salidas de forma sistemática

La revisión lado a lado no escala más allá de unas pocas docenas de SKU. Señales más económicas:

  • Revisión de hoja de contactos: monta un lote en una sola imagen de cuadrícula y escanea en busca de anomalías. Los fondos que se desvían y los encuadres desplazados saltan de inmediato a tamaño de miniatura.
  • Muestreo de bordes contra el fondo: muestrea el color de los píxeles cerca del borde de la imagen y marca los resultados cuyos colores de esquina difieran del tono esperado del preset. Esto detecta el fallo más común, un fondo que cambia de color sutilmente, sin necesidad de ojos humanos.
  • Comprobación de la posición en el encuadre: si el producto debe estar centrado con espacio negativo arriba, mide dónde queda la masa del sujeto en cada imagen y marca las anomalías.

Todo lo marcado entra en una cola de revisión; todo lo demás se publica automáticamente.

Paso 5: regenerar de forma deliberada

Una vez que la línea base es estable, un nuevo SKU es un problema de datos, no de prompt: añade los campos de sujeto y material, pon la tarea en cola y deja que la automatización se encargue. Reserva las ejecuciones de regeneración para cambios intencionados (fondos de temporada, nuevas variantes de iluminación) y, cuando lo hagas, incrementa la versión del preset.

Errores comunes y cómo evitarlos

La mayoría de los fallos al generar imágenes de producto son los mismos pocos problemas, cada uno con una solución del lado del prompt o del lado del pipeline.

Deriva del fondo entre lotes

La queja más común: las imágenes son consistentes individualmente, pero difieren entre SKU. Casi siempre es por deriva en la redacción: alguien reescribió el bloque de fondo, o la plantilla insertó atributos del producto en él. Solución: trata el fondo y la iluminación como cadenas fijas provenientes de una única fuente de presets y verifica en el código que el prompt ensamblado contenga literalmente el texto del preset.

Accesorios y elementos de escena no deseados

A los modelos les encanta añadir fondo: una pequeña rama con hojas, un trozo de tela doblada, una sombra que parece el borde de una mesa. Declara explícitamente el vacío («fondo vacío, sin accesorios») y mantén el lenguaje de escena lo más físico y limitado al estudio posible. Si persiste, simplifica la descripción del sujeto: los adjetivos decorativos en el bloque del sujeto suelen atraer decoración correspondiente en la escena.

Productos flotantes

Sin sombra de contacto, el objeto parece pegado al fondo. Incluye «sombra de contacto suave bajo el producto» en el bloque de iluminación y especifica que el producto está apoyado sobre una superficie, no suspendido.

Encuadre inconsistente

Mezclar recortes arruina una página de categoría. Fija el bloque de encuadre en una sola frase y no dejes que varíe; si necesitas varias relaciones de aspecto, genera la misma composición y recorta en posproducción en lugar de crear un prompt para cada proporción.

Prompts demasiado especificados

Los prompts largos que describen la historia, la marca y el relato del producto suelen producir imágenes editoriales en lugar de imágenes de catálogo. La plantilla debería leerse como una lista de tomas. Cuando el resultado no se siente bien, la solución suele ser quitar palabras, no añadirlas.

Tratar un fallo de generación como un defecto del código

Un solo resultado malo no es señal de reescribir el pipeline. Reprodúcelo con la cadena exacta del prompt almacenada, cambia un bloque, vuelve a generar y luego saca conclusiones. Registrar el prompt junto con cada salida es precisamente lo que hace esto posible, y es el hábito más barato de adoptar desde el principio.

Empieza con un preset, un lote de muestra y el prompt almacenado por imagen; amplía una vez que la línea base se sostenga en todos los tipos de material.

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