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

La mayoría de los pipelines de imágenes de producto colapsan en cuanto aparece la siguiente necesidad: hay que producir tres formas distintas a partir de la misma foto: una imagen cuadrada para la cuadrícula del catálogo, un recorte vertical para la página de detalles del producto (PDP) en móvil y una imagen panorámica para el banner principal de la página de inicio. Recortar de nuevo una imagen principal rara vez queda bien en todas las proporciones: o se corta el producto o aparecen zonas vacías incómodas. grok-imagine/text-to-image evita este problema: puede generar de forma nativa en la proporción exacta que necesitas, incluidos dos formatos panorámicos creados específicamente para este tipo de trabajo de banner (2:1 y 20:9), con un precio uniforme en la API de hiapi de $0.03 por imagen, independientemente de la resolución.

Esta guía describe la estructura real de la solicitud, las trampas del esquema que encontramos en nuestras pruebas, un script de generación por lotes que ejecuta una lista completa de tomas para un único brief de producto y un cálculo honesto de costes para volúmenes de catálogo.

Posicionamiento de precio

Verificado según la página de precios de hiapi en el momento de redactar este artículo:

Modelo	Precio por imagen	Resolución	Control de relación de aspecto
grok-imagine/text-to-image	$0.03 uniforme	1K o 2K, mismo precio	13 proporciones, incluidas 2:1 y 20:9
grok-imagine-quality/text-to-image	$0.07 (1K) / $0.10 (2K)	Precio escalonado por resolución	Mismo conjunto de proporciones

La versión de calidad sí ofrece una mejora notable en detalles finos —reflejos, textura de tejidos, textos pequeños— y vale la pena pagar el extra para un pequeño número de imágenes principales realmente importantes. Para la mayor parte de las imágenes del catálogo (miniaturas de la cuadrícula, variantes de estilo de vida, otros ángulos), el modelo básico ya está lo bastante cerca, y una diferencia de precio de 2-3 veces no merece la pena en escenarios por lotes.

La solicitud que realmente funciona

Todas las imágenes de esta página provienen del mismo endpoint:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "matte ceramic pour-over coffee dripper on a pale oak table, soft morning window light from the left, small negative space top-right, no text, no logo, product photography",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }
  }'

Esto devuelve un taskId; consulta GET /v1/tasks/{taskId} hasta que status sea success, y luego obtén output[0].url y descarga: esa URL está firmada y caduca, así que debes guardar los bytes de inmediato en lugar de enlazar directamente a ella.

Durante las pruebas, tres detalles del esquema nos hicieron tropezar y conviene conocerlos antes de construir por tu cuenta:

• aspect_ratio es un enum estricto de 13 valores, no formato libre. Enviar cualquier otro valor devuelve un 400 con la lista completa: 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2. Las dos proporciones que necesitan los banners son 2:1 y 20:9: la mayoría de los modelos de imagen en hiapi llegan como máximo a 21:9 o directamente no ofrecen opción ultraancha.
• resolution solo admite minúsculas: usa "2k", no "2K". Enviar la forma en mayúsculas se rechaza directamente, no se convierte en silencio.
• El esquema de entrada es estricto. Campos adicionales o mal escritos (un negative_prompt residual, una clave style copiada de ejemplos de otros modelos) hacen fallar toda la solicitud en lugar de ignorarse.

Escribir prompts para imágenes limpias a escala de catálogo

La mayor palanca para obtener resultados de catálogo coherentes es indicar explícitamente lo que no quieres. Para la imagen principal sobre fondo blanco de arriba, el prompt que funciona es:

"Cafetera de filtro de cerámica mate sobre un fondo blanco puro sin costuras, iluminación de softbox de estudio, centrada, sin degradados de sombra salvo una suave sombra de contacto, sin texto, sin marca de agua, sin accesorios, fotografía de producto de comercio electrónico, enfoque nítido"

Para variantes de estilo de vida destinadas a imágenes secundarias de PDP o banners de correo electrónico, cambia el fondo y las claves de iluminación, pero mantén la misma disciplina de «sin texto / sin marca de agua / sin accesorios salvo los indicados»: es precisamente esto lo que evita que grok-imagine añada objetos desordenados o texto ilegible de etiquetas sobre el propio producto:

"La misma cafetera de filtro de cerámica sobre una encimera de cocina de madera, junto a una taza humeante, luz cálida de mañana, profundidad de campo reducida, fondo de cocina acogedor y doméstico suavemente desenfocado, sin texto, sin logotipo"

Flujo de trabajo para banners ultraanchos

Cuando lo que se necesita es un banner de página de inicio o de categoría en lugar de una miniatura de catálogo, 2:1 y 20:9 son precisamente las dos proporciones que hacen que grok-imagine merezca especialmente la pena. El truco consiste en indicar directamente el espacio negativo en lugar de confiar en que el recorte encaje por casualidad: describe dónde está el producto en el encuadre y qué zonas deben quedar vacías:

"Cafetera de filtro de cerámica mate situada en el tercio derecho del encuadre, luz exterior de hora dorada, amplio espacio negativo vacío en los dos tercios izquierdos de la imagen para superponer el texto del titular, composición panorámica cinematográfica, sin texto, sin logotipo"

{
  "model": "grok-imagine/text-to-image",
  "input": {
    "prompt": "matte ceramic pour-over coffee dripper positioned in the right third of frame, golden-hour outdoor light, generous empty negative space across the left two-thirds of the image for headline text overlay, cinematic wide composition, no text, no logo",
    "aspect_ratio": "20:9",
    "resolution": "2k"
  }
}

Si tu CMS necesita dimensiones exactas en píxeles en lugar de proporciones, genera con la proporción compatible más cercana y luego recorta sin pérdida a partir de esa imagen; para los cálculos concretos de relleno, consulta nuestras notas sobre dimensiones exactas mediante API.

Generar por lotes una lista completa de tomas

Un único brief de producto suele necesitar más de una imagen. El siguiente script reproduce el que se usó realmente para generar las cuatro imágenes de esta página: envía una tarea por imagen, consulta hasta que termine y guarda en disco:

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"}

SHOTS = [
    {
        "name": "hero",
        "prompt": "matte ceramic pour-over coffee dripper on a pure white seamless "
                  "background, studio softbox lighting, centered, e-commerce product "
                  "photography, no text, no watermark",
        "aspect_ratio": "1:1",
    },
    {
        "name": "lifestyle",
        "prompt": "same ceramic pour-over dripper on a wooden kitchen counter next to "
                  "a steaming mug, warm morning light, shallow depth of field, no text",
        "aspect_ratio": "4:3",
    },
    {
        "name": "banner",
        "prompt": "ceramic pour-over dripper in the right third of frame, soft studio "
                  "light, empty negative space across the left two-thirds for headline "
                  "text, no text, no logo",
        "aspect_ratio": "2:1",
    },
]


def create_task(shot):
    payload = {
        "model": "grok-imagine/text-to-image",
        "input": {"prompt": shot["prompt"], "aspect_ratio": shot["aspect_ratio"], "resolution": "2k"},
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


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


for shot in SHOTS:
    task_id = create_task(shot)
    url = wait_for_result(task_id)
    image_bytes = requests.get(url, timeout=120).content
    with open(f"{shot['name']}.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{shot['name']}: saved {len(image_bytes)} bytes")

Si vas a ejecutar un lote completo de varios SKU, envía primero las tres tareas y luego consúltalas en paralelo (basta con un pequeño asyncio o un grupo de hilos): cada tarea suele terminar en menos de un minuto, y ejecutarlas en serie solo añade tiempo de espera inactivo sin motivo.

Coste de una ejecución real de catálogo

Con un precio uniforme de $0.03 por imagen, el conjunto de tres imágenes anterior (principal + estilo de vida + banner) cuesta $0.09 por SKU. Al escalar:

• 50 SKU × 3 imágenes = 150 imágenes → $4.50
• 500 SKU × 3 imágenes = 1,500 imágenes → $45
• Añadir la mejora a grok-imagine-quality solo para las imágenes principales en 2K ($0.10 en lugar de $0.03) hace que el total para 500 SKU pase a $80, lo que sigue siendo una fracción de lo que cuesta una sola sesión tradicional de fotografía de producto.

grok-imagine frente al resto de la línea de productos

Si una imagen necesita movimiento —por ejemplo, un breve clip de producto de 6 segundos para un anuncio en redes sociales en lugar de un banner estático—, la misma familia lo cubre mediante grok-imagine-image-to-video, que usa una de estas imágenes estáticas como fotograma inicial; describimos ese flujo de trabajo por separado en la guía de vídeo corto. Para equipos que comparan con un pipeline de catálogo basado en Nano-Banana, nuestra guía de comercio electrónico con Nano-Banana es la referencia comparativa más cercana: la misma estructura de API de tareas, distintas ventajas del modelo.

Preguntas frecuentes

¿grok-imagine/text-to-image admite imágenes de referencia (i2i), no solo prompts de texto? Sí, pero esa es una variante de modelo distinta (grok-imagine/image-to-image), con su propio esquema de entrada. Esta guía cubre la ruta de texto a imagen pura.

¿Por qué mi solicitud devuelve un 400 y un error de «additional properties»? El esquema de entrada es estricto. Revisa con cuidado que solo envías prompt, aspect_ratio y, opcionalmente, resolution: no arrastres campos adicionales copiados de ejemplos de otros modelos.

¿Puedo obtener una proporción exacta como 1200×630 en lugar de elegir del enum? Genera con la proporción compatible más cercana (16:9 se acerca a muchas formas de banner web) y luego recorta sin pérdida en posproducción; para el método concreto de relleno, consulta la guía de dimensiones exactas enlazada arriba.

¿Merece la pena esperar la resolución 2K frente a 1K? Este modelo tiene el mismo precio en ambas resoluciones, así que usa 2K por defecto salvo que tengas un presupuesto de latencia estricto: obtienes más detalle gratis.

Pruébalo tú mismo

Todo el acceso a la API que aparece aquí está disponible con una clave estándar de hiapi: consulta la documentación para la autenticación y la referencia completa de consulta de tareas, y revisa la página de precios para conocer las tarifas actuales de toda la línea de modelos antes de comprometerte a ejecuciones por lotes.