flux-2/image-to-image para imágenes de productos de comercio electrónico: guía de la API de hiapi

Si ya tienes fotos de productos decentes —aunque sean fotos desordenadas con un fondo incorrecto o un recorte inadecuado—, flux-2/image-to-image puede convertirlas en imágenes de comercio electrónico listas para publicar sin necesidad de volver a fotografiarlas. Es un modelo de edición, no un modelo de texto a imagen: le das de 1 a 8 imágenes de referencia más una instrucción y devuelve una nueva imagen que cambia todo lo que la rodea —el fondo, la iluminación, la composición e incluso la escena en la que se encuentra el producto— preservando con precisión la forma, el color, el material y las proporciones del producto.

Ejecutamos de principio a fin dos tareas habituales de comercio electrónico a través del endpoint /v1/tasks de hiapi —la sustitución del fondo de estudio y la composición en escenas de estilo de vida— y, antes de escribir esto, verificamos el esquema de entrada, el comportamiento de la relación de aspecto y el precio real por imagen contra la página de precios de hiapi.

• flux-2/image-to-image acepta hasta 8 imágenes de referencia por llamada, por lo que la sustitución de fondo (1 imagen) y la composición de escenas (2 o más imágenes) usan exactamente el mismo endpoint.
• aspect_ratio: "auto" sí sigue la relación de aspecto de la propia imagen de entrada: una foto vertical 9:16 de unas zapatillas deportivas se mantiene en 9:16 a menos que la sobrescribas. Un valor explícito como "1:1" fuerza esa forma independientemente de lo que introduzcas.
• El precio se estructura por tramos de resolución: $0.035/imagen en 1K y $0.05/imagen en 2K: un precio fijo, sin facturación por megapíxel.
• Es una edición real, no un redibujado: el logotipo, las costuras y la textura del material del propio producto se conservan tras cambiar el fondo o la escena.
• Un script de procesamiento por lotes (véase más abajo) basta para recorrer todo un catálogo de productos con la misma instrucción de limpieza de fondo.

Qué hace realmente flux-2/image-to-image

En esencia, es un único modelo sobre la interfaz unificada de tareas de hiapi: no eliges entre una herramienta de «eliminación de fondo» y una herramienta de «composición», sino que escribes una instrucción y proporcionas las imágenes de referencia correctas para esa tarea:

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Remove the background and place the product on a seamless white studio background with a soft contact shadow. Keep the product'"'"'s shape, color and proportions unchanged.",
      "image_urls": ["https://your-cdn.example.com/raw-product-photo.jpg"],
      "aspect_ratio": "auto",
      "resolution": "1K"
    }
  }'

Los campos obligatorios son prompt (cadena), image_urls (array, máximo 8), aspect_ratio (auto, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2 o 2:3) y resolution (1K o 2K). La respuesta devuelve un taskId: consulta periódicamente GET /v1/tasks/{taskId} hasta que status sea success y luego descarga la imagen inmediatamente desde output[0].url (ese enlace caduca, así que no lo trates como almacenamiento permanente).

La sustitución de fondo solo necesita una imagen de referencia. Para componer un producto en una escena de estilo de vida, pasa dos: primero la imagen del producto y después la escena de destino, y describe en la instrucción qué objeto va en qué lugar.

Qué hace realmente la relación de aspecto «auto»

Esta es la parte que conviene probar antes de construir un flujo de trabajo en torno a ella, porque es fácil dar por sentado que el modelo siempre devuelve un cuadrado fijo o alguna forma predeterminada fija. No es así.

Esta es una foto vertical de unas zapatillas deportivas ejecutada con aspect_ratio: "auto": la salida es de 720×1280, coincidiendo exactamente con el 9:16 de la imagen de referencia de entrada, sin recortes ni márgenes que la conviertan en otra forma. auto significa «seguir la entrada», no «elegir un valor predeterminado».

La misma imagen de origen, la misma instrucción: el único cambio es establecer explícitamente aspect_ratio: "1:1". La salida es un cuadrado exacto de 1024×1024; el modelo recompone para adaptarse en lugar de limitarse a recortar. Si tu catálogo de productos necesita una cuadrícula cuadrada uniforme para las páginas de listado, fuerza esa proporción; si prefieres que cada imagen conserve su composición nativa, mantén auto.

Dos ejemplos de composición de escenas

La sustitución de fondo es el caso sencillo. La técnica más útil para el contenido de comercio electrónico es componer una imagen limpia del producto dentro de una escena de estilo de vida: útil para la imagen principal, publicaciones en redes sociales o fotos secundarias de «cómo combinarlo», sin necesidad de una sesión fotográfica real.

Aquí se introdujeron dos imágenes de referencia: una foto limpia del producto de los auriculares y una escena independiente de una mesa de roble iluminada por el sol. La instrucción especificaba qué objeto colocar y dónde («apoyado de forma natural junto a la planta») y pedía al modelo que igualara la dirección de la luz existente en la escena y proyectara una sombra creíble; precisamente ese detalle es lo que hace que la composición parezca real y no pegada.

La misma escena de destino, un producto distinto y también aspect_ratio: "auto" (que hereda la composición cuadrada de la imagen de referencia de la escena). La forma y el material cerámico del goteador se conservan tal cual a partir de su propia foto de referencia: solo ha cambiado el entorno.

