Hailuo API : guide Python pour MiniMax H3 et 3 modes vidéo testés

L'API Hailuo est l'API vidéo de MiniMax, et son modèle actuel est MiniMax H3 (MiniMax-H3), la génération qui suit Hailuo 01 et 02. Chaque appel est asynchrone : créer une tâche, l'interroger, télécharger le MP4. Le 26 octobre 2026, nos clips de 5 secondes en 768P ont demandé entre 35 et 42 secondes dans les trois modes, et chacun est revenu avec du son.

Réponse courte

• Modèle : MiniMax-H3 sur l'API de MiniMax, annoncé le 31 juillet 2026 (notes de version) ; minimax-h3 sur OmniaKey, un seul id pour les trois types de tâche (documentation vidéo).
• Réglages : resolution (obligatoire) avec "768P" ou "2K", duration de 4 à 15 secondes entières, aspect_ratio (documentation vidéo).
• Coût : $0.08 par seconde en 768P, $0.40 pour 5 secondes, $0.13 en 2K, le prix catalogue de MiniMax (tarifs, vérifié le 26 octobre 2026) ; le tarif d'OmniaKey est sur la page du modèle.
• Durée et son : 35 à 42 secondes par clip, tous avec un son stéréo ; la référence de création V2 ne mentionne aucun interrupteur pour couper le son (référence de création).

Existe-t-il une API Hailuo officielle ?

Oui. MiniMax l'exploite sur platform.minimax.io, et le modèle actuel y est MiniMax H3, d'id MiniMax-H3 (page des modèles, vérifiée le 26 octobre 2026).

L'annonce de MiniMax présente H3 comme la génération qui suit Hailuo 01 et Hailuo 02 (annonce). Les modèles plus anciens restent dans l'API, sous les ids MiniMax-Hailuo-2.3 et MiniMax-Hailuo-02 (référence V1).

Le nom change d'une page à l'autre. La documentation de MiniMax écrit « MiniMax H3 », la description du modèle dans l'API écrit « Hailuo-03 » (référence de création), et l'application Hailuo AI, où l'annonce invite à l'essayer, écrit « Hailuo 3.0 » (application). « Hailuo 3 » n'est pas un nom officiel.

La clé se crée dans Account > API Keys, et la facturation se fait à l'usage (FAQ API). Les packs vidéo de MiniMax couvrent les modèles plus anciens, pas H3 (tarifs).

MiniMax propose quatre variantes de H3 (référence de création) :

Sur l'API propre à MiniMax, un appel se fait en trois étapes (guide vidéo) :

• POST https://api.minimax.io/v2/video_generation renvoie un task_id (référence de création).
• Interroger GET /v2/query/video_generation/{task_id} jusqu'à succeeded, puis télécharger content.url (référence d'interrogation).
• Seules les tâches des 7 derniers jours sont interrogeables, et MiniMax ne publie pas la durée de validité de l'URL de téléchargement (référence d'interrogation).

V1 (Hailuo 2.3 et 02) passe l'id de tâche en paramètre ?task_id= plutôt que dans le chemin, donc gardez les deux flux séparés (référence V1).

OmniaKey vend l'accès API à MiniMax H3, et ces exemples passent par là. Le flux est identique : POST https://api.omniakey.com/v1/media/tasks avec un en-tête Idempotency-Key renvoie 202 et un id, puis vous interrogez GET /v1/media/tasks/{id} (présentation media). Le même flux fait tourner Grok Imagine Video dans notre guide de l'API Grok Imagine Video. Tous les prix ci-dessous sont ceux de MiniMax.

Quels paramètres peut-on régler ?

• resolution est obligatoire ; 1080P et 4K échouent avec 400 model_price_error (documentation vidéo), et V2 n'a pas de 1080P pour H3 (référence de création). Les trois modes ont tourné en 768P, et nous n'avons pas testé le 2K.
• duration va de 4 à 15 secondes entières (documentation vidéo) ; MiniMax-H3-Max commence à 5 et refuse 4 (référence de création).
• aspect_ratio accepte adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 ou 21:9 (documentation vidéo). Sur l'API de MiniMax, le texte vers vidéo exige un format fixe et l'image vers vidéo suit la forme de l'image (référence de création). Nous avons omis le format dans notre essai image vers vidéo, et le clip a gardé la forme de l'image fixe, 1376×768.
• input.media[] accepte first_frame et un last_frame facultatif pour l'image vers vidéo, ou reference_image, reference_video et reference_audio pour la référence vers vidéo. Les deux familles ne se mélangent pas, et une référence audio a besoin d'une référence image ou vidéo à côté (documentation vidéo). Chaque entrée est un type et une url, soit un lien HTTPS public, soit un data URI. OmniaKey plafonne la requête entière à 1 MiB, Base64 compris (présentation media), donc le script envoie des JPEG de 1024 pixels.
• Le prompt se met dans input.prompt (documentation vidéo), jusqu'à 7,000 caractères (guide vidéo). Le son que vous voulez se décrit là aussi.

