Blog

Tutorial

Cómo llamar a hailuo-2.3/image-to-video mediante la API de HiAPI: curl y Python

Nov 12, 2026
Imagen de portada: franjas anchas de tejido entrelazadas sobre un fondo de color café oscuro, con un estilo de ilustración de tejido plano, salpicadas de pequeños cuadrados de color latón.
En esta página

Qué puede hacer hailuo-2.3/image-to-video y cuándo usarlo

hailuo-2.3/image-to-video es un modelo de imagen a vídeo disponible a través de la API unificada de HiAPI. Le proporcionas una imagen estática como primer fotograma, junto con una indicación que describe cómo debería moverse la escena, y el modelo genera un vídeo corto que comienza con esa imagen y avanza la animación a partir de ella.

La palabra clave es primer fotograma. En texto a vídeo, el modelo imagina toda la escena a partir de la indicación; en imagen a vídeo, la composición, el sujeto, la iluminación y el estilo quedan anclados a la imagen que proporcionas. Por eso resulta la opción adecuada cuando ya tienes material visual concreto que debe conservarse —fotografías de producto, imágenes de referencia de personajes, fotogramas de storyboard, renders conceptuales— y quieres superponer movimiento en lugar de reinterpretarlo.

Escenarios en los que conviene usar este endpoint:

  • Necesitas mantener la coherencia con material existente. Una foto de producto no debería regenerarse como un producto ligeramente distinto, sino animarse.
  • Estás construyendo un storyboard o animatic a partir de fotogramas estáticos y quieres previsualizar el movimiento con rapidez.
  • Necesitas composición controlada: la posición de la cámara y del sujeto proviene de la imagen, y la indicación solo describe el movimiento.

Si no tienes una imagen de referencia y quieres que el modelo diseñe el plano, o si los detalles visuales se expresan mejor con texto que fijándolos mediante un fotograma, es más adecuado usar texto a vídeo.

Requisitos previos y obtención de la clave de API

Antes de tu primera solicitud necesitas tres cosas: una cuenta de HiAPI, una clave de API y una URL de imagen del primer fotograma accesible públicamente.

Cuenta y clave de API

Inicia sesión en HiAPI y crea una clave de API en la consola. Trata la clave como un secreto: guárdala en una variable de entorno en lugar de pegarla en el archivo de código fuente. Los ejemplos de esta guía la leen de HIAPI_API_KEY.

export HIAPI_API_KEY="your-api-key-here"

URL de imagen accesible

La imagen que se pasa como primer fotograma debe poder ser obtenida por el servidor —sirve una URL firmada de almacenamiento en la nube, un enlace de CDN o cualquier URL HTTPS pública, pero no una ruta de archivo local—. Si el material está en una ubicación que requiere autenticación, genera para la solicitud una URL firmada con validez temporal.

Antes de automatizar cualquier flujo, confirma la ruta del endpoint, los nombres de parámetros y los valores permitidos actuales en la documentación de referencia de la API de HiAPI más reciente. Las interfaces de los modelos evolucionan, y codificar de forma fija los nombres de parámetros vistos en tutoriales antiguos es una fuente común y evitable de errores. El precio actual y cualquier regla de cuota figuran en el panel de precios del sitio web; confírmalos allí en lugar de suponerlos.

Estructura de la solicitud: entrada de imagen y parámetros

Conceptualmente, una solicitud de imagen a vídeo consta de tres partes: el identificador del modelo, la imagen y los parámetros de generación.

Identificador del modelo

Cada llamada apunta a hailuo-2.3/image-to-video. Centralízalo en un solo lugar del código para que cambiar de modelo posteriormente requiera cambiar una sola línea.

Imagen del primer fotograma

Es la URL de la imagen estática con la que comienza el vídeo. Su relación de aspecto y resolución determinan la geometría base de la salida, así que elige una imagen que ya tenga la composición que necesitas en lugar de recortarla después. Una imagen limpia, bien iluminada y con un sujeto claro produce un movimiento mucho más predecible que un collage desordenado.

Indicación (prompt)

El campo de texto que describe el movimiento; se trata en la sección siguiente.

Duración y resolución

