Tutorial
Cómo llamar a hailuo-2.3/image-to-video mediante la API de HiAPI: curl y Python
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 →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio