Cómo llamar a hailuo-2.3/text-to-video mediante la API de HiAPI: curl, Python y ejemplos de solicitud ejecutables

Qué hace el endpoint hailuo-2.3/text-to-video

Si tienes un prompt de texto y quieres generar a partir de él un clip de vídeo corto, hailuo-2.3/text-to-video es el endpoint que buscas. Recibe un prompt en lenguaje natural que describe la escena, el sujeto y el movimiento que quieres ver; después devuelve el clip de vídeo generado. El modelo está ajustado para salidas de corta duración, por lo que rinde mejor cuando le pides un instante compacto y autónomo en lugar de una narración larga.

En HiAPI, la llamada sigue el mismo patrón que otros endpoints de generación asíncrona: envías la solicitud, el servicio acepta la tarea y luego sondeas hasta que el resultado está listo. Esto hace que el endpoint sea ideal para pipelines de backend: herramientas de contenido, generadores de prototipos, tareas por lotes o cualquier escenario en el que necesites obtener unos segundos de vídeo bajo demanda sin que una persona esté sentada frente a un editor de vídeo.

La solicitud lleva un prompt y unos pocos parámetros de control de generación; la respuesta lleva un identificador de tarea y, después, la URL del vídeo terminado. No tienes que gestionar GPU ni pesos de modelo: HiAPI se encarga del cómputo y devuelve el enlace de salida. Si has usado otras API de texto a vídeo, la forma general te resultará familiar, pero el estilo de prompt de hailuo-2.3 premia pensar en la física del movimiento y no solo en la descripción visual (lo detallamos más adelante).

Requisitos previos y credenciales de API

Antes de la primera llamada, asegúrate de tener tres cosas preparadas:

• Una clave de API de tu cuenta de HiAPI. Trátala como una contraseña: no la incluyas en el control de versiones, cárgala desde una variable de entorno y rótala si se filtra.
• Un cliente HTTP. Los ejemplos de shell de abajo solo necesitan curl. Los ejemplos de Python necesitan Python 3.8+ y la librería requests (pip install requests).
• La URL base de la API de HiAPI. Todas las solicitudes se envían al host de la API de HiAPI, con la ruta del endpoint hailuo-2.3/text-to-video. Te autenticas enviando un bearer token en la cabecera Authorization.

Configura la clave en una variable de entorno para que no aparezca en tu código:

export HIAPI_API_KEY="your_api_key_here"

En Python, puedes leerla con os.environ["HIAPI_API_KEY"]. En curl, harás referencia a la misma variable con $HIAPI_API_KEY.

Hay una cosa más que decidir de antemano: dónde se almacenarán los vídeos generados. La API devuelve la URL de la salida, que debe obtenerse y almacenarse con prontitud en tu propio bucket o sistema de archivos; no construyas un pipeline que asuma que esa URL es un activo permanente.

Solicitud ejecutable con curl

A continuación tienes una llamada completa con curl para enviar una tarea de texto a vídeo. Sustituye el prompt por tu propia descripción de escena. El cuerpo de la solicitud es JSON y los campos clave son el prompt y los parámetros de generación que controlan la duración y la forma de la salida.

curl -X POST "https://api.hiapi.ai/v1/hailuo-2.3/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Una canica de cristal rueda por una rampa de madera, acelera y cae sobre un suelo de piedra, rebota dos veces y se detiene",
    "duration": 6
  }'

Un envío correcto devuelve un objeto JSON con un identificador de tarea. Se parece a esto:

{
  "id": "job_abc123",
  "status": "queued"
}

La parte clave es id. La generación no se completa de forma síncrona: el endpoint pone la tarea en cola y devuelve de inmediato. Guarda el id; lo usarás para sondear el estado y, finalmente, obtener la URL del vídeo.

Si encuentras un error de autenticación, comprueba que la clave se haya exportado en la misma sesión de shell. Si encuentras un error de validación, comprueba que el cuerpo JSON tenga el formato correcto y que el prompt exista. Una respuesta 429 significa que enviaste solicitudes demasiado rápido y deberías aplicar retroceso: lo detallamos en la sección de producción.

La misma llamada en Python

La versión de Python hace lo mismo, pero encapsulada en una función reutilizable para que puedas colocarla en un pipeline. Envía la tarea y devuelve el identificador de tarea.

import os
import requests

HIAPI_BASE = "https://api.hiapi.ai/v1"


def submit_text_to_video(prompt: str, duration: int = 6) -> str:
    """Envía una tarea hailuo-2.3/text-to-video y devuelve su id de tarea."""
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE}/hailuo-2.3/text-to-video",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"prompt": prompt, "duration": duration},
        timeout=30,
    )
    response.raise_for_status()
    data = response.json()
    return data["id"]


