MiniMax Hailuo 2.3 API-Integration: komplexe menschliche Bewegung in KI-Videos erzeugen
Zielmodell:
MiniMax-Hailuo-2.3
Inferenz-Endpunkt:https://api.toapis.com/v1/videos/generations
Verwandt: MiniMax H3 API-Leitfaden · Kamerabewegungs-Prompts für H3 · Automatisierte R2V-Pipeline
1. Kurzüberblick und Leistungsübersicht
- Aufgabe: Text-zu-Video- oder First-Frame-Image-to-Video-Jobs für Charakter- und Bewegungsclips an den Generierungs-Endpunkt von ToAPIs senden.
- Vertrag:
MiniMax-Hailuo-2.3akzeptiert ganzzahlige Dauern von 6 oder 10 Sekunden und Auflösungen768Poder1080P.1080Punterstützt nur 6 Sekunden. Die aktuelle API-Referenz begrenzt den Prompt auf 2.000 Zeichen. - IDs: Verwenden Sie die Katalogzeichenkette
MiniMax-Hailuo-2.3(Text-zu-Video und Image-to-Video).MiniMax-Hailuo-2.3-Fastist nur Image-to-Video und verlangt eine Startbild-URL. Keine der beiden IDs ist mitminimax-h3austauschbar. - Kamerasprache: Die ToAPIs Referenz zu Hailuo 2.3 dokumentiert Direktiven in eckigen Klammern wie
[Push in]und[Pan left, Pedestal up]. Behandeln Sie die folgende Tabelle als aktuelles dokumentiertes Vokabular und prüfen Sie es anhand der Live-Dokumentation, bevor Sie eine Shot-Grammatik fest codieren. - Protokoll: REST mit Bearer. Speichern Sie die Task-
idaus der Übergabeantwort und fragen SieGET /v1/videos/generations/{task_id}(oderGET /v1/tasks/{task_id}) mit einer begrenzten Frist ab. Eine clientseitige Zeitüberschreitung beweist nicht, dass der Upstream-Task fehlgeschlagen ist.
2. Prompt-Muster für menschliche Bewegung
Der öffentliche ToAPIs Katalog beschreibt MiniMax Hailuo 2.3 als Videomodell für Charakterbewegung, Ausdruck und Stil in ausdrucksstarken Geschichten und Charakterclips. Das ist Produktpositionierung und kein unabhängiger Benchmark für „keine Gliedmaßen-Verzerrung“. Schreiben Sie für die Produktion Prompts, die ein Motiv und eine Hauptaktion in klarer mechanischer Sprache beschreiben, und prüfen Sie dann den Take.
Ein brauchbarer Bewegungs-Prompt benennt die Körpermechanik, bevor Stil hinzukommt: wer sich bewegt, welches Glied führt, wie sich das Gewicht verlagert und wie die Aktion beginnt und endet. Halten Sie diesen Kern stabil, wenn Sie Dauer oder Auflösung im A/B-Test vergleichen; sonst kann eine geänderte Formulierung einen anderen Take erklären.
Die ToAPIs Referenz zur Hailuo 2.3 API dokumentiert die folgenden Kameradirektiven. Sie stehen in der Prompt-Zeichenkette, nicht in einem separaten Request-Feld. Der Frontend-Request-Vertrag prüft prompt weiterhin als Text. Kombinieren Sie höchstens drei Direktiven in einer Klammer für gleichzeitige Bewegung oder ordnen Sie sie im Satz für aufeinanderfolgende Bewegungen.
| Kategorie | Dokumentierte Direktiven |
|---|---|
| Pan | [Pan left], [Pan right] |
| Tilt | [Tilt up], [Tilt down] |
| Push / Pull | [Push in], [Pull out] |
| Pedestal | [Pedestal up], [Pedestal down] |
| Truck | [Truck left], [Truck right] |
| Zoom | [Zoom in], [Zoom out] |
| Sonstiges | [Shake], [Tracking shot], [Static shot] |