Comment appeler l'API Hailuo depuis Python ?

Il faut Python 3 et requests, avec la clé dans une variable d'environnement.

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

Le seul argument est t2v, i2v ou r2v ; les exécutions qui ont besoin d'une image lisent bicycle.jpg ou robot.jpg dans le même dossier.

Voici le script que nous avons exécuté, sans modification :

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 sortie du 27 octobre 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

Chaque exécution a demandé de 47 à 60 secondes entre le départ et le fichier enregistré.

Gardez l'id de tâche. Une tâche lente n'a pas échoué : interrogez le même id au lieu de renvoyer la requête (présentation media). L'URL de téléchargement signée dure environ une heure et l'enregistrement de la tâche 24 heures, donc enregistrez le fichier tout de suite ou interrogez de nouveau pour obtenir une URL fraîche. Le téléchargement lui-même ne demande aucune clé d'API.

Ce que les trois modes ont renvoyé

Les trois clips viennent de trois tâches du 26 octobre 2026, avec exactement les corps de requête du script.

Chaque clip était un MP4, H.264, 24 fps, 5.17 secondes, avec un audio AAC stéréo à 32 kHz ; usage indiquait output_seconds: 5.

Texte vers vidéo : le batteur de rue

Le prompt est DRUMMER dans le script.

Ce que nous avons vu :

• Un trottoir mouillé la nuit, des néons rouges et bleus reflétés sur le sol, des voitures garées et un batteur en veste noire à capuche penché sur des seaux bleus retournés. La capuche cache le visage tout du long.
• La caméra avance d'un plan large vers un gros plan des mains, des baguettes en mouvement et du dessus des seaux, tandis qu'une personne avec un parapluie passe derrière lui.
• Les lettres des enseignes au néon ne forment pas de vrais mots. Les frappes de tambour gagnent en force vers la fin, mais la pluie n'est pas distincte dans le son.

À changer : s'il faut un visage, ajoutez « hood down, face visible » ; si la pluie doit s'entendre, donnez-lui une phrase de son à elle.

Image vers vidéo : la première image reste

La première image est une image fixe créée avec Nano Banana 2.1 ; le prompt est BICYCLE et ne décrit que le mouvement.

Ce que nous avons vu :

• La première image correspond à l'image fixe : le même vélo rouge, le mur en plâtre jaune, les volets, les plantes en pot et les pavés.
• La caméra avance jusqu'à ce que le panier de marguerites blanches remplisse le cadre, et le vélo comme le mur gardent leur forme jusqu'au bout.
• Sur les images vérifiées, nous n'avons pas vu de pétales tomber. Le son est une mélodie de piano solo lente, alors que le prompt ne mentionne ni son ni musique.

À changer : ne décrivez que le mouvement et le son, puisque l'image fixe fixe déjà l'aspect, et fabriquez l'image fixe dans la forme que le clip doit avoir.

Référence vers vidéo : une image garde le personnage

La référence est une seule image d'un petit robot orange créée avec Nano Banana 2.1 ; le prompt est ROBOT.

Ce que nous avons vu :

• Le même robot : corps arrondi orange, yeux ronds en verre bleu, une courte antenne surmontée d'une boule et un disque rond sur le côté de la tête, maintenant sur un balcon ensoleillé avec des pots de fleurs et d'herbes.
• Il verse l'eau d'un arrosoir rouge, le jet apparaît vers 1 seconde, et la caméra glisse légèrement sur le côté.
• Le son est de l'eau qui coule et éclabousse, il commence juste avant l'apparition du jet, sans musique.

À changer : le personnage n'a eu besoin d'aucune correction. Pour le garder identique sur plusieurs clips, réutilisez la même image de référence à chaque fois.

Son : décrivez-le, ou H3 le choisit

Quand le prompt ne disait rien du son, H3 l'a choisi : de l'eau pour le robot, ce qui colle à l'arrosage, et du piano pour le vélo. Décrivez dans le prompt le son qu'il vous faut. La référence de création V2 ne mentionne aucun interrupteur pour couper le son (référence de création), donc pour un clip muet, retirez la piste ensuite :

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

Cela écrit une copie avec seulement la vidéo H.264, toujours longue de 5.17 secondes et sans réencodage.

Quelles erreurs allez-vous rencontrer ?

Les erreurs viennent de l'API de tâches d'OmniaKey et, en appel direct, de celle de MiniMax.

