Wie verwende ich die MiniMax H3 Max API? Video aus Text oder Bild generieren

MiniMax H3 Max ist auf HiAPI unter zwei Modellnamen verfügbar: Text-zu-Video minimax-h3-max/text-to-video und Bild-zu-Video minimax-h3-max/image-to-video. Erzeugt werden Videos von 0,92–15 Sekunden; 480P kostet $0,072 pro Sekunde, 768P $0,115 pro Sekunde und 1080P $0,229 pro Sekunde – abgerechnet nach den angeforderten Sekunden. Erzeuge zunächst mit dem folgenden Papierboot-Prompt einen 5-sekündigen Querformat-Clip; das Budget für 768P beträgt $0,575. Bei der API-Integration reichst du eine Aufgabe ein und rufst das Video anschließend über die zurückgegebene taskId ab.

MiniMax H3 Max ist jetzt auf HiAPI verfügbar – mit diesem Prompt generieren →. Der Prompt wird automatisch eingefügt; wähle anschließend manuell 5 Sekunden, 768P und 16:9.

Das erste Video: ein Papierboot nach dem Regen

After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.

mit diesem Prompt generieren →

Dieser Prompt trennt Bewegung und Kameraführung: Das Papierboot treibt mit dem Wasser, eine tiefe Kameraposition folgt ihm fließend, und der Ton wird durch fernes Vogelgezwitscher angedeutet. Wenn du das Papierboot durch dein eigenes Motiv ersetzt, behalte zunächst eine Bewegung und eine Kameraführung bei – so lässt sich leichter erkennen, was angepasst werden muss.

Online ausprobieren oder API-Integration – was wählen?

Wenn du zuerst das Ergebnis sehen möchtest, öffne die Modellseite für Text-zu-Video, kopiere den Prompt, wähle Dauer und Auflösung und reiche die Generierung ein. Wenn bereits ein Ausgangsbild vorhanden ist, wechsle zur Modellseite für Bild-zu-Video und lade das Startbild hoch. Für die Integration in eine Anwendung rufst du zuerst auf der API-Key-Seite einen Schlüssel ab, erstellst per Serveranfrage eine Aufgabe, speicherst die taskId und liest nach erfolgreichem Abschluss die Video-URL aus.

Die Auflösung sollte explizit angegeben werden: 5 Sekunden in 480P kosten $0,36, in 768P $0,575, in 1080P $1,145. Bestätige die Bewegung zunächst mit niedriger Auflösung und wähle die Stufe dann nach Lieferanforderung; das vollständige Budget findest du in der Preistabelle für H3 und H3 Max.

cURL: Aufgabe erstellen und Ergebnis abfragen

Nachdem du den API-Key als lokale Umgebungsvariable HIAPI_API_KEY gesetzt hast, führe diese Anfrage aus:

curl --fail-with-body --connect-timeout 10 --max-time 60 -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}'

Wenn der POST-Request das Timeout überschreitet, die Verbindung unterbrochen wird oder die Antwort das Erstellungsergebnis nicht bestätigt, ist der Einreichungsstatus unbekannt: Prüfe zuerst die Aufgabenhistorie und führe den POST nicht direkt erneut aus. Nachdem du bestätigt hast, dass die Antwort code=200 enthält, data ein Objekt ist und data.taskId nicht leer ist, speichere die ID und ersetze YOUR_TASK_ID in der Abfrage-URL:

curl --fail-with-body --connect-timeout 10 --max-time 60 "https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Für eine laufende Aufgabe fragst du weiterhin dieselbe ID ab. Wenn data.status success ist, lies die url des Videoeintrags aus data.output; bei fail prüfe die Fehlermeldung der Aufgabe; bei Eingabe- oder Authentifizierungsfehlern behebe zuerst das jeweilige Problem und frage bei vorhandener Aufgaben-ID weiterhin diese Aufgabe ab.

Python: einmal einreichen und auf dieselbe Aufgabe warten

Im Folgenden wird die Python-Standardbibliothek verwendet. Es wird nur einmal POST ausgeführt und die Antwort validiert; wenn das Einreichungsergebnis unbekannt ist, wird abgebrochen und auf die Aufgabenhistorie verwiesen. Bei vorübergehend fehlgeschlagenen Abfragen bleibt die Aufgaben-ID erhalten und GET wird fortgesetzt; 600 Sekunden sind die Wartezeitgrenze in diesem Beispiel.

import json
import os
import time
import urllib.error
import urllib.request

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer " + os.environ["HIAPI_API_KEY"],
    "Content-Type": "application/json",
}


def request(method, url, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data=data, headers=HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=30) as response:
        result = json.load(response)
    if not isinstance(result, dict) or result.get("code") != 200:
        raise ValueError(f"Unexpected API response: {result!r}")
    if not isinstance(result.get("data"), dict):
        raise ValueError("Missing data object")
    return result["data"]


payload = {
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}
try:
    created = request("POST", BASE, payload)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing taskId")
