Genera videos cortos a partir de imágenes fijas de producto: grok-imagine/image-to-video en la API de hiapi

El contenido de video corto para productos tiene un problema de suministro. Un clip listo para publicar solía implicar una producción: tiempo de estudio, diseño de movimiento, un editor. Pero si ya gestionas un catálogo de comercio electrónico, tienes la materia prima a mano: miles de imágenes fijas de producto.grok-imagine/image-to-video (el endpoint de imagen a video Grok Imagine de xAI) convierte esas imágenes fijas en clips cinematográficos de 6 a 30 segundos con una sola llamada de API asíncrona, y su condicionamiento por imagen de referencia hace que tu producto siga pareciendo tu producto.

Esta guía es el flujo de trabajo de extremo a extremo en la API de hiapi: anima una sola imagen fija de catálogo, bloquea la consistencia del sujeto con varias imágenes de referencia, elige las franjas de duración y resolución según la economía del feed, y procesa por lotes todo un catálogo en una cola de clips verticales. Cada clip incrustado a continuación es una salida real, sin editar y de primera generación procedente de la API en producción, generada para este artículo a partir de imágenes fijas de nuestra biblioteca de recursos, con el prompt y la configuración exactos al lado.

Modelo, límites y precios

grok-imagine/image-to-video se ejecuta sobre la interfaz de tareas asíncronas de hiapi (POST /v1/tasks). El esquema de entrada que verificamos empíricamente para este artículo:

• image_urls (array, obligatorio) — una o más URL de imagen de referencia accesibles públicamente. Las URL privadas o no recuperables fallan durante la normalización, no con un error de esquema, así que aloja primero las imágenes de referencia en una ubicación pública.
• prompt (cadena, opcional) — indicaciones de movimiento, cámara y ambiente. Sin prompt, el modelo improvisa; para contenido de producto siempre deberías proporcionarlo.
• duration (entero, 6–30 segundos)
• resolution (480p o 720p)
• aspect_ratio (1:1, 2:3, 3:2, 16:9, 9:16)

No hay campos motion_mode, seed ni prompt negativo: los campos desconocidos se rechazan con un 400. Todo el control del movimiento depende de la redacción del prompt.

Un comportamiento que encontramos al generar los clips de este artículo: cuando aspect_ratio no coincide con la relación de aspecto de la propia imagen de referencia, la imagen de referencia suele imponerse. En las tres ejecuciones siguientes solicitamos 9:16; dos imágenes fijas de origen cuadradas devolvieron clips cuadrados (960×960 y 544×544), mientras que la ejecución cuya primera referencia era horizontal entregó un verdadero vertical de 720×1280. Si tu feed exige garantizar 9:16, recorta la imagen fija de referencia a 9:16 antes de enviarla, en lugar de confiar en ese parámetro.

El precio se factura por segundos de salida, según la página de precios de hiapi en el momento de redacción:

Franja	Precio por segundo	Clip de 6 s	Clip de 15 s	Clip de 30 s
480p	$0.0114	$0.068	$0.171	$0.342
720p	$0.0214	$0.128	$0.321	$0.642

Este precio define todo el flujo de trabajo: un clip principal de 6 segundos a 720p cuesta unos 13 céntimos, y un borrador a 480p aproximadamente la mitad. Puedes permitirte iterar sin problema.

Enviar → sondear → descargar

El ciclo de vida de la tarea es enviar, sondear, descargar. Envía con curl:

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/image-to-video",
    "input": {
      "prompt": "Órbita cinematográfica lenta alrededor del bolso, la iluminación de estudio destella en las cremalleras de latón, el fondo permanece limpio, producto sin cambios.",
      "image_urls": ["https://your-cdn.example.com/products/weekender.jpg"],
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "9:16"
    }
  }'

Recibes de inmediato un ID de tarea:

{"code": 200, "data": {"taskId": "tk-hiapi-01KX2H8WMWQG99A2F97BREDPS6"}, "message": "success"}

