Genera imágenes de productos de comercio electrónico con grok-imagine/image-to-image a través de la API de hiapi

Los catálogos de productos de comercio electrónico se juegan todo en la consistencia. Un vendedor con 40 SKU no necesita 40 sesiones de fotos distintas: necesita un fondo que se vea bien y una forma rápida de colocar cada producto en él. Este es exactamente el caso de uso real de la edición de imágenes guiada por imágenes de referencia, y es precisamente para lo que destaca grok-imagine/image-to-image en la API de hiapi: le das una escena y una foto de producto, y compone ambas en una imagen limpia y acorde con tu marca, sin máscaras manuales ni un paso separado de recorte.

Esta guía cubre el esquema de solicitud real y probado del modelo (no marketing), el precio que realmente se te cobrará, un script de procesamiento por lotes para aplicar el mismo fondo a todo un catálogo y un truco práctico: controlar la relación de aspecto de salida entre las distintas plataformas de comercio electrónico que exigen recortes diferentes.

Qué hace realmente el modelo

grok-imagine/image-to-image recibe un prompt de texto y una o varias imágenes de referencia y las fusiona en una nueva imagen. Para la fotografía de producto, esto significa:

• Unificación de fondos: coloca cada foto de SKU frente a la misma escena estilizada (una mesa, una estantería, un fondo de estudio), sin necesidad de volver a hacer ninguna foto.
• Composición de escenas: combina el recorte del producto con una imagen de referencia del entorno para que la iluminación y la composición encajen.
• Transferencia de estilo entre imágenes de referencia: lleva la gradación de color o los accesorios de una imagen a otra manteniendo el producto intacto.

Todo esto se hace en una sola llamada de tarea, con facturación por imagen de salida más una pequeña tarifa por cada imagen de referencia que envíes.

El esquema real (verificado contra la API en producción, no en la página de precios)

Consultamos directamente POST /v1/tasks con grok-imagine/image-to-image y el esquema de entrada de este modelo acepta exactamente dos campos:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "string, required",
    "image_urls": ["array of public image URLs, required, max 3"]
  }
}

Eso es todo: no hay resolution, ni aspect_ratio, ni parámetro strength. Cualquier otra cosa en el payload será rechazada por el esquema estricto.

Hay un error que conviene señalar: la página de precios de hiapi afirma actualmente que este modelo admite «hasta 6» imágenes de referencia. Lo probamos directamente enviando 6 y 7 URL de imágenes en la misma solicitud, y ambas fueron rechazadas:

