Hailuo API: MiniMax H3 mit Python und 3 Videomodi im Test

Die Hailuo API ist die Video-API von MiniMax, und ihr aktuelles Modell ist MiniMax H3 (MiniMax-H3), die Generation nach Hailuo 01 und 02. Jeder Aufruf läuft asynchron: Aufgabe anlegen, abfragen, MP4 herunterladen. Am 26. Oktober 2026 brauchten unsere 5-Sekunden-Clips in 768P in allen drei Modi 35 bis 42 Sekunden, und jeder kam mit Ton.

Kurze Antwort

• Modell: MiniMax-H3 in der API von MiniMax, angekündigt am 31. Juli 2026 (Release Notes); minimax-h3 bei OmniaKey, eine id für alle drei Aufgabentypen (Video-Dokumentation).
• Einstellungen: resolution (Pflicht) mit "768P" oder "2K", duration 4 bis 15 ganze Sekunden, aspect_ratio (Video-Dokumentation).
• Kosten: $0.08 pro Sekunde in 768P, $0.40 für 5 Sekunden, $0.13 in 2K, der Listenpreis von MiniMax (Preise, geprüft am 26. Oktober 2026); der Tarif von OmniaKey steht auf der Modellseite.
• Zeit und Ton: 35 bis 42 Sekunden pro Clip, jeweils mit Stereo-Ton; die Create-Referenz von V2 nennt keinen Schalter, um den Ton abzuschalten (Create-Referenz).

Gibt es eine offizielle Hailuo API?

Ja. MiniMax betreibt sie unter platform.minimax.io, und das aktuelle Modell dort ist MiniMax H3 mit der id MiniMax-H3 (Modellübersicht, geprüft am 26. Oktober 2026).

Die Ankündigung von MiniMax stellt H3 als die Generation nach Hailuo 01 und Hailuo 02 vor (Ankündigung). Die älteren Modelle sind weiterhin in der API, als MiniMax-Hailuo-2.3 und MiniMax-Hailuo-02 (V1-Referenz).

Der Name wechselt von Seite zu Seite. Die Dokumentation von MiniMax schreibt „MiniMax H3“, die Modellbeschreibung der API schreibt „Hailuo-03“ (Create-Referenz), und die App Hailuo AI, zu der die Ankündigung zum Ausprobieren führt, schreibt „Hailuo 3.0“ (App). „Hailuo 3“ ist kein offizieller Name.

Den Schlüssel legen Sie unter Account > API Keys an, abgerechnet wird nach Verbrauch (API-FAQ). Die Videopakete von MiniMax decken die älteren Modelle ab, nicht H3 (Preise).

MiniMax führt vier H3-Varianten (Create-Referenz):

In der eigenen API von MiniMax besteht ein Aufruf aus drei Schritten (Video-Guide):

• POST https://api.minimax.io/v2/video_generation gibt eine task_id zurück (Create-Referenz).
• GET /v2/query/video_generation/{task_id} abfragen, bis succeeded kommt, dann content.url herunterladen (Query-Referenz).
• Abfragbar sind nur Aufgaben der letzten 7 Tage, und wie lange die Download-URL gilt, veröffentlicht MiniMax nicht (Query-Referenz).

V1 (Hailuo 2.3 und 02) übergibt die Aufgaben-ID als Parameter ?task_id= statt als Teil des Pfads, deshalb halten Sie die beiden Abläufe getrennt (V1-Referenz).

OmniaKey verkauft den API-Zugang zu MiniMax H3, deshalb liefen diese Beispiele darüber. Der Ablauf ist derselbe: POST https://api.omniakey.com/v1/media/tasks mit einem Idempotency-Key-Header liefert 202 und eine id, danach fragen Sie GET /v1/media/tasks/{id} ab (Media-Übersicht). Derselbe Ablauf bewegt Grok Imagine Video in unserem Leitfaden zur Grok Imagine Video API. Alle Preise unten sind die Listenpreise von MiniMax.

Welche Parameter lassen sich einstellen?