Las tareas de imagen a vídeo suelen ofrecer opciones de duración del clip y de resolución de salida. Es muy probable que estos parámetros cambien según la versión del modelo, así que no los codifiques de forma fija de memoria. Abre la documentación de referencia de la API más reciente, lee los nombres de campo aceptados y los valores permitidos, y coloca esos valores en un objeto de configuración en lugar de dispersar literales por el código. Si se rechaza un valor, la respuesta de la API normalmente indicará qué campo es el problemático.

El cuerpo de la solicitud es JSON; la respuesta devuelve un identificador de tarea, no el vídeo terminado, lo cual se trata en la sección de sondeo a continuación.

Escribir indicaciones que produzcan un movimiento creíble

La imagen ya describe qué hay en la escena. La tarea de la indicación es describir cómo se mueve. Una indicación que vuelve a describir al sujeto desaprovecha la capacidad del modelo; una indicación que especifica el movimiento, el comportamiento de la cámara y las leyes físicas produce clips mucho mejores.

Describe el movimiento, no el contenido

Ejemplo deficiente: «Una mujer con abrigo rojo de pie en un puente».

Mejor ejemplo: «La mujer gira lentamente la cabeza hacia la cámara mientras el abrigo se agita con el viento; la cámara avanza suavemente».

Separa el movimiento del sujeto del movimiento de cámara

Sé explícito con ambos. «Avance lento», «deriva de cámara en mano», «cámara fija» y «órbita hacia la derecha» indican cómo cambia el encuadre; «el pelo ondea», «el vapor asciende» y «las páginas pasan» describen lo que ocurre dentro del encuadre. Combinar ambos produce un plano coherente en lugar de una imagen a la deriva.

Respeta las leyes físicas

Pide movimientos razonables a velocidades razonables: «la tela se ondula suavemente», «el agua fluye río abajo», «el humo se enrosca hacia arriba». Evita instrucciones que contradigan la escena —hacer que un sujeto sentado camine o pedir un paneo rápido en un plano de producto con cámara fija suele producir artefactos—.

Sé breve y concreto

Dos o tres frases concretas y de carácter físico superan a un párrafo entero de adjetivos. Indica primero el movimiento principal, luego la cámara y por último detalles secundarios como cambios de iluminación.

Enviar la tarea y sondear el resultado

La generación de vídeo lleva tiempo, por lo que la API es asíncrona. El ciclo de vida consta de tres pasos:

1. Crear la tarea

Envía por POST la URL de la imagen, la indicación y los parámetros al endpoint. Una respuesta correcta devuelve un identificador de tarea y un estado inicial, normalmente algo como queued o processing. En esa respuesta aún no hay vídeo.

2. Sondear la tarea

Envía periódicamente solicitudes GET para ese identificador de tarea. Cada respuesta informa el estado y, cuando está completa, incluye la carga del resultado. Sondea a intervalos razonables —normalmente de varios segundos— en lugar de en un bucle apretado, y limita el número de intentos para que una tarea atascada no deje el proceso colgado de forma permanente.

3. Obtener el vídeo

Cuando el estado informa éxito, la respuesta contiene la ubicación del vídeo (normalmente una URL) y a menudo metadatos como la duración. Descárgalo o guárdalo según tus propias reglas de retención.

Puntos clave de diseño para producción

  • Persiste el ID de tarea. Si tu proceso de trabajo se cae a mitad del sondeo, querrás reanudar en lugar de reenviar y pagar por tareas duplicadas.
  • Gestiona los fallos terminales. Las tareas pueden fallar; trata el fallo como una rama independiente, no como «seguir sondeando».
  • Desacopla el envío del sondeo. En un backend web, envía desde el manejador de la solicitud y sondea desde un proceso de trabajo en segundo plano, de modo que un tiempo de espera HTTP nunca termine con una generación en curso.

Ejemplo de curl ejecutable

El siguiente ejemplo envía una tarea. Sustituye la URL de la imagen y la indicación por las tuyas; la clave proviene de la variable de entorno configurada anteriormente.

curl -sS -X POST \
  "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://your-cdn.example.com/first-frame.jpg",
    "prompt": "El sujeto de la escena gira ligeramente hacia la cámara y sonríe; la cámara avanza despacio y una luz suave recorre el rostro."
  }'