except (OSError, ValueError) as exc:
    raise SystemExit(
        f"Submission outcome is unconfirmed: {exc}. "
        "Check task history before another POST; do not blindly resubmit."
    )

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        task = request("GET", f"{BASE}/{task_id}")
    except urllib.error.HTTPError as exc:
        if exc.code in (400, 401, 403, 404):
            raise SystemExit(
                f"Query rejected ({exc.code}). Correct URL/auth, then GET existing task {task_id}."
            )
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    except (OSError, ValueError) as exc:
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    status = task.get("status")
    if status not in ("queued", "handling", "archiving", "success", "fail"):
        raise RuntimeError(f"Unexpected task status {status!r}; keep task ID {task_id}")
    if status == "success":
        output = task.get("output")
        if not isinstance(output, list):
            raise RuntimeError(f"Invalid output; keep task ID {task_id}")
        videos = [item["url"] for item in output
                  if isinstance(item, dict) and item.get("type") == "video"
                  and isinstance(item.get("url"), str) and item["url"]]
        if not videos:
            raise RuntimeError(f"No video URL; keep task ID {task_id}")
        print(videos[0])
        break
    if status == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task!r}")
    time.sleep(5)
else:
    raise TimeoutError(f"Keep querying existing task {task_id}; do not POST again")

Start- oder Endbild mit Bildern steuern

Wenn das Video mit deinem eigenen Produktbild beginnen soll, ändere den Modellnamen zu minimax-h3-max/image-to-video und füge first_frame_image in input hinzu; um das Ende festzulegen, füge last_frame_image hinzu. Du kannst nur das Endbild übergeben oder gleichzeitig Start- und Endbild; Bild-zu-Video hat kein Feld aspect_ratio – das Seitenverhältnis folgt dem Bild.

Feld	Verwendung
prompt	Erforderlich, maximal 50000 Zeichen; beschreibt Bewegung, Kameraführung und Ton
duration	0,92–15 Sekunden, Dezimalwerte möglich, Standard 5 Sekunden
resolution	480P, 768P oder 1080P, Standard 768P
aspect_ratio	Nur bei Text-zu-Video: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, Standard 16:9
first_frame_image	Bild-zu-Video: öffentliche Bild-URL des Startbilds
last_frame_image	Bild-zu-Video: öffentliche Bild-URL des Endbilds
target_audio_url	Optional; ersetzt die Tonspur durch eigenes Audio, mindestens 2 Sekunden
prompt_expansion_mode	Optional, disabled / balanced (Standard) / quality

Im Folgenden siehst du den vollständigen Request-Body für Start- und Endbild; die Bild-URLs sind Platzhalter für deine eigenen öffentlich erreichbaren Adressen. Die Bilder legen die Komposition zu Beginn und am Ende fest:

{
  "model": "minimax-h3-max/image-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "first_frame_image": "https://your-domain.com/images/paperboat-first.jpg",
    "last_frame_image": "https://your-domain.com/images/paperboat-last.jpg"
  }
}

Wenn du nur das Endbild steuern möchtest, kannst du first_frame_image entfernen und last_frame_image beibehalten. Schreibe nur die Kamerabewegung in den Prompt; die Bilder legen Motiv und Ausgangskomposition fest. Für mehrere Kameraeinstellungen kannst du jeden Wechsel im Prompt klar beschreiben; die Request-Felder bleiben gemäß dieser Tabelle – füge kein camera_angle, mode oder watermark hinzu.

Für einen vertikalen Clip schreibst du bei Text-zu-Video direkt "aspect_ratio": "9:16"; bei Bild-zu-Video verwendest du ein vertikales Startbild – das Seitenverhältnis folgt dem Bild.

Callback bei Anwendungsintegration auf oberster Request-Ebene platzieren

Füge im Erstellungs-Request auf oberster Ebene einen optionalen Callback hinzu, parallel zu model und input:

{
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

Füge dies in den vollständigen Request ein. Der Empfänger dedupliziert nach taskId, behandelt Erfolg und Fehler getrennt und ergänzt verpasste Benachrichtigungen durch Aufgabenabfragen. Reiche nach Erhalt der Aufgaben-ID nicht erneut ein; lies bei HTTP-Fehlern zuerst den Antwortinhalt und unterscheide zwischen Authentifizierungs- und Parameterproblemen.

Diese vier Punkte nach der Integration prüfen

1. Speichere eine nicht leere data.taskId und verwende sie auch nach Abfragefehlern weiter.
2. Bestätige, dass der Endstatus success oder fail ist, und behandle die Wartezeitgrenze nicht als Modelllaufzeit.
3. Suche in data.output der erfolgreichen Aufgabe nach type=video, um die Video-URL zu finden.
4. Lade das Ergebnis herunter und prüfe tatsächliche Abmessungen, Dauer und Bildinhalt gegen die Lieferanforderungen.

Häufige Fragen

Kann H3 Max Referenzvideos oder -audio verwenden? H3 Max ersetzt die Tonspur mit target_audio_url und akzeptiert keine Referenzvideos; wenn du multimodale Referenzen aus Bild, Video und Audio benötigst, wähle MiniMax H3.

Ist Max teurer als H3? H3 2K kostet $0,1189 pro Sekunde, Max 768P $0,115 pro Sekunde und 1080P $0,229 pro Sekunde. Wähle das Modell zuerst nach benötigter Auflösung und Referenzmaterial und berechne dann das Budget anhand der Dauer.

Wie beginne ich mit einem vertikalen Clip? Bei Text-zu-Video schreibst du "aspect_ratio": "9:16"; bei Bild-zu-Video bereitest du ein vertikales Startbild vor – das Seitenverhältnis folgt dem Bild.

Kopiere den Papierboot-Prompt, mit diesem Prompt generieren →, und erstelle zuerst einen 5-sekündigen Clip. Weitere Formulierungen für Bewegung und Kameraführung findest du unter 4 echte Videos mit vollständigen Prompts; die vollständigen Felder findest du in der Parameterdokumentation für Text-zu-Video und der Parameterdokumentation für Bild-zu-Video.