Hailuo API: guía de MiniMax H3 en Python y 3 modos de video probados

La API de Hailuo es la API de video de MiniMax, y su modelo actual es MiniMax H3 (MiniMax-H3), la generación posterior a Hailuo 01 y 02. Cada llamada es asíncrona: se crea una tarea, se consulta y se descarga el MP4. El 26 de octubre de 2026, nuestros clips de 5 segundos en 768P tardaron entre 35 y 42 segundos en los tres modos, y todos llegaron con sonido.

Respuesta corta

• Modelo: MiniMax-H3 en la API de MiniMax, anunciado el 31 de julio de 2026 (notas de la versión); minimax-h3 en OmniaKey, un solo id para los tres tipos de tarea (documentación de video).
• Ajustes: resolution (obligatorio) con "768P" o "2K", duration de 4 a 15 segundos enteros, aspect_ratio (documentación de video).
• Coste: $0.08 por segundo en 768P, $0.40 por 5 segundos, $0.13 en 2K, el precio de lista de MiniMax (precios, consultado el 26 de octubre de 2026); la tarifa de OmniaKey está en la página del modelo.
• Tiempo y sonido: de 35 a 42 segundos por clip, todos con sonido estéreo; la referencia de creación de V2 no incluye ningún interruptor para apagar el sonido (referencia de creación).

¿Existe una API oficial de Hailuo?

Sí. MiniMax la ofrece en platform.minimax.io, y el modelo actual es MiniMax H3, con id MiniMax-H3 (página de modelos, consultada el 26 de octubre de 2026).

El anuncio de MiniMax presenta H3 como la generación posterior a Hailuo 01 y Hailuo 02 (anuncio). Los modelos anteriores siguen en la API como MiniMax-Hailuo-2.3 y MiniMax-Hailuo-02 (referencia de V1).

El nombre cambia según la página. La documentación de MiniMax dice "MiniMax H3", la descripción del modelo en la API dice "Hailuo-03" (referencia de creación) y la app Hailuo AI, adonde el anuncio manda a probarlo, dice "Hailuo 3.0" (app). "Hailuo 3" no es un nombre oficial.

La clave se crea en Account > API Keys y el cobro es por uso (preguntas sobre la API). Los paquetes de video de MiniMax cubren los modelos anteriores, no H3 (precios).

MiniMax lista cuatro variantes de H3 (referencia de creación):

En la API propia de MiniMax, una llamada tiene tres pasos (guía de video):

• POST https://api.minimax.io/v2/video_generation devuelve un task_id (referencia de creación).
• Se consulta GET /v2/query/video_generation/{task_id} hasta succeeded y luego se descarga content.url (referencia de consulta).
• Solo se pueden consultar las tareas de los últimos 7 días, y MiniMax no publica cuánto dura la URL de descarga (referencia de consulta).

V1 (Hailuo 2.3 y 02) pasa el id de la tarea como parámetro ?task_id= en lugar de un tramo de la URL, así que conviene no mezclar los dos flujos (referencia de V1).

OmniaKey vende acceso a la API de MiniMax H3, así que estos ejemplos se ejecutaron por ahí. El flujo es el mismo: POST https://api.omniakey.com/v1/media/tasks con una cabecera Idempotency-Key devuelve 202 y un id, y se consulta GET /v1/media/tasks/{id} (resumen de media). El mismo flujo mueve Grok Imagine Video en la guía de la API de Grok Imagine Video. Todos los precios de abajo son el precio de lista de MiniMax.

¿Qué parámetros se pueden ajustar?

• resolution es obligatorio; 1080P y 4K fallan con 400 model_price_error (documentación de video), y V2 no tiene 1080P para H3 (referencia de creación). Los tres modos se ejecutaron en 768P y no probamos 2K.
• duration va de 4 a 15 segundos enteros (documentación de video); MiniMax-H3-Max empieza en 5 y rechaza el 4 (referencia de creación).
• aspect_ratio acepta adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 o 21:9 (documentación de video). En la API de MiniMax, texto a video necesita una proporción fija e imagen a video sigue la forma de la imagen (referencia de creación). En nuestra prueba de imagen a video omitimos la proporción y el clip mantuvo la forma de la imagen fija, 1376×768.
• input.media[] acepta first_frame y un last_frame opcional para imagen a video, o reference_image, reference_video y reference_audio para referencia a video. Los dos tipos no se mezclan, y una referencia de audio necesita una referencia de imagen o de video que la acompañe (documentación de video). Cada entrada es un type y una url, ya sea un enlace HTTPS público o un data URI. OmniaKey limita la petición completa a 1 MiB, Base64 incluido (resumen de media), así que el script envía JPEG de 1024 píxeles.
• El prompt va en input.prompt (documentación de video), hasta 7,000 caracteres (guía de video). El sonido que quieras se describe ahí también.