• resolution ist Pflicht; 1080P und 4K scheitern mit 400 model_price_error (Video-Dokumentation), und V2 kennt kein 1080P für H3 (Create-Referenz). Alle drei Modi liefen in 768P, 2K haben wir nicht getestet.
• duration umfasst 4 bis 15 ganze Sekunden (Video-Dokumentation); MiniMax-H3-Max beginnt bei 5 und lehnt 4 ab (Create-Referenz).
• aspect_ratio nimmt adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 oder 21:9 (Video-Dokumentation). In der API von MiniMax braucht Text zu Video ein festes Seitenverhältnis, und Bild zu Video folgt der Form des Bildes (Create-Referenz). In unserem Lauf für Bild zu Video ließen wir das Seitenverhältnis weg, und der Clip behielt die Form des Standbilds, 1376×768.
• input.media[] nimmt first_frame und ein optionales last_frame für Bild zu Video oder reference_image, reference_video und reference_audio für Referenz zu Video. Die beiden Arten lassen sich nicht mischen, und eine Audio-Referenz braucht eine Bild- oder Video-Referenz daneben (Video-Dokumentation). Jeder Eintrag besteht aus type und url, entweder ein öffentlicher HTTPS-Link oder eine Data-URI. OmniaKey begrenzt die ganze Anfrage auf 1 MiB inklusive Base64 (Media-Übersicht), deshalb schickt das Skript JPEGs mit 1024 Pixeln.
• Der Prompt steht in input.prompt (Video-Dokumentation), bis zu 7,000 Zeichen (Video-Guide). Den gewünschten Ton beschreiben Sie dort ebenfalls.

Wie ruft man die Hailuo API aus Python auf?

Sie brauchen Python 3 und requests, mit dem Schlüssel in einer Umgebungsvariable.

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

Das einzige Argument ist t2v, i2v oder r2v; die Läufe mit Bild lesen bicycle.jpg oder robot.jpg aus demselben Ordner.

Hier ist das Skript, das wir ausgeführt haben, unverändert:

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",
    )

Die Ausgabe vom 27. Oktober 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

Jeder Lauf brauchte vom Start bis zur gespeicherten Datei 47 bis 60 Sekunden.

Behalten Sie die Aufgaben-ID. Eine langsame Aufgabe ist nicht gescheitert, fragen Sie also dieselbe ID erneut ab, statt neu einzureichen (Media-Übersicht). Die signierte Download-URL gilt etwa eine Stunde, der Aufgabeneintrag 24 Stunden; speichern Sie die Datei sofort oder fragen Sie erneut nach einer frischen URL. Der Download selbst braucht keinen API-Schlüssel.

Was die drei Modi zurückgaben

Die drei Clips stammen aus drei Aufgaben vom 26. Oktober 2026, mit genau den Request-Bodies aus dem Skript.

Jeder Clip war ein MP4, H.264, 24 fps, 5.17 Sekunden, mit Stereo-AAC-Audio bei 32 kHz; usage meldete output_seconds: 5.

Text zu Video: der Straßentrommler

Der Prompt ist DRUMMER im Skript.

Was wir sahen:

• Ein nasser Bürgersteig bei Nacht, rotes und blaues Neonlicht auf dem Boden, geparkte Autos und ein Trommler in schwarzer Kapuzenjacke, über umgedrehte blaue Eimer gebeugt. Die Kapuze verdeckt das Gesicht die ganze Zeit.
• Die Kamera fährt von einer weiten Ansicht auf die Hände, die bewegten Sticks und die Oberseiten der Eimer zu, während hinter ihm eine Person mit Regenschirm vorbeigeht.
• Die Buchstaben auf den Neonschildern sind keine echten Wörter. Die Trommelschläge werden zum Ende hin kräftiger, der Regen ist im Ton aber nicht zu erkennen.

Was zu ändern ist: Wenn Sie ein Gesicht brauchen, ergänzen Sie „hood down, face visible“; wenn der Regen zu hören sein soll, geben Sie ihm einen eigenen Tonsatz.