• 400 missing_idempotency_key: En-tête Idempotency-Key absent. L'ajouter.
• 409 idempotency_key_reused: Même clé, nouveau corps. Une clé par tâche.
• 400 model_price_error: 1080P ou 4K. Passer en 768P ou 2K.
• 400 invalid_request: Corps ou paramètre incorrect. Vérifier les paramètres.
• 403 model_not_allowed: La clé n'a pas ce modèle. Vérifier l'accès de la clé.
• 503 no_available_channel: Modèle indisponible maintenant. Réessayer plus tard.
• provider_submit_uncertain: Refusé à l'envoi. Utiliser input.prompt, vérifier le média.
• Tâche failed: Génération échouée. Lire error.

Une tâche échouée ou annulée est remboursée (présentation media). Sur l'API propre à MiniMax (codes d'erreur, vérifiés le 26 octobre 2026) :

• MiniMax envoie le statut HTTP correspondant à chaque code, par exemple 401 avec 1004 et 400 avec 2013 (référence de création).
• H3 sur V2 autorise 300 requêtes par minute et 30 tâches simultanées (limites de débit).

Combien coûte l'API Hailuo ?

MiniMax facture H3 à la seconde de vidéo produite, selon la variante et la résolution (page des tarifs, vérifiée le 26 octobre 2026) :

À ces prix : 5 secondes en 768P coûtent $0.40, 10 secondes en 2K $1.30 et 15 secondes en 2K $1.95.

• Les 5 premières images d'entrée par tâche sont gratuites (2 sur Max), chaque image supplémentaire coûte $0.04 sur H3, et l'entrée audio est gratuite. La vidéo d'entrée est facturée à la seconde, et sur Max une seconde d'entrée ($0.143 en 768P) coûte plus cher qu'une seconde de sortie. À variante et résolution égales, les trois types de tâche coûtent la même chose.
• H3 fonctionne uniquement à l'usage, et les packs vidéo de MiniMax ne le couvrent pas. Les chiffres à la seconde des offres de l'application Hailuo AI sont des crédits d'application, pas des prix d'API (application).
• La plateforme chinoise de MiniMax a sa propre grille en yuans, donc ne convertissez pas l'une en l'autre (tarifs Chine, vérifiés le 26 octobre 2026).
• Sur OmniaKey, une tâche vidéo est facturée à la seconde produite au moment de sa création, et une tâche échouée ou annulée est remboursée (présentation media).

Le tarif actuel d'OmniaKey est sur la page du modèle MiniMax H3 ; la forme de la requête est dans la documentation de l'API vidéo.

Questions fréquentes

L'API Hailuo est-elle gratuite ?

Sur l'API propre à MiniMax, non : ses pages de tarifs, de démarrage rapide et de FAQ n'affichent ni essai gratuit ni crédit pour H3 (vérifiées le 26 octobre 2026). Seules les 5 premières images d'entrée par tâche et l'entrée audio sont gratuites (tarifs), et les crédits de l'application Hailuo AI ne servent pas de crédits d'API.

Quelle différence entre Hailuo 2.3 et MiniMax H3 ?

Hailuo 2.3 tourne sur V1 : 6 ou 10 secondes, jusqu'à 1080P, facturé à la vidéo, avec un prix catalogue de MiniMax à $0.28 pour 6 secondes en 768P (tarifs, référence V1). H3 tourne sur V2 : 4 à 15 secondes, 768P ou 2K, facturé à la seconde, avec un son stéréo (référence de création, page des modèles). MiniMax propose toujours les deux (FAQ modèles).

Qu'est-ce que MiniMax H3 Max ?

C'est une sortie conjointe de MiniMax et de fal.ai, post-entraînée par fal.ai sur H3 pour la vitesse (guide vidéo). Il produit des clips en 480P ou 768P de 5 à 15 secondes, et extra.prompt_expansion_mode accepte disabled, balanced (la valeur par défaut) ou quality (référence de création). Les pages de MiniMax ne disent pas la même chose sur les références : le guide vidéo et la FAQ modèles ne listent que le texte vers vidéo et l'image vers vidéo, tandis que la référence de création et la page des tarifs listent aussi la référence vers vidéo.

Peut-on faire tourner MiniMax H3 soi-même ?

Oui, hors de certaines régions. Les poids sont sur Hugging Face (MiniMaxAI/MiniMax-H3) et GitHub (MiniMax-AI/MiniMax-H3) sous la MiniMax H3 Community License Agreement, une licence maison (Hugging Face, GitHub). Dans la révision de la licence consultée le 26 août 2026, les États-Unis, l'UE, le Royaume-Uni et la Corée du Sud sont des territoires exclus qui demandent une licence séparée (guide de déploiement local).

Journal des mises à jour

27 octobre 2026 : première version, avec des clips réalisés le 26 octobre 2026.