{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 6, want 3"}
{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 7, want 3"}

A fecha de este artículo, el límite que se aplica realmente es de 3 imágenes por llamada, no 6. Si vas a construir un pipeline en torno a este modelo, planifica para 3 y considera obsoleto cualquier texto de marketing que diga lo contrario; antes de publicar automatizaciones que dependan de ese límite, confírmalo siempre con una llamada real a POST /v1/tasks, porque estos límites cambian a medida que la plataforma evoluciona.

Relación de aspecto automática: la proporción de salida sigue a tu primera imagen de referencia

Este modelo no tiene un campo de entrada aspect_ratio, así que ¿de dónde viene la forma de la salida? Hicimos una prueba controlada para averiguarlo: el mismo prompt, las mismas dos imágenes de referencia, cambiando solo el orden de image_urls.

En este render, la foto del producto (la mochila) aparecía en primer lugar en image_urls, seguida de la escena de fondo. La salida fue de 1248×832, una imagen horizontal 3:2 que coincide con la proporción de la propia foto del producto.

El mismo prompt, las mismas dos imágenes, pero esta vez la escena de fondo aparecía en primer lugar. La salida fue de 1024×1024, un recorte cuadrado que coincide con la relación de aspecto de la imagen de referencia de la escena, no con la del producto.

La regla es: la relación de aspecto de salida de grok-imagine/image-to-image se hereda de la URL que aparece primero en image_urls. No lee indicaciones de composición del prompt («foto de producto» o «escena amplia»): es puramente posicional. Una vez que lo sabes, es una palanca realmente útil: para conseguir el recorte que prefiere una plataforma de comercio electrónico concreta, basta con reordenar el array de imágenes de referencia. Para listados de producto cuadrados al estilo Instagram, pon primero una referencia cuadrada; para espacios de banner anchos, pon primero una referencia horizontal.

Precios (verificados contra la lista de precios en producción)

Modelo	Tipo de llamada	Precio
grok-imagine/text-to-image	Texto → Imagen	$0.03 / imagen
grok-imagine/image-to-image	Edición guiada por imágenes de referencia (esta guía)	$0.03 / imagen + $0.003 por cada imagen de referencia
grok-imagine-quality/text-to-image	Texto → Imagen, nivel avanzado	$0.07 / imagen (1K)
grok-imagine-quality/image-to-image	Edición guiada por imágenes de referencia, nivel avanzado	$0.08 / imagen (1K), $0.10 / imagen (2K), + $0.015 por cada imagen de referencia

El nivel básico grok-imagine/image-to-image usado en esta guía no varía según la resolución y tiene una tarifa plana: no pagas el recargo de 2K/4K como en el nivel -quality. Para actualizar un catálogo componiendo decenas de SKU sobre la misma escena, $0.036 por imagen (una foto de producto más una referencia de escena) es la cifra con la que debes presupuestar. Vuelve a consultar /en/pricing antes de ejecutar lotes grandes, porque las tarifas pueden cambiar.

Si necesitas detalles más nítidos en cada imagen y puedes asumir un aumento de precio de unas 3 veces, el nivel grok-imagine-quality es una versión de mayor fidelidad del mismo flujo de trabajo. Para renders de producto puramente de texto a imagen sin ninguna foto de referencia, consulta el tutorial de texto a imagen del nivel básico.

Script de procesamiento por lotes: una escena, todo un catálogo

A continuación tienes un bucle mínimo en Python que toma una escena de fondo reutilizable, la compone con cada foto de producto de una carpeta, envía cada una como una tarea independiente y consulta el estado hasta que termina. Usa el esquema confirmado arriba y coloca la foto del producto en primer lugar, de modo que cada salida herede la relación de aspecto de la propia foto del producto; si quieres la proporción de la escena, intercambia el orden.

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1"
TOKEN = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

SCENE_URL = "https://static.hiapi.ai/blog/grok-imagine-image-to-image-ecommerce/scene-base.jpg"
PROMPT = (
    "Composite the product from the first reference photo naturally into the "
    "second reference's studio scene, matching its lighting and shadow direction. "
    "Keep the product's shape, color, and texture unchanged."
)


def submit(product_url: str) -> str:
    payload = {
        "model": "grok-imagine/image-to-image",
        "input": {
            "prompt": PROMPT,
            "image_urls": [product_url, SCENE_URL],  # product first -> output follows its ratio
        },
    }
    resp = requests.post(f"{API_BASE}/tasks", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, timeout_s: int = 300) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    product_urls = [
        "https://your-storage.example.com/catalog/dripper-raw.jpg",
        "https://your-storage.example.com/catalog/sneaker-raw.jpg",
        "https://your-storage.example.com/catalog/backpack-raw.jpg",
    ]
    for url in product_urls:
        task_id = submit(url)
        output_url = wait_for_result(task_id)
        print(f"{url} -> {output_url}")

Para pipelines de producción, registra un callback.url en la tarea en lugar de consultar en bucle; consulta la guía de modelos de hiapi para ver la estructura completa del payload de callback. Guarda el taskId junto con el SKU de tu producto para que las tareas fallidas se puedan reintentar sin volver a enviar todo el lote.

Ejemplos con fotos de producto reales

Ambas se generaron usando la misma imagen de referencia de escena de fondo, cambiando solo la foto del producto entre llamadas: la iluminación, la mesa y las plantas del fondo se mantienen consistentes en todo el «catálogo», que es justo el objetivo del flujo de trabajo con escenas reutilizables.

Preguntas frecuentes

¿Puedo usar más de 3 imágenes de referencia en una sola llamada? No. El esquema en producción impone maxItems: 3 en image_urls, algo confirmado mediante pruebas directas de la API, diga lo que diga el texto de marketing en otros sitios. Diseña tus prompts para un máximo de 3 imágenes de referencia (normalmente: producto + escena, o producto + escena + referencia de estilo).

¿Cómo controlo la relación de aspecto de la salida? El modelo no tiene parámetro aspect_ratio. La salida hereda la relación de aspecto de la primera imagen de image_urls: reordena tus imágenes de referencia para conseguir la proporción que necesites.

¿Admite generación solo con texto, sin imágenes de referencia? No: image_urls es un campo obligatorio. Para renders de producto solo con texto, usa grok-imagine/text-to-image, a $0.03/imagen.

¿Existe una versión de mayor fidelidad de este modelo? Sí, grok-imagine-quality/image-to-image ejecuta el mismo flujo de trabajo guiado por imágenes de referencia a $0.08/imagen (1K) o $0.10/imagen (2K), más $0.015 por cada imagen de referencia, para ofrecer detalles más nítidos.

Pruébalo ahora

Obtén una clave de API en tu panel de hiapi, prepara una escena de fondo, ejecuta tus primeras tareas con unos pocos SKU antes de decidir renovar todo el catálogo: a $0.036 por imagen, probar este flujo de trabajo con 10 productos cuesta menos de un dólar.