Genera videos cortos por lotes con hailuo-2.3-fast/image-to-video en hiapi

El éxito de los videos cortos depende de la velocidad de iteración. Si tu flujo de trabajo es una cadena de producción orientada a TikTok o Reels, no necesitas una salida cinematográfica en 4K: lo que necesitas es un modelo que convierta una imagen estática de producto en un clip utilizable en menos de un minuto, y a un costo lo bastante bajo como para generar decenas de variantes antes de elegir la mejor versión. Es exactamente ahí donde encaja hailuo-2.3-fast/image-to-video: el hermano de la capa Fast de hailuo-2.3, con precios y ajustes pensados específicamente para flujos de trabajo de alto volumen con múltiples intentos desechables.

Esta guía te muestra cómo usarlo como motor de videos cortos por lotes: cómo elegir la imagen estática de origen, cómo impulsarlo mediante la API de tareas asíncronas, cómo validar esos detalles del esquema que, si los pasas por alto, te harán recibir errores 400, y cómo pensar en la economía de ejecutarlo a escala de TikTok/Reels.

Qué te ofrece el modelo

hailuo-2.3-fast/image-to-video recibe una imagen estática y un prompt, y las anima para convertirlas en un clip de video corto. Se encuentra en la página del modelo hailuo-2.3-fast/image-to-video y, como todos los modelos de hiapi, se invoca a través del endpoint asíncrono unificado /v1/tasks: haces un POST de una tarea, consultas su estado (o registras un callback) hasta que se complete y luego descargas el video desde una URL de salida de vigencia limitada.

Verificado contra la API en producción al momento de escribir esto:

• Entrada: una imagen (image_url) + un prompt de texto que describe el efecto de movimiento que deseas
• Salida: MP4, con duración fija de 6 s o 10 s (no admite longitudes arbitrarias)
• Precio: precio único por video, no facturación por segundo: $0.27 por un clip de 6 segundos y $0.46 por uno de 10 segundos
• Tiempo de respuesta: nuestros clips de prueba se completaron de extremo a extremo (envío → éxito) en unos 80 segundos

El precio único por video es precisamente el detalle clave para los trabajos por lotes: un intento de 6 segundos cuesta lo mismo tanto si tu prompt acierta con el efecto de movimiento al primer intento como si ya vas por el cuarto. Con el precio de la capa Fast, generar 5 o 6 variantes de la misma imagen principal para encontrar la de movimiento más fluido sigue costando menos que un solo intento en la mayoría de los modelos de video de gama alta. Antes de presupuestar un lote, confirma las cifras actuales en la página de precios: los precios cambian.

Si necesitas la referencia completa de parámetros, opciones de mayor duración o una comparación lado a lado con la capa no Fast de hailuo-2.3, consulta nuestro tutorial de integración de la API de hailuo-2.3-fast/image-to-video; esta guía se centra en el ángulo de lotes/flujo de trabajo, no en la referencia de la API en bruto.

Flujo de trabajo: imagen estática → clip de video corto

La receta para videos cortos es sencilla: parte de una imagen estática que ya tengas (fotografía de producto, un hero shot generado, material de marca), y deja que el modelo añada movimiento (un acercamiento lento, una rotación sutil, una atmósfera flotante) en lugar de generar el video desde cero. Así fijas tu identidad visual (el mismo producto, la misma iluminación, la misma composición) y a la vez produces contenido que no es una publicación estática.

Este es un caso real: una imagen estática vertical (9:16) de una zapatilla deportiva sobre un pedestal iluminado, animada con un prompt de movimiento que describe un acercamiento lento y una rotación suave.