Abbildung 1: Behandeln Sie eine statische Pose als Eingabe für das Startbild, beschreiben Sie die folgende Aktion im Prompt und senden Sie eine einzelne Generierungsanfrage über das ToAPIs Gateway.
Eine kompakte Vorlage, die testbar bleibt:
SUBJECT and PRIMARY ACTION (lead limb, weight shift, follow-through), ENVIRONMENT, [CAMERA], STYLE NOTES
Beispiel: A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs.
Senden Sie für Image-to-Video eine öffentlich erreichbare Startbild-URL in image_urls. Das Bild ist der Startframe; der Prompt beschreibt die folgende Bewegung. Aktuell dokumentierte Bildlimits sind JPG, JPEG, PNG oder WebP; unter 20 MB; kurze Seite größer als 300 px; Seitenverhältnis zwischen 2:5 und 5:2. Setzen Sie kein Base64 in image_urls – laden Sie zuerst eine lokale Datei hoch.
MiniMax-Hailuo-2.3-Fast akzeptiert kein Text-zu-Video: Eine Startbild-URL ist erforderlich. Hailuo 2.3 dokumentiert kein Feld für ein Endbild; die Start-zu-End-Interpolation gehört zu MiniMax-Hailuo-02, nicht zu dieser ID. Kopieren Sie keine H3-Felder wie ratio oder reference_videos in eine Hailuo 2.3 Anfrage.
Optionslabels im Playground können 768p / 1080p in Kleinschreibung zeigen. Aktuelle API-Beispiele verwenden 768P und 1080P. Bestätigen Sie den Wert, den Ihr Konto akzeptiert, bevor Sie einen Batch automatisieren. Dieselbe Kameraformulierung lässt sich wiederverwenden, wenn Sie eine Einstellung zu MiniMax H3 verschieben, aber die Verträge für Dauer, Auflösung und Medienmodus sind anders – wechseln Sie die ID erst, nachdem Sie diesen Leitfaden erneut gelesen haben.
3. Produktionsumsetzung: cURL und Python
Schritt 1: Versand per cURL
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-Hailuo-2.3",
"prompt": "A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs",
"duration": 6,
"resolution": "768P"
}'
Schritt 2: Python-Hilfe und Poller
Die offizielle Dokumentation nennt derzeit den öffentlichen Ursprung https://toapis.com (und https://toapis.cn für Festlandchina). Andere ToAPIs Guides dieser Reihe verwenden https://api.toapis.com. Wählen Sie eine Basis-URL und bleiben Sie konsistent. Der Ausschnitt folgt dem dokumentierten Task-Status-Pfad und den Zuständen completed / failed; bestätigen Sie id, result.data[0].url und die Antwortstruktur anhand der API-Referenz Ihres Kontos, bevor Sie ausliefern.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_motion_clip(
prompt: str,
duration: int = 6,
resolution: str = "768P",
image_url: str | None = None,
model: str = "MiniMax-Hailuo-2.3",
) -> str:
if resolution == "1080P" and duration != 6:
raise ValueError("1080P currently supports a 6-second duration only")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"metadata": {"prompt_optimizer": True, "aigc_watermark": False},
}
if image_url:
payload["image_urls"] = [image_url]
elif model == "MiniMax-Hailuo-2.3-Fast":
raise ValueError("MiniMax-Hailuo-2.3-Fast requires a first-frame image_urls value")
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 300) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 5.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 30))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 10.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
prompt = (
"A contemporary dancer in a black practice leotard plants the left foot, "
"then uncoils a slow 360-degree turn with the right arm leading and the "
"torso stacked over the standing leg, warehouse skylight, [Tracking shot], "
"photorealistic, no morphing limbs"
)
task_id = dispatch_motion_clip(prompt)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Speichern Sie die Version der Prompt-Vorlage beim Task-Datensatz, damit Sie einen Modellwechsel von einer Formulierungsänderung unterscheiden können. Wenn Sie einen Job mit Startbild benötigen, übergeben Sie image_url= an dispatch_motion_clip. Für die Fast-SKU ist dieses Argument erforderlich.
Die Dauer von Hailuo 2.3 Basis ist 6 oder 10 Sekunden. Senden Sie 1080P nicht mit duration: 10. Wenn Sie durchgehende Clips von 4–15 Sekunden, Referenzmaterial oder Eingaben für ein Endbild benötigen, ist das ein anderer Vertrag – siehe den H3 API-Leitfaden und das R2V-Pipeline-Tutorial.
4. Fehlerbehandlung und Statusmatrix
Die folgenden Kategorien sind Ausgangspunkte für die Diagnose und keine Garantie für exakte ToAPIs Fehlercodes. Eine erfolgreiche HTTP-Abfrage erfordert weiterhin, den Task-status zu lesen.
| HTTP-Status | Häufige Kategorie | Empfohlene Maßnahme |
|---|---|---|
400 | Ungültiges Feld, nicht unterstützte Kombination oder Konflikt im Medienmodus | Prüfen Sie die genaue Modell-ID, ob die Dauer 6 oder 10 ist, ob 1080P nur mit 6 Sekunden kombiniert wird und ob Fast-Jobs image_urls enthalten. Senden Sie bei Hailuo 2.3 kein Feld für ein Endbild |
401 | Fehlender oder ungültiger API-Schlüssel | Rotieren Sie den Schlüssel im ToAPIs Dashboard und prüfen Sie den Authorization-Header |
429 | Rate- oder Parallelitätslimit | Beachten Sie Retry-After, wenn vorhanden; weichen Sie mit Jitter zurück; wiederholen Sie nur, wenn es sicher ist |
5xx oder Netzwerk-Zeitüberschreitung | Vorübergehendes Gateway- oder Upstream-Problem | Prüfen Sie den Task-Status vor dem erneuten Senden und nutzen Sie eine begrenzte Wiederholungsstrategie |
5. Preise und FinOps-ROI
- Verwenden Sie keine Stückpreise aus Planungsentwürfen. Preise pro Sekunde oder pro Video, Abrechnungseinheiten und der Umgang mit fehlgeschlagenen Tasks variieren je nach Modell, Auflösung, Dauer, Route und Konto. Offizielle Anbieter-Referenzzeilen auf der ToAPIs Preisseite dienen nur der Anzeige und können von der Abrechnung Ihres Kontos abweichen. Lesen Sie den aktuellen Katalog und das Angebot Ihres Kontos, bevor Sie eine Shot-Liste kalkulieren.
- Fast ist eine andere SKU, kein kostenloser Geschwindigkeitsschalter auf derselben ID.
MiniMax-Hailuo-2.3-Fastist dokumentiert als ausschließlich Image-to-Video. Bestätigen Sie den aktuellen Kontopreis separat. - Steuern Sie die Kosten in der Prompt-Ebene: Entwerfen Sie in
768Pund 6 Sekunden, halten Sie eine versionierte Vorlage, ändern Sie jeweils nur eine Variable und senden Sie nach einer clientseitigen Zeitüberschreitung erst erneut, wenn Sie den Task-Status geprüft haben. - Offizielle Anbieterverträge enthalten oft Jahresverpflichtungen, Sitzkontingente und Vorauszahlungsuntergrenzen. Die ToAPIs Abrechnung erfolgt typischerweise als Bezahlung nach Verbrauch – bestätigen Sie die aktiven Bedingungen Ihres Kontos.
6. Häufig gestellte Fragen
Siehe den FAQ-Block im Frontmatter. Kurzfassung: Die Request-Modellzeichenkette ist MiniMax-Hailuo-2.3, kein mit Bindestrichen versehener Slug und keine H3-ID; 1080P ist auf 6 Sekunden begrenzt; Fast erfordert eine Startbild-URL und unterstützt kein Text-zu-Video; dokumentierte Kameradirektiven stehen im Prompt und nicht in separaten Feldern; Hailuo 2.3 hat keine Eingabe für ein Endbild.
7. Aktionscheckliste
- Erstellen Sie einen Schlüssel im ToAPIs Developer Portal.
- Testen Sie den cURL-Ausschnitt kurz mit
MiniMax-Hailuo-2.3,resolution: "768P"und einer Dauer von 6 Sekunden. - Bestätigen Sie, ob Ihr Konto
768Poder768perwartet, und fragen SieGET /v1/videos/generations/{id}mit einer begrenzten Frist ab. - Nächster Schritt: der H3-Leitfaden zu Kamerabewegungen, wenn Sie eine andere Dauer oder einen anderen Medienvertrag benötigen, und der Hailuo 2.3 Modell-Leitfaden für den Live-Status im Katalog.