¿Cómo se llama a la API de Hailuo desde Python?

Necesitas Python 3 y requests, con la clave en una variable de entorno.

pip install requests
export OMNIAKEY_API_KEY="your-key"
python hailuo_h3.py t2v   # or i2v (needs bicycle.jpg) or r2v (needs robot.jpg)

El único argumento es t2v, i2v o r2v; las ejecuciones que necesitan una imagen leen bicycle.jpg o robot.jpg de la misma carpeta.

Este es el script que ejecutamos, sin cambios:

import base64
import os
import sys
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

DRUMMER = (
    "A street drummer plays a fast rhythm on upturned plastic buckets on a rainy city sidewalk "
    "at night. Neon signs reflect in the puddles and a few people with umbrellas walk past "
    "behind him. The camera slowly pushes in from a medium shot to a close-up of his hands and "
    "drumsticks. Realistic, handheld documentary look, with the sound of rain and drumming."
)
BICYCLE = (
    "A gentle breeze moves the daisies in the basket and a few petals drift down to the "
    "cobblestones. The camera slowly pushes in toward the basket. The bicycle and the wall "
    "stay exactly as they are."
)
ROBOT = (
    "The small orange robot from the reference image waters potted plants on a sunny "
    "apartment balcony with a red watering can. Medium shot, slow sideways camera move, "
    "city rooftops in the background."
)


def data_uri(path):
    # A local JPEG sent inline. The whole request must stay under 1 MiB, so keep it small.
    with open(path, "rb") as f:
        return "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()


def make_video(operation, prompt, parameters, media, out):
    task_input = {"prompt": prompt}
    if media:
        task_input["media"] = media

    # 1. Create the task. Reuse the same Idempotency-Key only when retrying this exact request.
    resp = requests.post(
        API,
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={
            "model": "minimax-h3",
            "type": "video",
            "operation": operation,
            "input": task_input,
            "parameters": parameters,
        },
        timeout=60,
    )
    resp.raise_for_status()
    task = resp.json()
    print(operation, "task:", task["id"])

    # 2. Poll the same task. Slow is not failed: never resubmit, keep polling this id.
    deadline = time.time() + 15 * 60
    while task["status"] in ("queued", "processing"):
        if time.time() > deadline:
            raise SystemExit(f"still {task['status']}: poll {task['id']} again later")
        time.sleep(5)
        task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] != "succeeded":
        raise SystemExit(f"{operation} ended {task['status']}: {task.get('error')}")

    # 3. Download the clip now: the signed URL lasts about an hour.
    asset = task["assets"][0]
    with open(out, "wb") as f:
        f.write(requests.get(asset["url"], timeout=120).content)
    print("saved", out, asset["byte_size"], "bytes")


mode = sys.argv[1] if len(sys.argv) > 1 else "t2v"
if mode == "t2v":
    make_video(
        "text_to_video", DRUMMER,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        None, "drummer.mp4",
    )
elif mode == "i2v":
    make_video(
        "image_to_video", BICYCLE,
        {"resolution": "768P", "duration": 5},
        [{"type": "first_frame", "url": data_uri("bicycle.jpg")}], "bicycle.mp4",
    )
elif mode == "r2v":
    make_video(
        "reference_to_video", ROBOT,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        [{"type": "reference_image", "url": data_uri("robot.jpg")}], "robot.mp4",
    )

La salida del 27 de octubre de 2026:

$ python hailuo_h3.py t2v
text_to_video task: task_V5TXAJG7n3ny42imJNqgTXRL4L8PGStd
saved drummer.mp4 4612510 bytes
$ python hailuo_h3.py i2v
image_to_video task: task_c4m3wHmF79Cmq7ZhDrTnCyt8SmIaW1ls
saved bicycle.mp4 4705286 bytes
$ python hailuo_h3.py r2v
reference_to_video task: task_dqx1TYA7u0znN5PFTl9tbfdWgtbBUbKd
saved robot.mp4 5630121 bytes