La respuesta contiene un identificador de tarea. Sondéala con una solicitud GET:

curl -sS \
  "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video/TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Repite hasta que el estado sea el de éxito terminal y luego lee la URL del vídeo en la carga. La ruta exacta del endpoint y los nombres de campo mostrados aquí solo ilustran el patrón; confírmalos con la documentación de referencia de la API más reciente antes de pegar nada en código de producción, porque las interfaces de los modelos cambian de verdad.

Ejemplo de Python ejecutable

Este script envía la tarea y luego sondea hasta que termina, e incluye tiempo de espera y manejo básico de errores.

import os
import time

import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def create_task(image_url: str, prompt: str) -> str:
    resp = requests.post(
        BASE,
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image_url": image_url, "prompt": prompt},
        timeout=60,
    )
    resp.raise_for_status()
    data = resp.json()
    task_id = data.get("task_id") or data.get("id")
    if not task_id:
        raise RuntimeError(f"No task id in response: {data}")
    return task_id


def poll_task(task_id: str, timeout_s: int = 600, interval_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = str(data.get("status", "")).lower()
        if status in {"succeeded", "success", "completed"}:
            return data
        if status in {"failed", "error", "cancelled"}:
            raise RuntimeError(f"Task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"Task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task = create_task(
        image_url="https://your-cdn.example.com/first-frame.jpg",
        prompt="El vapor asciende de la taza; la cámara deriva lentamente hacia la derecha.",
    )
    result = poll_task(task)
    print(result)

Como las cadenas de estado pueden diferir entre versiones de la API, el código comprueba un pequeño conjunto de valores comunes de éxito y de fallo en lugar de un único literal; verifica el vocabulario exacto en la documentación de referencia de la API y ajusta el conjunto en consecuencia. Si construyes varias canalizaciones de medios, tener esta función auxiliar aislada facilita su reutilización.

Modos de fallo comunes y métodos de depuración

La mayoría de los problemas con este endpoint se encuadran en las siguientes categorías.

Imagen rechazada o inaccesible

El servicio debe poder descargar tu imagen. Si aparece un error de obtención o de validación, comprueba que la URL sea HTTPS pública, que no haya caducado (las URL firmadas caducan) y que el formato y el tamaño estén dentro de los límites de la documentación. Una comprobación rápida consiste en abrir la URL en una ventana privada del navegador: si pide iniciar sesión, el servidor tampoco podrá leerla.

Parámetros no válidos

Una duración o resolución rechazada, o un campo desconocido, normalmente devuelve un error de validación que indica el campo. Compara tu carga con la documentación de referencia de la API más reciente, no con un tutorial, y registra el cuerpo completo del error: el mensaje de error es más específico que el código de estado HTTP por sí solo.

Errores de autenticación

Un 401 o 403 casi siempre significa que la clave falta, tiene un formato incorrecto o carece de permiso de acceso. Confirma que la cabecera Authorization está presente y que la variable de entorno realmente se ha exportado en el shell o proceso que ejecuta la solicitud.

Tiempo de espera del sondeo

Si la tarea sigue en processing después de tu tiempo de espera, comprueba primero que estás sondeando el ID de tarea correcto y luego amplía el tiempo de espera. En producción, distingue entre «sigue ejecutándose» y «atascada»: persiste el estado y deja que el proceso de trabajo reanude el sondeo en lugar de reenviar, ya que reenviar desperdicia tareas.

La tarea falla tras enviarse

Las tareas fallidas suelen apuntar a la combinación de indicación e imagen —instrucciones de movimiento contradictorias, o un primer fotograma que entra en conflicto con el movimiento solicitado—. Simplifica la indicación, prueba con un primer fotograma más limpio y vuelve a ejecutar.

La salida no parece correcta

Si el movimiento es débil o extraño, la solución casi siempre está en la indicación: indica con claridad el movimiento principal, separa el comportamiento de la cámara del comportamiento del sujeto y mantén un movimiento físicamente razonable. Registra en los logs el ID de solicitud y el ID de tarea para poder asociar un clip deficiente con la entrada exacta que lo produjo. Antes de publicar, confirma los nombres de los parámetros y los precios actuales en la documentación de referencia de la API y en el panel de precios.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API