La imagen estática de origen y la solicitud completa:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3-fast/image-to-video",
    "input": {
      "prompt": "Slow smooth push-in on a chunky retro basketball sneaker in wolf-gray suede with volt yellow laces, floating above a wet concrete pedestal, subtle rotation revealing the side panel, mist drifting through teal-to-amber rim light, dust particles catching the light, stable cinematic camera movement, premium commercial product-video finish",
      "image_url": "https://static.hiapi.ai/gallery/2026/07/c2e71481d2eb81a7.jpg",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

Respuesta:

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

Consulta el estado hasta que la resolución termine:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KZ5FJV0TB8EYKDCV58FQ1F2X \
  -H "Authorization: Bearer $HIAPI_API_KEY"

{
  "status": "success",
  "output": [{"type": "video", "url": "https://temp.hiapi.ai/.../result.mp4", "expireAt": 1786421652}]
}

Ese output[0].url es temporal: descárgalo de inmediato y guárdalo en tu propio almacenamiento. No lo enlaces en caliente ni lo guardes en un campo de base de datos esperando que sea una URL estable.

Esquema de entrada (verificado contra la API en producción)

El esquema de este modelo es mucho más reducido de lo que cabría esperar por otros modelos de video de la plataforma: sin control de relación de aspecto, sin niveles de resolución, sin seed.

Campo	Tipo	Restricción	Obligatorio
prompt	string	Describe el movimiento/la escena	Sí
image_url	string	Singular: una URL pública, no un array	Sí
duration	string	Enumeración "6" o "10": como string, no como número	Sí
prompt_optimizer	boolean	Permite que la plataforma reescriba/mejore tu prompt	No

Si traes supuestos de otros modelos, hay dos trampas que te harán recibir un 400:

1. image_url es singular, no image_urls. Varios otros modelos i2v de hiapi reciben un array de imágenes de referencia; este modelo recibe solo una. Si envías un array, obtendrás un error de campo faltante, no una conversión de tipo útil.
2. duration debe ser el string "6" o "10", no el número 6. Enviar el número 6 devuelve duration: got number, want string. Además, no se acepta ningún valor fuera de esa enumeración de dos valores: esta capa no tiene control de duración arbitraria.

Enviar aspect_ratio, resolution, seed o watermark (campos habituales en modelos hermanos) se rechaza directamente con additional properties ... not allowed. El modelo hereda la relación de aspecto de la imagen de entrada, así que si necesitas una salida 9:16 para Reels/TikTok, recorta o genera la imagen estática de origen en 9:16 antes de enviarla (eso es exactamente lo que hicimos con la imagen de la zapatilla de arriba).

Python de extremo a extremo

import requests
import time

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "your-api-key"

def make_short_clip(prompt: str, image_url: str, out_path: str, duration: str = "6"):
    resp = requests.post(
        API_BASE,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "model": "hailuo-2.3-fast/image-to-video",
            "input": {
                "prompt": prompt,
                "image_url": image_url,
                "duration": duration,  # must be a string: "6" or "10"
                "prompt_optimizer": True,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API_BASE}/{task_id}",
                             headers={"Authorization": f"Bearer {API_KEY}"},
                             timeout=30).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(8)

    video_url = task["output"][0]["url"]  # temporary link — download immediately
    video_bytes = requests.get(video_url, timeout=120).content
    with open(out_path, "wb") as f:
        f.write(video_bytes)
    return out_path

Para una ejecución realmente por lotes (por ejemplo, probar 6 variantes de prompt sobre la misma imagen estática de origen para elegir el efecto de movimiento más fluido), envuelve esta función en un bucle sobre una lista de prompts y comprueba cada task_id de forma independiente en lugar de bloquear secuencialmente; a unos 80 segundos por clip, ejecutar varios en paralelo es lo que hace que la capa Fast se sienta realmente rápida.

Preguntas frecuentes

¿Puedo controlar la relación de aspecto de la salida? No: este modelo no tiene campo aspect_ratio y enviarlo devuelve un 400. La salida sigue la relación de aspecto de la imagen de entrada, así que prepara la imagen estática de origen con la proporción que necesites antes de enviarla (9:16 para Reels/TikTok, 1:1 para publicaciones de feed).

¿Por qué falla mi solicitud con "got number, want string"? Enviaste duration como un número JSON. Debe ser el string "6" o "10": son los dos únicos valores válidos.

¿Es el mismo modelo que hailuo-2.3/image-to-video (no Fast)? No: la capa Fast es un modelo independiente y con precio propio en hiapi, con su propio esquema, ajustado para velocidad y costo en lugar de para el estándar de la capa no Fast. Si necesitas el recorrido de referencia no orientado a lotes, consulta el tutorial de integración completo.

¿Puedo darle imágenes generadas en lugar de fotos reales? Sí: la imagen estática de origen puede venir de cualquier modelo de imagen de hiapi (o de otro lugar), siempre que sea una URL de acceso público. Usar las imágenes estáticas que ya produces para otros formatos (imágenes principales de producto, pósteres) suele ser la forma más rápida de obtener videos cortos sin un flujo creativo aparte.

¿El precio varía según la resolución? Este modelo no tiene parámetro de resolución, así que el precio es único por duración independientemente de la resolución de la imagen de entrada: al momento de escribir esto, $0.27 por 6 s y $0.46 por 10 s. Confírmalo en la página de precios.

Puntos clave

• hailuo-2.3-fast/image-to-video convierte una imagen estática en un MP4 de 6 s o 10 s, con precio único por video ($0.27 / $0.46) en lugar de facturación por segundo: lo bastante barato como para generar varias variantes de prompt por cada imagen de origen.
• El esquema es deliberadamente reducido: prompt, image_url (singular), duration (enumeración de strings "6"/"10") y el opcional prompt_optimizer; sin control de relación de aspecto, resolución ni seed.
• La salida hereda la relación de aspecto de la imagen de entrada, así que prepara la imagen estática de origen en 9:16 (o la proporción que requiera tu plataforma) antes de enviarla.
• Los dos errores de integración más comunes son enviar image_url como array y enviar duration como número en lugar de string.
• Para flujos de trabajo de videos cortos por lotes, el precio único por video y un tiempo de respuesta de unos 80 segundos hacen viable generar varios intentos y elegir el mejor efecto de movimiento, en lugar de enviar una sola generación por cada pieza de material.

¿Listo para probarlo con tus propias imágenes de producto? Ve a la página del modelo hailuo-2.3-fast/image-to-video para probar una solicitud directamente, o si primero quieres comparar la capa Fast con otras opciones de imagen a video, consulta el catálogo completo de modelos.