Cada ejecución tardó de 47 a 60 segundos desde el inicio hasta el archivo guardado.

Guarda el id de la tarea. Una tarea lenta no ha fallado, así que conviene consultar el mismo id en vez de reenviar la petición (resumen de media). La URL de descarga firmada dura cerca de una hora y el registro de la tarea 24 horas, así que guarda el archivo de inmediato o vuelve a consultar para obtener una URL nueva. La descarga en sí no necesita clave de API.

Qué devolvieron los tres modos

Los tres clips salieron de tres tareas del 26 de octubre de 2026, con los cuerpos de petición exactos del script.

Todos los clips eran MP4, H.264, 24 fps, 5.17 segundos, con audio AAC estéreo a 32 kHz; usage indicaba output_seconds: 5.

Texto a video: el baterista callejero

El prompt es DRUMMER en el script.

Lo que vimos:

• Una acera mojada de noche, con neones rojos y azules reflejados en el suelo, coches aparcados y un baterista con chaqueta negra de capucha inclinado sobre cubos azules boca abajo. La capucha oculta la cara todo el tiempo.
• La cámara avanza de un plano general a un primer plano de las manos, las baquetas en movimiento y la parte superior de los cubos, mientras una persona con paraguas pasa por detrás.
• Las letras de los carteles de neón no forman palabras reales. Los golpes de batería ganan fuerza hacia el final, pero la lluvia no se distingue en el sonido.

Qué cambiar: si necesitas una cara, añade "hood down, face visible"; si la lluvia tiene que oírse, dale una frase de sonido propia.

Imagen a video: el primer fotograma se queda

El primer fotograma es una imagen fija hecha con Nano Banana 2.1; el prompt es BICYCLE y describe solo el movimiento.

Lo que vimos:

• El primer fotograma coincide con la imagen fija: la misma bicicleta roja, la pared de yeso amarilla, las persianas, las plantas en maceta y el empedrado.
• La cámara avanza hasta que la cesta de margaritas blancas llena el encuadre, y la bicicleta y la pared mantienen su forma hasta el final.
• En los fotogramas que revisamos no vimos caer pétalos. El sonido es una melodía lenta de piano solo, aunque el prompt nunca menciona sonido ni música.

Qué cambiar: describe solo el movimiento y el sonido, porque la imagen fija ya fija el aspecto, y prepara la imagen fija con la forma que quieras para el clip.

Referencia a video: una imagen mantiene el personaje

La referencia es una sola imagen de un robot naranja pequeño hecha con Nano Banana 2.1; el prompt es ROBOT.

Lo que vimos:

• El mismo robot: cuerpo redondeado naranja, ojos redondos de cristal azul, una antena corta con una bola encima y un disco redondo en el lado de la cabeza, ahora en un balcón soleado con macetas de flores y hierbas.
• Vierte agua de una regadera roja, el chorro se ve desde alrededor de 1 segundo y la cámara se desplaza un poco hacia un lado.
• El sonido es agua corriendo y salpicando que empieza justo antes de que aparezca el chorro, sin música.

Qué cambiar: el personaje no necesitó ningún arreglo. Para mantenerlo igual en varios clips, reutiliza la misma imagen de referencia cada vez.

Sonido: descríbelo o lo elige H3

Cuando el prompt no decía nada del sonido, H3 lo eligió: agua para el robot, que encaja con el riego, y piano para la bicicleta. Describe en el prompt el sonido que necesitas. La referencia de creación de V2 no incluye ningún interruptor para apagar el sonido (referencia de creación), así que para un clip mudo quita la pista después:

ffmpeg -i drummer.mp4 -an -c copy drummer-silent.mp4

Eso escribe una copia solo con el video H.264, de 5.17 segundos y sin recodificar.

¿Qué errores vas a encontrar?

Los errores vienen de la API de tareas de OmniaKey y, en una llamada directa, de la de MiniMax.