Bild zu Video: das erste Frame bleibt

Das erste Frame ist ein Standbild, das wir mit Nano Banana 2.1 erstellt haben; der Prompt ist BICYCLE und beschreibt nur die Bewegung.

Was wir sahen:

• Das erste Frame entspricht dem Standbild: dasselbe rote Fahrrad, die gelbe Putzwand, Fensterläden, Topfpflanzen und Kopfsteinpflaster.
• Die Kamera fährt heran, bis der Korb mit weißen Gänseblümchen das Bild füllt, und Fahrrad und Wand behalten die ganze Zeit ihre Form.
• In den geprüften Frames sahen wir keine Blütenblätter fallen. Der Ton ist eine langsame Klaviermelodie, obwohl der Prompt weder Ton noch Musik erwähnt.

Was zu ändern ist: Beschreiben Sie nur Bewegung und Ton, weil das Standbild das Aussehen schon festlegt, und erstellen Sie das Standbild in der Form, die der Clip haben soll.

Referenz zu Video: ein Bild hält die Figur

Die Referenz ist ein einzelnes Bild eines kleinen orangen Roboters, erstellt mit Nano Banana 2.1; der Prompt ist ROBOT.

Was wir sahen:

• Derselbe Roboter: oranger runder Körper, runde blaue Glasangen, eine kurze Antenne mit Kugel oben und eine runde Scheibe an der Kopfseite, nun auf einem sonnigen Balkon mit Töpfen voller Blumen und Kräuter.
• Er gießt aus einer roten Gießkanne, der Wasserstrahl ist etwa ab 1 Sekunde zu sehen, und die Kamera wandert leicht zur Seite.
• Der Ton ist laufendes und spritzendes Wasser, das kurz vor dem Strahl beginnt, ohne Musik.

Was zu ändern ist: Die Figur brauchte keine Korrektur. Damit sie über mehrere Clips gleich bleibt, nutzen Sie jedes Mal dasselbe Referenzbild.

Ton: beschreiben, oder H3 wählt ihn

Wenn der Prompt nichts zum Ton sagte, wählte H3 ihn: Wasser für den Roboter, was zum Gießen passt, und Klavier für das Fahrrad. Beschreiben Sie den Ton, den Sie brauchen, im Prompt. Die Create-Referenz von V2 nennt keinen Schalter, um den Ton abzuschalten (Create-Referenz), deshalb entfernen Sie die Spur für einen stummen Clip hinterher:

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

Das schreibt eine Kopie nur mit dem H.264-Video, weiterhin 5.17 Sekunden lang und ohne Neukodierung.

Welche Fehler treten auf?

Fehler kommen aus der Aufgaben-API von OmniaKey und, beim direkten Aufruf, von MiniMax.

• 400 missing_idempotency_key: Kein Idempotency-Key-Header. Header ergänzen.
• 409 idempotency_key_reused: Gleicher Schlüssel, neuer Body. Neuer Schlüssel pro Aufgabe.
• 400 model_price_error: 1080P oder 4K. 768P oder 2K verwenden.
• 400 invalid_request: Body oder Parameter fehlerhaft. Parameter prüfen.
• 403 model_not_allowed: Schlüssel hat dieses Modell nicht. Zugang des Schlüssels prüfen.
• 503 no_available_channel: Modell gerade nicht verfügbar. Später erneut versuchen.
• provider_submit_uncertain: Beim Absenden abgelehnt. input.prompt verwenden, Material prüfen.
• Aufgabe failed: Generierung fehlgeschlagen. error lesen.

Eine gescheiterte oder abgebrochene Aufgabe wird erstattet (Media-Übersicht). In der eigenen API von MiniMax (Fehlercodes, geprüft am 26. Oktober 2026):

• MiniMax schickt zu jedem Code den passenden HTTP-Status, etwa 401 zu 1004 und 400 zu 2013 (Create-Referenz).
• H3 erlaubt auf V2 300 Anfragen pro Minute und 30 gleichzeitig laufende Aufgaben (Ratenlimits).