Procesamiento por lotes de un catálogo de productos

A $0.035/imagen (resolución 1K), más barato que volver a montar y fotografiar un solo producto, es fácil justificar recorrer todo un catálogo de productos con flux-2/image-to-image. Si primero quieres probar la instrucción a bajo coste, merece la pena echar un vistazo al nivel más ligero flux-2-klein-4b/image-to-image antes de usar el modelo completo a escala; los precios actuales de ambos están en la página de precios de hiapi.

Una vez ajustada la instrucción para un producto, ejecutarla en todo el catálogo no es más que un bucle sobre la misma petición. Este ejemplo recorre un conjunto de fotos de productos sin procesar, ejecuta la misma instrucción de limpieza de fondo en cada una e imprime la URL de alojamiento del resultado:

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]

HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

BACKGROUND_PROMPT = (
    "Remove the existing background and place the product on a seamless pure white "
    "studio background with a soft, realistic contact shadow and even diffused catalog "
    "lighting. Keep the product's exact shape, color, material and proportions unchanged."
)


def edit_product_image(prompt, image_urls, aspect_ratio="auto", resolution="1K"):
    payload = {
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,
        },
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    while True:
        time.sleep(3)
        status = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30).json()
        state = status["data"]["status"]
        if state == "success":
            return status["data"]["output"][0]["url"]
        if state == "fail":
            raise RuntimeError(f"task {task_id} failed: {status}")


CATALOG = [
    {"sku": "SNK-001", "image_url": "https://cdn.example.com/raw/snk-001.jpg"},
    {"sku": "HDP-014", "image_url": "https://cdn.example.com/raw/hdp-014.jpg"},
    {"sku": "DRP-022", "image_url": "https://cdn.example.com/raw/drp-022.jpg"},
]

for item in CATALOG:
    out_url = edit_product_image(BACKGROUND_PROMPT, [item["image_url"]])
    print(item["sku"], "->", out_url)

Cada output[0].url es un enlace con caducidad: descárgalo y vuelve a alojarlo dentro del bucle (en tu propio bucket, tu CDN o cualquier servicio que respalde el backend de tu tienda) en lugar de guardar el enlace original. Para ver el recorrido completo del bucle de creación de tarea/consulta/descarga (con gestión de errores), consulta cómo usar flux-2/image-to-image través de la API de hiapi.

Preguntas frecuentes

¿flux-2/image-to-image cambia el producto en sí o solo el fondo? Con una instrucción adecuada, debería cambiar solo lo que le indiques —el fondo, la escena, la iluminación— manteniendo la forma, el color y el material del producto tal como aparecen en la imagen de referencia. No todos los intentos salen perfectos; antes de publicar, compara el resultado con la imagen de origen, especialmente en el caso de logotipos o textos pequeños del envase.

¿Cuántas imágenes de referencia puedo usar como máximo en una sola llamada? Hasta 8. La sustitución de fondo solo necesita 1. La composición de escenas normalmente requiere 2 (producto + escena de destino); más imágenes de referencia son útiles cuando quieres que el modelo haga coincidir un personaje, un accesorio o un elemento de marca existentes y concretos en un conjunto de fotos.

¿Debo usar resolución 1K o 2K? 1K ($0.035/imagen) basta para la mayoría de los catálogos de productos y listados web; las composiciones de los auriculares y del goteador anteriores se generaron en 1K. Para banners principales o cualquier contenido que vaya a recortarse y ampliarse después, elige 2K ($0.05/imagen).

¿Cuál es la diferencia entre flux-2/image-to-image y el nivel Klein? Klein (9b y 4b) cambia parte de la fidelidad de edición por un precio más bajo: resulta útil para probar instrucciones a bajo coste antes de recorrer todo el catálogo con el modelo completo. Los precios actuales están en la tabla de precios de arriba.

¿Puedo forzar un tamaño de salida concreto sin dejar que lo decida el modelo? Sí: establece aspect_ratio en un valor explícito (1:1, 4:3, 16:9, etc.) en lugar de auto. El modelo recompone para adaptarse a esa forma en lugar de limitarse a recortar la salida de ajuste automático.

Puntos clave

• flux-2/image-to-image edita fotos de productos existentes en lugar de generarlas desde cero: entra una imagen de referencia, sale una imagen editada y se conserva la identidad del producto.
• aspect_ratio: "auto" sigue la forma de la propia imagen de entrada; cuando necesites una proporción de salida uniforme para toda la cuadrícula del catálogo, establécelo explícitamente.
• La resolución 1K ($0.035/imagen) cubre la mayoría de los casos de uso de comercio electrónico; 2K ($0.05/imagen) para tamaños de imagen principal o salidas muy recortadas.
• El mismo endpoint gestiona tanto la sustitución de fondo con una sola imagen como la composición de escenas con varias imágenes: la única diferencia es cuántas image_urls pasas.
• El procesamiento por lotes es solo un bucle normal envolviendo el ciclo de creación de tarea/consulta/descarga; no se necesita un endpoint por lotes independiente.

Si ya estás listo para aplicarlo a tu propio catálogo de productos, la página del modelo flux-2/image-to-image ofrece el esquema en vivo y una petición de inicio rápido, y las recetas de instrucciones para flux-2/image-to-image recopilan más patrones de instrucciones probados, además de la sustitución de fondo y la composición de escenas.