• 400 missing_idempotency_key: Falta la cabecera Idempotency-Key. Añádela.
• 409 idempotency_key_reused: Misma clave, cuerpo nuevo. Clave nueva por tarea.
• 400 model_price_error: 1080P o 4K. Usa 768P o 2K.
• 400 invalid_request: Cuerpo o parámetro incorrecto. Revisa los parámetros.
• 403 model_not_allowed: La clave no tiene este modelo. Revisa el acceso de la clave.
• 503 no_available_channel: Modelo no disponible ahora. Reintenta más tarde.
• provider_submit_uncertain: Rechazado en el envío. Usa input.prompt y revisa el material.
• Tarea failed: La generación falló. Lee error.

Una tarea fallida o cancelada se reembolsa (resumen de media). En la API propia de MiniMax (códigos de error, consultados el 26 de octubre de 2026):

• MiniMax envía el estado HTTP correspondiente con cada código, por ejemplo 401 con 1004 y 400 con 2013 (referencia de creación).
• H3 en V2 permite 300 peticiones por minuto y 30 tareas en ejecución a la vez (límites de uso).

¿Cuánto cuesta la API de Hailuo?

MiniMax cobra H3 por segundo de video de salida, según la variante y la resolución (página de precios, consultada el 26 de octubre de 2026):

Con esos precios: 5 segundos en 768P son $0.40, 10 segundos en 2K son $1.30 y 15 segundos en 2K son $1.95.

• Las primeras 5 imágenes de entrada por tarea son gratis (2 en Max), cada imagen extra cuesta $0.04 en H3 y la entrada de audio es gratis. El video de entrada se cobra por segundo, y en Max un segundo de entrada ($0.143 en 768P) cuesta más que un segundo de salida. Para la misma variante y resolución, los tres tipos de tarea cuestan lo mismo.
• H3 es solo pago por uso, y los paquetes de video de MiniMax no lo cubren. Las cifras por segundo de los planes de la app Hailuo AI son créditos de la app, no precios de API (app).
• La plataforma china de MiniMax tiene su propia lista de precios en yuanes, así que no conviertas una en la otra (precios de China, consultados el 26 de octubre de 2026).
• En OmniaKey, una tarea de video se cobra por segundo de salida al crearse, y una tarea fallida o cancelada se reembolsa (resumen de media).

La tarifa actual de OmniaKey está en la página del modelo MiniMax H3; la forma de la petición está en la documentación de la API de video.

Preguntas frecuentes

¿La API de Hailuo es gratis?

En la API propia de MiniMax no: sus páginas de precios, de inicio rápido y de preguntas no muestran prueba gratuita ni crédito para H3 (consultadas el 26 de octubre de 2026). Lo único gratis son las primeras 5 imágenes de entrada por tarea y la entrada de audio (precios), y los créditos de la app Hailuo AI no sirven como créditos de API.

¿Qué diferencia hay entre Hailuo 2.3 y MiniMax H3?

Hailuo 2.3 va en V1: 6 o 10 segundos, hasta 1080P, cobrado por video, con el precio de lista de MiniMax en $0.28 por 6 segundos en 768P (precios, referencia de V1). H3 va en V2: de 4 a 15 segundos, 768P o 2K, cobrado por segundo y con sonido estéreo (referencia de creación, página de modelos). MiniMax sigue listando los dos (preguntas sobre modelos).

¿Qué es MiniMax H3 Max?

Es un lanzamiento conjunto de MiniMax y fal.ai, con posentrenamiento de fal.ai sobre H3 para ganar velocidad (guía de video). Hace clips de 480P o 768P de 5 a 15 segundos, y extra.prompt_expansion_mode acepta disabled, balanced (el valor por defecto) o quality (referencia de creación). Las páginas de MiniMax no coinciden sobre si acepta referencias: la guía de video y las preguntas sobre modelos listan solo texto e imagen a video, mientras que la referencia de creación y la página de precios también listan referencia a video.

¿Se puede ejecutar MiniMax H3 por tu cuenta?

Sí, fuera de algunas regiones. Los pesos están en Hugging Face (MiniMaxAI/MiniMax-H3) y GitHub (MiniMax-AI/MiniMax-H3) bajo la MiniMax H3 Community License Agreement, una licencia propia (Hugging Face, GitHub). En la revisión de la licencia consultada el 26 de agosto de 2026, Estados Unidos, la UE, el Reino Unido y Corea del Sur son territorios excluidos que necesitan una licencia aparte (guía de despliegue local).

Registro de cambios

27 de octubre de 2026: primera versión, con clips hechos el 26 de octubre de 2026.