Was kostet die Hailuo API?

MiniMax rechnet H3 pro Sekunde Ausgabevideo ab, je nach Variante und Auflösung (Preisseite, geprüft am 26. Oktober 2026):

Mit diesen Preisen kosten 5 Sekunden in 768P $0.40, 10 Sekunden in 2K $1.30 und 15 Sekunden in 2K $1.95.

• Die ersten 5 Eingabebilder pro Aufgabe sind kostenlos (2 bei Max), jedes weitere Bild kostet bei H3 $0.04, Audio-Eingabe ist kostenlos. Eingabevideo wird pro Sekunde berechnet, und bei Max kostet eine Eingabesekunde ($0.143 in 768P) mehr als eine Ausgabesekunde. Bei gleicher Variante und Auflösung kosten alle drei Aufgabentypen gleich viel.
• H3 gibt es nur nach Verbrauch, und die Videopakete von MiniMax decken es nicht ab. Die Sekundenwerte in den Plänen der App Hailuo AI sind App-Credits, keine API-Preise (App).
• Die China-Plattform von MiniMax hat eine eigene Preisliste in Yuan, deshalb rechnen Sie die eine nicht in die andere um (China-Preise, geprüft am 26. Oktober 2026).
• Bei OmniaKey wird eine Videoaufgabe beim Anlegen pro Ausgabesekunde berechnet, und eine gescheiterte oder abgebrochene Aufgabe wird erstattet (Media-Übersicht).

Der aktuelle Tarif von OmniaKey steht auf der Modellseite zu MiniMax H3; die Form der Anfrage in der Dokumentation der Video-API.

Häufige Fragen

Ist die Hailuo API kostenlos?

In der eigenen API von MiniMax nicht: Die Seiten zu Preisen, Schnellstart und FAQ zeigen keine kostenlose Testphase und kein Guthaben für H3 (geprüft am 26. Oktober 2026). Kostenlos sind nur die ersten 5 Eingabebilder pro Aufgabe und die Audio-Eingabe (Preise), und die Credits der App Hailuo AI gelten nicht als API-Guthaben.

Worin unterscheiden sich Hailuo 2.3 und MiniMax H3?

Hailuo 2.3 läuft auf V1: 6 oder 10 Sekunden, bis 1080P, pro Video abgerechnet, mit einem Listenpreis von MiniMax von $0.28 für 6 Sekunden in 768P (Preise, V1-Referenz). H3 läuft auf V2: 4 bis 15 Sekunden, 768P oder 2K, pro Sekunde abgerechnet, mit Stereo-Ton (Create-Referenz, Modellübersicht). MiniMax führt beide weiterhin (Modell-FAQ).

Was ist MiniMax H3 Max?

Es ist eine gemeinsame Veröffentlichung von MiniMax und fal.ai, von fal.ai auf H3 für mehr Tempo nachtrainiert (Video-Guide). Es erzeugt Clips in 480P oder 768P mit 5 bis 15 Sekunden, und extra.prompt_expansion_mode nimmt disabled, balanced (die Voreinstellung) oder quality (Create-Referenz). Ob es Referenzen annimmt, beschreiben die Seiten von MiniMax unterschiedlich: Video-Guide und Modell-FAQ nennen nur Text zu Video und Bild zu Video, Create-Referenz und Preisseite nennen auch Referenz zu Video.

Kann man MiniMax H3 selbst betreiben?

Ja, außerhalb einiger Regionen. Die Gewichte liegen auf Hugging Face (MiniMaxAI/MiniMax-H3) und GitHub (MiniMax-AI/MiniMax-H3) unter der MiniMax H3 Community License Agreement, einer eigenen Lizenz (Hugging Face, GitHub). In der am 26. August 2026 geprüften Fassung sind die USA, die EU, das Vereinigte Königreich und Südkorea ausgeschlossene Gebiete, die eine eigene Lizenz brauchen (Leitfaden zur lokalen Installation).

Änderungsprotokoll

27. Oktober 2026: erste Fassung, mit Clips vom 26. Oktober 2026.