if __name__ == "__main__":
    job_id = submit_text_to_video(
        "Una canica de cristal rueda por una rampa de madera, acelera y cae sobre un suelo de piedra, rebota dos veces y se detiene"
    )
    print("submitted job:", job_id)

Hay varios detalles que merece la pena conservar:

• raise_for_status() convierte las respuestas que no son 2xx en excepciones, que es el comportamiento deseado en un pipeline. Fallar de forma ruidosa en la fase de envío es mejor que sondear una tarea que nunca se creó.
• El timeout de la solicitud de envío se establece deliberadamente corto. El envío debería ser rápido; las esperas largas ocurren en la fase de sondeo, no aquí.
• El parámetro duration es un parámetro independiente, de modo que quien llama puede pedir un clip más corto o más largo sin duplicar la lógica de construcción de la solicitud.

Una vez que la función devuelve, tienes todo lo necesario para continuar con el sondeo de estado.

Redactar prompts de física del movimiento para clips de 6-10 segundos

Los clips cortos no dan tregua. En seis o diez segundos no puedes establecer un personaje, construir un mundo y cerrar una trama; por eso los prompts más eficaces describen una única acción continua con consecuencias físicas claras. Piensa en el prompt como la descripción de un plano en un instante, no como una historia.

Empezar por el sujeto y la acción

Empieza por lo que se mueve y lo que está haciendo. "Una canica de cristal rueda por una rampa de madera" da inmediatamente al modelo el sujeto, el material y la dirección del recorrido. Un comienzo vago como "una escena bonita" no le da nada que animar.

Describir fuerzas, no solo la apariencia

Un prompt de física del movimiento implica nombrar las fuerzas que actúan: gravedad, fricción, momento, peso, elasticidad. Palabras como rodar, acelerar, rebotar, detenerse, balancearse, volcarse, salpicar o desgarrarse sugieren un modelo físico. Para un objeto que rebota, indica cuántas veces rebota y dónde acaba deteniéndose. Para un objeto que cae, indica sobre qué cae y si se rompe, se abolla o rebota.

Mantener el plano explícito y sencillo

Un plano fijo o un único movimiento de cámara lento suele bastar para un clip corto. Si tanto la cámara como el sujeto hacen cosas complejas, el clip se vuelve desordenado y el movimiento parece ruido. Indica el tipo de plano solo cuando sea importante para la acción: primer plano, plano general, travelling.

Construir un arco de acontecimiento

Una plantilla útil para clips de 6–10 segundos es: preparación → acción → consecuencia. La canica está en lo alto de la rampa; rueda hacia abajo y acelera; cae, rebota dos veces y se detiene. Este arco da al modelo un principio, un medio y un final, todos ajustados a la duración del clip. Evita pedir varias acciones no relacionadas; un único acontecimiento físico bien descrito se lee mucho mejor que tres acontecimientos a medias.

Por último, mantén el prompt concreto. Los materiales, la iluminación y las texturas de superficie ayudan al modelo a fundamentar el movimiento: una canica sobre madera no se comporta igual que una canica sobre hielo, y decirlo orienta el resultado.

Gestionar tareas asíncronas mediante sondeo

La generación lleva tiempo, por lo que el endpoint es asíncrono. Tras enviar la tarea recibes un id; luego sondeas el endpoint de estado hasta que la tarea alcanza un estado terminal. Un bucle de sondeo robusto gestiona tres cosas: intervalo, timeout y exposición de errores.

import time
import requests

HIAPI_BASE = "https://api.hiapi.ai/v1"