Luego sondea GET /v1/tasks/{taskId} hasta que status sea success, y descarga output[0].url. A continuación un script auxiliar completo de Python, el patrón exacto que se usó para generar cada clip de este artículo:

import json, subprocess, time, os

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

def submit(input_fields: dict) -> str:
    payload = {"model": "grok-imagine/image-to-video", "input": input_fields}
    out = subprocess.run(
        ["curl", "-s", "-X", "POST", API,
         "-H", f"Authorization: Bearer {TOKEN}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(payload)],
        capture_output=True, text=True, timeout=70).stdout
    data = json.loads(out)
    if not (data.get("data") or {}).get("taskId"):
        raise RuntimeError(f"submit failed: {out[:300]}")
    return data["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 1200) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        out = subprocess.run(
            ["curl", "-s", f"{API}/{task_id}",
             "-H", f"Authorization: Bearer {TOKEN}"],
            capture_output=True, text=True, timeout=40).stdout
        task = json.loads(out)["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)

task_id = submit({
    "prompt": "...",
    "image_urls": ["https://your-cdn.example.com/products/weekender.jpg"],
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "9:16",
})
task = wait(task_id)
video_url = task["output"][0]["url"]
subprocess.run(["curl", "-s", "-o", "clip.mp4", video_url], timeout=180)

Dos detalles operativos a tener en cuenta en producción:

1. output[0].url es un enlace firmado con caducidad (con un tiempo de expiración). En cuanto la tarea tenga éxito, descarga los bytes de inmediato y migra el archivo a tu propio almacenamiento; nunca persistas la URL original de la tarea.
2. La facturación se produce cuando se acepta la tarea, así que valida antes de enviar lotes grandes. Un truco útil: envía un valor fuera de rango, como "duration": 99; recibirás el error de validación de esquema completo sin crear una tarea facturable.

Una imagen fija → un clip principal

La operación más común: coge una imagen de producto del catálogo y dale un movimiento de cámara continuo. La fotografía de producto es intrínsecamente estática, así que la responsabilidad del prompt es añadir un solo movimiento creíble y fijar explícitamente todo lo demás:

Órbita cinematográfica lenta alrededor del bolso weekender de lona naranja quemado, la cámara
circula suavemente de frente a una vista de tres cuartos, la iluminación de estudio destella
en las cremalleras de latón, el fondo blanco sin costuras permanece limpio y sin sombras,
producto perfectamente nítido y sin cambios, sutil energía premium de comercio electrónico.

Salida real: grok-imagine/image-to-video, 6 s a 720p, una sola imagen de referencia. Primera generación, sin editar. Entregado realmente a 960×960: la imagen fija de origen cuadrada anuló nuestra solicitud 9:16 (véase la nota sobre relación de aspecto más arriba). La imagen fija de origen aparece a continuación.

Patrones de prompt para mantener realistas los clips de producto:

• Un verbo de cámara ("orbitar", "acercarse", "desplazarse"). Dos movimientos en un mismo prompt te dan una imagen de mareo.
• Escribe explícitamente "producto sin cambios / perfectamente nítido". Los modelos de imagen a video derivan; decirle al modelo que el sujeto no puede modificarse reduce notablemente la deformación de logotipos, costuras y herrajes.
• Menciona el momento de materialidad ("destellando en las cremalleras de latón"): el reflejo de luz que se desplaza sobre el metal y el cuero es justo lo que hace que una imagen fija parezca una grabación en lugar de una distorsión.
• Fija el fondo ("permanece limpio y sin sombras"). De lo contrario, el modelo inventará su propio decorado.

Varias imágenes de referencia: bloquear el sujeto

image_urls acepta más de una imagen de referencia, y esto es lo que distingue a grok-imagine de los animadores de un solo fotograma en el trabajo con productos. Dale una imagen de estilo de vida que quieras como escena, más una imagen limpia del producto como seguro de identidad, y el modelo conciliará ambas: la escena sale de la primera imagen y los ribetes, correas y cremalleras exactos del producto quedan anclados por la segunda:

El mismo bolso weekender naranja quemado descansa sobre un banco de madera desgastada en un
ático iluminado por el sol; un suave acercamiento mientras las motas de polvo flotan en la cálida luz de la ventana,
las sombras suaves se deslizan lentamente por el banco, el bolso y su ribete de cuero oscuro
permanecen exactamente consistentes con las imágenes de referencia, ambiente tranquilo de catálogo de estilo de vida.

Salida real: grok-imagine/image-to-video, 6 s a 720p, 9:16, dos imágenes de referencia (imagen de estilo de vida en el banco + imagen de producto sobre fondo blanco). Primera generación, sin editar.

Fíjate en la frase "consistente con las imágenes de referencia" del prompt: al usar varias imágenes de referencia, decirlo explícitamente ayuda al modelo a tratar las imágenes adicionales como restricciones de identidad en lugar de una segunda escena en la que fusionarse. Este es el patrón para las cuentas de marca que publican a diario: fotografiar (o generar) una imagen de producto por SKU y luego reutilizarla como ancla de consistencia en cada clip de estilo de vida que quieras animar.

Economía de la duración y la franja de borrador

La duración va de 6 a 30 segundos, y la resolución es donde está la palanca de presupuesto: el precio por segundo a 480p es aproximadamente la mitad que a 720p. Como el feed comprime agresivamente de todos modos, una tubería sensata es hacer borradores a 480p y rehacer los ganadores a 720p. Las duraciones más largas también dan al modelo espacio para un desarrollo pausado: a continuación un clip de 12 segundos en la franja de borrador a 480p, con un movimiento ambiental continuo sobre una imagen fija de una lata de té:

Acercamiento lento y atmosférico a la lata de té negro mate sobre pizarra, el vapor se eleva
perezosamente detrás, un suave haz de luz matinal barre la etiqueta en relieve,
pequeñas hojas de té caen suavemente sobre la pizarra en los últimos segundos, atmósfera
oscura y premium, el texto de la etiqueta sin cambios y legible.

Salida real: grok-imagine/image-to-video, 12 s a 480p, una sola imagen de referencia. Primera generación, sin editar (entregado en cuadrado, consistente con la imagen fija de origen cuadrada). Coste: $0.137.

Renderizar a 480p cuesta $0.0114/segundo: el clip completo de 12 segundos costó solo 13,7 céntimos. Lo bastante barato como para probar tres variantes de prompt por producto y pagar la tarifa de 720p solo por el que realmente publiques. Fíjate en "el texto de la etiqueta sin cambios y legible" del prompt: el texto del envase es lo primero que se emborrona en imagen a video, mencionarlo es tu protección más barata.

Procesar el catálogo por lotes

Todo lo anterior escala de forma lineal porque las tareas son asíncronas: envía todo el lote y luego sondea. Un ejecutor de lotes mínimo para una lista de productos:

products = [
    {"sku": "weekender-orange", "refs": ["https://cdn.example.com/weekender.jpg"],
     "prompt": "Órbita cinematográfica lenta alrededor del bolso, luz de estudio en las cremalleras de latón, fondo limpio, producto sin cambios."},
    {"sku": "tea-tin-black", "refs": ["https://cdn.example.com/tea-tin.jpg"],
     "prompt": "Acercamiento lento y atmosférico, vapor flotando, luz barriendo la etiqueta en relieve, texto de la etiqueta sin cambios."},
    # ... el resto del catálogo
]

jobs = []
for p in products:
    tid = submit({
        "prompt": p["prompt"],
        "image_urls": p["refs"],
        "duration": 6,
        "resolution": "480p",     # franja de borrador
        "aspect_ratio": "9:16",
    })
    jobs.append((p["sku"], tid))

for sku, tid in jobs:
    task = wait(tid)
    url = task["output"][0]["url"]
    subprocess.run(["curl", "-s", "-o", f"{sku}.mp4", url], timeout=180)
    print(f"{sku}: done")

Consejos prácticos de procesamiento por lotes para ejecutar esta tubería:

• Envía primero, sondea después. Cada renderizado tarda varios minutos y se ejecuta en paralelo en el servidor; serializar "enviar-esperar-enviar" desperdicia ese paralelismo.
• Mantén una plantilla de prompt plana por tipo de contenido (órbita para imágenes de producto, acercamiento para imágenes de estilo de vida) e interpola el sustantivo del producto. La consistencia de todo el feed importa más que la ingeniosidad de cada clip.
• Comprobación de presupuesto: un catálogo de 50 SKU con borradores de 6 s a 480p cuesta 50 × $0.068 ≈ $3.42. Promover los diez mejores a 720p añade diez × $0.128 ≈ $1.28. Un mes entero de clips diarios de producto cuesta menos que una hora de tiempo de estudio.

Notas para publicar videos cortos

• El formato vertical requiere imágenes de referencia verticales. Como se indicó, la relación de aspecto de la referencia a menudo anula aspect_ratio; si el clip va a un feed, recorta la imagen fija a 9:16 antes de enviarla. Recortar un renderizado cuadrado terminado a vertical desperdicia la mayor parte de los píxeles.
• El primer segundo es el gancho: los prompts que ponen el movimiento en marcha de inmediato ("la cámara orbita", "acercamiento") superan a las aperturas con fundido lento en tasa de finalización.
• Los clips incluyen una pista de ambiente generada por el modelo. Cada salida que generamos trae un flujo AAC: algunos clips tienen un sutil ambiente de estudio, otros son casi silenciosos. No hay campo de entrada para controlarlo, así que al publicar planifica sustituirlo por tu propia música o locución en lugar de tratarlo como banda sonora terminada.
• Amigable para bucles: las órbitas y los barridos de luz se repiten mucho mejor que los clips que terminan en una revelación. Para feeds con bucle automático (Shorts, Reels), el patrón de órbita anterior se reproduce sin costuras.

Preguntas frecuentes

¿Cuánto tarda en renderizarse? Los clips de 6 segundos de este artículo tardaron unos minutos cada uno en renderizarse; el clip de 12 segundos algo más. Trátalo como una cola asíncrona, no como una llamada interactiva: envía por lotes y sondea.

¿Puedo usar imágenes generadas como imágenes de referencia? Sí. La URL de referencia solo tiene que ser recuperable públicamente. Las tres imágenes fijas de origen de este artículo son en sí mismas imágenes de producto generadas por la API (procedentes de ejecuciones de seedream-5.0-lite), extraídas de nuestra biblioteca de recursos: una tubería de imagen fija a video totalmente sintética.

¿Y 1080p o más de 30 segundos? Este endpoint está limitado a 720p y 30 segundos. Para feeds de video corto, ese es precisamente el rango óptimo; si necesitas mayor resolución, escala en posproducción o consulta el catálogo de modelos para ver las opciones actuales.

¿En qué se diferencia de grok-imagine-1.5/image-to-video? El endpoint de vista previa 1.5 cambia alcance por calidad de movimiento: duraciones de 1 a 15 segundos, movimiento mejorado, mismo precio por segundo. Este endpoint 1.0 te da de 6 a 30 segundos. Cubrimos los fundamentos de la 1.5 en otro artículo detallado.

¿Hay una versión de texto a video? Sí: grok-imagine/text-to-video, la misma interfaz de tareas, solo con entrada de prompt. Cuando la consistencia de marca/producto importa, la imagen a video es la elección correcta; cuando necesitas generar material desde cero, usa texto a video.

---

Si tienes imágenes fijas de producto y una clave de API, estás a un solo POST /v1/tasks de tu primer clip para feed: obtén la clave desde el panel, empieza en la página del modelo grok-imagine/image-to-video y anima una imagen de producto con el prompt de órbita anterior; a 13 céntimos por borrador, la forma más rápida de aprender este modelo es ejecutarlo.