def wait_for_video(job_id: str, api_key: str, interval: float = 3.0, max_wait: float = 600.0) -> str:
    """Sondea hasta que la tarea termina y devuelve la URL del vídeo de salida."""
    deadline = time.time() + max_wait
    url = f"{HIAPI_BASE}/hailuo-2.3/text-to-video/{job_id}"

    while time.time() < deadline:
        response = requests.get(
            url,
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30,
        )
        response.raise_for_status()
        data = response.json()
        status = data.get("status")

        if status == "completed":
            return data["output"]["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"La tarea {job_id} terminó con el estado {status}: {data.get('error')}")

        time.sleep(interval)

    raise TimeoutError(f"La tarea {job_id} no se completó en {max_wait} segundos")

Notas sobre este bucle:

• Sondea a intervalos, no con un bucle apretado. Unos segundos entre comprobaciones bastan y evitan saturar la API.
• Limita siempre el tiempo total de espera. Una tarea colgada no debería suspender un proceso de trabajo para siempre. El valor de max_wait aquí es conservador; ajústalo según la duración de tus clips y las condiciones de la cola.
• Trata failed como una rama real. Expón la carga de error en lugar de reintentar a ciegas: los problemas de prompt o de parámetros no se arreglan solos.
• Devuelve la URL del vídeo, no la respuesta en bruto. Quien llame a esta función no debería necesitar conocer la estructura de la respuesta.

Para cargas de trabajo más pesadas, coloca los pasos de envío y sondeo en procesos de trabajo distintos: uno encola las tareas y almacena los ID de tarea, otro se encarga del sondeo y la descarga. Así desacoplas la latencia de la solicitud del tiempo de generación.

Descargar y almacenar la salida

Cuando el sondeo devuelve la URL del vídeo, obtén los bytes y escríbelos en una ubicación persistente. Hazlo con prontitud: la URL devuelta es un enlace de entrega, no un almacenamiento permanente de activos. Descarga en streaming en lugar de cargar el archivo entero en memoria; escribe primero en una ruta temporal y luego renombra, para que una descarga parcial nunca parezca un archivo completo.

import os
import tempfile
import requests


def download_video(video_url: str, dest_path: str) -> None:
    """Escribe el vídeo terminado en dest_path mediante streaming y de forma atómica."""
    os.makedirs(os.path.dirname(dest_path) or ".", exist_ok=True)
    with requests.get(video_url, stream=True, timeout=120) as response:
        response.raise_for_status()
        fd, tmp_path = tempfile.mkstemp(dir=os.path.dirname(dest_path) or ".")
        try:
            with os.fdopen(fd, "wb") as f:
                for chunk in response.iter_content(chunk_size=1 << 16):
                    f.write(chunk)
            os.replace(tmp_path, dest_path)
        except Exception:
            if os.path.exists(tmp_path):
                os.unlink(tmp_path)
            raise


api_key = os.environ["HIAPI_API_KEY"]
video_url = wait_for_video("job_abc123", api_key)
download_video(video_url, f"out/{'job_abc123'}.mp4")

Algunas decisiones prácticas:

• Nombra los archivos por ID de tarea. Esto te da una clave estable y resistente a colisiones, y hace trivial asociar el archivo con la solicitud que lo produjo.
• Guarda metadatos junto con el vídeo. Conserva el prompt original, la duración y la marca de tiempo en un JSON auxiliar o en una base de datos. Dentro de seis meses querrás saber qué produjo un clip.
• Sube a almacenamiento de objetos en producción. Escribir en disco local está bien para prototipos; un pipeline real debería enviar los archivos a tu bucket y registrar la clave del objeto, para que los vídeos sobrevivan a los reinicios de los procesos de trabajo.

Consejos para producción y modos de fallo habituales

La mayoría de las primeras integraciones fallan en los mismos pocos puntos. Esto es lo que hay que vigilar.

Reintentar lo correcto

Reintenta fallos transitorios —errores de red, timeouts, 429 y respuestas 5xx— con retroceso exponencial y jitter. No reintentes errores de validación 4xx; un prompt mal formado o un parámetro incorrecto fallarán igual todas las veces. Si la propia tarea de generación falla, expón el error y decide con prudencia si reenviarla.

Separar el envío del sondeo

En producción, el envío y el sondeo deberían ser pasos distintos, normalmente en procesos distintos. Guarda el ID de tarea en una cola o base de datos en cuanto el envío tenga éxito. Si un proceso de trabajo se cae, puedes reanudar el sondeo en lugar de perder la tarea.

Establecer timeouts en todas partes

La solicitud de envío, el sondeo de estado y la descarga del archivo deberían tener cada uno su propio timeout. La falta de timeout en el paso de descarga es la causa clásica de procesos de trabajo colgados.

Mantener los prompts dentro de los puntos fuertes del modelo

Pide una única acción físicamente plausible en el rango de seis a diez segundos. Cuando un prompt pide demasiado, obtienes un clip desordenado con un movimiento turbio. Si la calidad de la salida es inconsistente, acorta primero el prompt y simplifica la acción antes de plantearte cambiar parámetros.

Gestionar bien las credenciales

Carga las claves de API desde variables de entorno o un gestor de secretos, nunca desde archivos confirmados en el repositorio. Usa claves distintas por entorno, para que una clave de desarrollo filtrada no pueda alcanzar producción.

Ojo con las suposiciones de caducidad de URL

El error más común en producción es tratar la URL del vídeo devuelta como un enlace permanente y renderizarla directamente en una interfaz meses después. Descarga y rehospeda el archivo como parte de la tarea, y guarda tu propia URL.

Con estos hábitos, la integración es pequeña: enviar, sondear, descargar, almacenar.