MiniMax H3 API-Leitfaden: Text-zu-Video und Referenzeingaben
Anfragen an MiniMax H3 werden leicht falsch konfiguriert, wenn ein Client alle Modellvarianten als austauschbar behandelt. Die gewählte Modell-ID beeinflusst die Prüfung von Dauer und Auflösung, während der Medienmodus entscheidet, welche Bild-, Video- und Audiofelder zusammen gesendet werden dürfen.
Dieser Leitfaden beschreibt den Request-Vertrag, wie er am 22. Oktober 2026 im ToAPIs Frontend abgebildet ist. Er ist ein Integrationsleitfaden und kein Bericht über die Leistung des Upstream-Anbieters oder über die aktuellen Preise Ihres Kontos. Prüfen Sie, ob Ihr Konto Zugriff auf das gewünschte Modell hat, bevor Sie Produktionsjobs senden.
Schnellstart
Der Generierungs-Endpunkt in den API-Beispielen von ToAPIs ist POST /v1/videos/generations. Authentifizieren Sie sich mit einem ToAPIs API-Schlüssel und übergeben Sie einen Prompt, eine freigeschaltete Modell-ID, die Dauer und das Seitenverhältnis. Zum Beispiel:
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
"duration": 5,
"ratio": "16:9"
}'
Behandeln Sie die Antwort als Übergabe eines asynchronen Tasks. Lesen Sie die Task-Kennung aus der Antwort Ihrer Konto-API und fragen Sie den Status über den dokumentierten Status-Endpunkt ab. Gehen Sie nicht von einem festen Antwortformat aus, solange es nicht in der API-Referenz Ihres Kontos spezifiziert ist.
import os
import time
import requests
BASE_URL = "https://api.toapis.com/v1"
API_KEY = os.environ["TOAPIS_API_KEY"]
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.post(
f"{BASE_URL}/videos/generations",
headers=headers,
json={
"model": "minimax-h3",
"prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
"duration": 5,
"ratio": "16:9",
},
timeout=30,
)
response.raise_for_status()
submission = response.json()
print("Submission response:", submission)
Das Beispiel gibt die Antwort bewusst aus, statt anzunehmen, wo eine Task-ID oder eine Video-URL erscheint. Passen Sie den Auslese- und Abfragecode an das für Ihr Konto dokumentierte Antwortschema an. So vermeiden Sie, ein geändertes Format stillschweigend als erfolgreichen Task zu behandeln.
Die exakte Modell-ID wählen
Das Frontend erkennt minimax-h3 und minimax-h3-global als IDs der Basisfamilie sowie Modell-IDs, die minimax-h3-max enthalten. Die im Produkt verwendete Turbo-Modell-ID lautet beispielsweise minimax-h3-max-turbo. Verwenden Sie die kanonische Modellkennung aus dem verfügbaren Modellkatalog und erfinden Sie keine Aliase und kürzen Sie die ID nicht.
Derzeit gelten im Frontend diese Fähigkeitsgrenzen:
| Modellfamilie / ID | Vom Frontend akzeptierte Dauer | Im Frontend abgebildete Auflösungen |
|---|---|---|
minimax-h3 und minimax-h3-global | 4–15 Sekunden, ganzzahlig | 2K, 768p |
minimax-h3-max-turbo und andere Max-Varianten | 5–15 Sekunden, ganzzahlig | 480P, 768P |
Kanonisches minimax-h3-max | 5–15 Sekunden, ganzzahlig | Max-Auswahl plus 1080P |
Das sind Validierungsgrenzen des Frontends, keine Garantie dafür, dass jedes Konto oder jede Upstream-Route dieselbe Verfügbarkeit hat. Insbesondere ist die zusätzliche 1080P-Option im aktuellen Client ausschließlich an die exakte kanonische ID minimax-h3-max gebunden. Leiten Sie daraus nicht ab, dass Turbo, ein -global-Alias oder jedes H3-Modell 1080P unterstützt.
Einen Medienmodus wählen
Das H3-Formular unterstützt zwei sich gegenseitig ausschließende Workflows:
- Frame-Modus: Übergeben Sie höchstens ein
first_frame_imageund höchstens einlast_frame_image. Der Client wählt ein adaptives Seitenverhältnis, wenn Frame-Eingaben vorhanden sind. - Referenzmodus: Übergeben Sie Referenzbilder, -videos und/oder -audios ohne Eingaben für Start- oder Endbild. Der Client verwendet das gewählte Seitenverhältnis für diese Referenzen.
Beispiel für eine Anfrage mit Startbild:
{
"model": "minimax-h3",
"prompt": "The subject turns toward the camera as the camera gently moves forward",
"duration": 5,
"ratio": "16:9",
"first_frame_image": ["https://example.com/starting-frame.jpg"]
}
Beispiel für eine Anfrage mit Referenzmaterial:
{
"model": "minimax-h3",
"prompt": "Use the supplied references to guide the scene and motion",
"duration": 5,
"ratio": "16:9",
"media_mode": "reference",
"reference_images": ["https://example.com/character-reference.jpg"],
"reference_videos": ["https://example.com/motion-reference.mp4"]
}
Das genaue Werteformat für hochgeladene Medien hängt vom Upload-Ablauf des Gateways ab. Diese Beispiele zeigen die Request-Felder und behaupten nicht, dass beliebige öffentliche URLs von jeder Route akzeptiert werden. Verwenden Sie URLs oder Asset-Kennungen, die der dokumentierte Upload-Ablauf zurückgibt.
Das Frontend erzwingt diese Referenzgrenzen:
- Bis zu 9 Referenzbilder.
- Bis zu 3 Referenzvideos.
- Bis zu 3 Referenzaudios.
- Insgesamt höchstens 12 Referenz-Assets.
- Jedes Referenzvideo muss 2–15 Sekunden lang sein, und die Gesamtdauer aller übergebenen Referenzen darf 15 Sekunden nicht überschreiten.
- Audioreferenzen erfordern mindestens eine visuelle Referenz.
- Turbo-Anfragen dürfen kein Referenzmaterial enthalten.
Beachten Sie diese Einschränkungen vor dem Senden. Eine Anfrage, die Eingabemodi mischt, eine Höchstzahl überschreitet oder den erforderlichen visuellen Kontext auslässt, wird lokal vom Frontend abgelehnt und nicht als gültige H3-Generierungsanfrage gesendet.
Prompt- und Generierungsoptionen
Der Prompt ist erforderlich und im aktuellen Frontend auf 7.000 Unicode-Zeichen begrenzt. Beschreiben Sie Szene, Motiv, Bewegung und visuelle Absicht in einfacher Sprache. Behandeln Sie Kamera-Tags in eckigen Klammern und andere Sondersyntax als normalen Prompt-Text, sofern die Upstream-Dokumentation des Modells sie nicht ausdrücklich definiert. Die im Frontend-Vertrag verfügbaren Hinweise belegen nicht, dass Zeichenketten wie [Pan Left] native H3-Befehle sind.
Der Request-Builder übergibt unterstützte optionale Steuerfelder wie prompt_optimizer, watermark und seed entsprechend der gewählten Modellroute. Gehen Sie nicht davon aus, dass optionale Felder von jedem Upstream-Kanal identisch akzeptiert werden. Wenn Sie sie in Ihrer eigenen Oberfläche anbieten, prüfen Sie sie gegen den modellspezifischen Katalog und entfernen Sie veraltete Felder, sobald Nutzer die Variante wechseln.
Beim Seitenverhältnis akzeptiert das Frontend adaptive, 21:9, 16:9, 4:3, 1:1, 3:4 und 9:16. Frame-Eingaben erzwingen adaptive. Bei Text-zu-Video wird eine adaptive Auswahl auf 16:9 normalisiert; der Referenzmodus behält das angeforderte unterstützte Seitenverhältnis bei.
Prompts schreiben, die testbar bleiben
Prompt-Erstellung ist kein API-Parameter, beeinflusst aber, wie nützlich eine technische Integration für die nutzende Person ist. Bitten Sie Nutzer, eine Szene und eine Hauptaktion zu beschreiben, bevor Kameraanweisung, Licht oder Stil hinzukommen. Ein kompakter Prompt kann Motiv, Aktion, Umgebung und Kamerabewegung in dieser Reihenfolge angeben. Halten Sie diese Bausteine bei einem Modellvergleich stabil; sonst kann eine geänderte Formulierung ein anderes Ergebnis erklären.
Versprechen Sie nicht, dass eine bestimmte Formulierung eine Kamerabewegung, Identitätstreue, Bildrate oder einen visuellen Stil garantiert. Der Frontend-Vertrag prüft den Prompt als Text und wendet ein Zeichenlimit an. Er definiert keine standardisierte Befehlsgrammatik für Kamera-Tags. Wenn Ihre Anwendung Prompt-Voreinstellungen anbietet, kennzeichnen Sie diese als Prompt-Hilfen und nicht als garantierte Modellsteuerung, sofern die Upstream-Dokumentation das Verhalten nicht bestätigt.
Speichern Sie bei wiederholten Generierungsworkflows die Version der Prompt-Vorlage zusammen mit dem Task-Datensatz. So lässt sich ein Modellwechsel von einer Prompt-Änderung unterscheiden, wenn Nutzer unterschiedliche Ergebnisse melden. Betten Sie keine API-Schlüssel, privaten Kennungen oder personenbezogenen Daten in Prompts ein. Prüfen Sie den Prompt-Inhalt gegen die Inhalts- und Datenschutzrichtlinien Ihres Produkts, bevor Sie unbeaufsichtigte Batch-Übermittlung erlauben.
Seitenverhältnis und Auflösung bewusst normalisieren
Seitenverhältnis und Auflösung beantworten unterschiedliche Fragen: Das Seitenverhältnis beschreibt die Form der Ausgabe, die Auflösung wählt eine von der Modellroute unterstützte Ausgabegröße. Ein akzeptiertes Seitenverhältnis bedeutet nicht, dass jede Auflösung damit kombiniert werden kann. Behalten Sie beide Felder in der Oberfläche und prüfen Sie sie gegen das aktuell gewählte Modell.
Wenn Nutzer den Modus für das Startbild oder für Start- und Endbild wählen, erzwingt das Frontend ein adaptives Seitenverhältnis, damit die Eingabebilder die Form der Arbeitsfläche vorgeben. Zeigen Sie kein widersprüchliches eigenes Seitenverhältnis an, als würde es berücksichtigt. Im Text-zu-Video-Modus löst sich die adaptive Auswahl im aktuellen Builder in das Standardverhalten 16:9 auf. Wenn Sie diese Normalisierung sichtbar machen, zeigen Sie den tatsächlich gesendeten Wert in einem Prüfschritt, damit Nutzer verstehen, was das Gateway erhält.
Auch die Auflösungsbezeichnungen unterscheiden sich in der Groß- und Kleinschreibung zwischen Varianten (768p gegenüber 768P). Normalisieren Sie sie nur, wenn der API-Vertrag des gewählten Modells das ausdrücklich erlaubt. Vermeiden Sie globale Umwandlungen von Modellwerten, weil ein Wert, den eine Route akzeptiert, von einer anderen abgelehnt werden kann.
Statusabfrage und Fehler
Die Videogenerierung ist asynchron. Speichern Sie nach dem Senden die Task-Kennung und fragen Sie den für Ihr API-Konto dokumentierten Status-Endpunkt ab. Nutzen Sie begrenztes exponentielles Backoff mit Jitter statt einer engen Schleife, setzen Sie eine Gesamtfrist und behandeln Sie einen endgültigen Fehler getrennt von einer Zeitüberschreitung. Eine Zeitüberschreitung beweist nicht, dass der Upstream-Task fehlgeschlagen ist; prüfen Sie den Task-Status, bevor Sie eine kostenpflichtige Generierung wiederholen.
Ihr Client sollte mindestens:
raise_for_status()oder ein Äquivalent auf HTTP-Antworten aufrufen.- Die Antwort gemäß dem veröffentlichten API-Schema auslesen.
- Die Abfrage bei einem dokumentierten endgültigen Erfolgs- oder Fehlerzustand beenden.
- Anzahl der Wiederholungen und Gesamtzeit begrenzen.
- Keine doppelte Generierung nur deshalb senden, weil eine clientseitige Anfrage in eine Zeitüberschreitung lief.
- Eine Request- oder Task-Kennung protokollieren, aber niemals den API-Schlüssel oder private Medien-URLs.
Die folgenden allgemeinen Fehlerkategorien sind Ausgangspunkte für die Diagnose und keine Garantie für exakte ToAPIs Fehlercodes:
| HTTP-Status | Häufige Kategorie | Empfohlene Maßnahme |
|---|---|---|
400 | Ungültiges Feld, nicht unterstützter Wert oder Konflikt im Medienmodus | Prüfen Sie Modell-ID, Dauer, Auflösung, Seitenverhältnis und Eingabezahlen. |
401 | Fehlender oder ungültiger API-Schlüssel | Prüfen Sie den Schlüssel in Ihrem Secret Manager und in den Request-Headern. |
429 | Rate- oder Parallelitätslimit | Weichen Sie mit Jitter zurück und 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. |
Preise und Servicegarantien
Preise, Verfügbarkeit, Erstattungsverhalten und Service Level Agreements können je nach Modell, Route und Konto variieren. Dieser Leitfaden nennt bewusst keinen Preis pro Sekunde und behauptet kein Verfügbarkeits-SLA. Prüfen Sie den aktuellen ToAPIs Modellkatalog und die Preise Ihres Kontos, bevor Sie Projektkosten schätzen. Verwenden Sie einen Preis aus einem Planungsentwurf nicht als Produktionsangebot.
Ein sichererer Workflow für den Request-Aufbau
Halten Sie Modellauswahl und Validierung an einer Stelle Ihrer Anwendung. Wenn Nutzer das Modell wechseln, bauen Sie die erlaubten Optionen neu auf, statt alle Felder der vorherigen Auswahl in die nächste Anfrage zu übernehmen. Das ist beim Wechsel von H3 Basis zu Max oder Turbo wichtig: Eine veraltete Auflösung, Referenzmedienliste oder Dauer kann für ein Modell gültig und für ein anderes ungültig sein.
Eine zuverlässige clientseitige Reihenfolge sieht so aus:
- Lesen Sie die aktuell gewählte Modell-ID aus dem Modellkatalog.
- Laden Sie die Dauer- und Auflösungsoptionen dieses Modells.
- Bitten Sie Nutzer, entweder den Frame-Modus oder den Referenzmodus zu wählen.
- Prüfen Sie Feldanzahlen und Kompatibilität, bevor Medien hochgeladen werden.
- Laden Sie die gewählten Medien über den dokumentierten Asset-Endpunkt hoch.
- Bauen Sie ein neues Request-Objekt aus den validierten Werten.
- Senden Sie einmal, speichern Sie die zurückgegebene Task-Kennung und zeigen Sie den Task-Status an.
Vermeiden Sie es, ein altes Request-Objekt direkt zu verändern. Ein neues Objekt macht es unwahrscheinlicher, dass ein Feld wie reference_videos nach einem Modellwechsel in eine Turbo-Anfrage gelangt. Der ToAPIs Frontend-Vertrag macht den Modus außerdem explizit: media_mode kann frame oder reference sein, und gemischte Eingaben werden abgelehnt.
Spiegeln Sie bei einer eigenen Integration diese Prüfungen vor dem Netzwerkaufruf:
def validate_h3_request(model, duration, resolution, frame_images, refs):
is_max_family = "minimax-h3-max" in model
is_turbo = "turbo" in model
min_duration = 5 if is_max_family else 4
if not isinstance(duration, int) or not min_duration <= duration <= 15:
raise ValueError("Duration is outside this model's supported range")
if len(frame_images) > 2:
raise ValueError("Use at most one first frame and one last frame")
if frame_images and refs:
raise ValueError("Frame inputs and reference media are separate modes")
if is_turbo and refs:
raise ValueError("This Turbo route does not accept reference media")
if len(refs.get("images", [])) > 9:
raise ValueError("Too many reference images")
if len(refs.get("videos", [])) > 3:
raise ValueError("Too many reference videos")
Das ist eine illustrative clientseitige Absicherung und kein Ersatz für die Servervalidierung. Produktionscode sollte zusätzlich jeden Medientyp prüfen, die Gesamtzahl der Referenzen und die Videodauer berechnen, die modellspezifische Auflösungsliste anwenden und die tatsächlichen Kennungen aus dem Upload-Ablauf verwenden.
Hinweise zu Upload und Datenschutz
Behandeln Sie Referenzmaterial als Nutzerdaten. Laden Sie nur Dateien hoch, für die Nutzer eine Berechtigung haben, und stellen Sie sicher, dass Ihre Aufbewahrungs- und Zugriffsregeln Quellbilder, Audio und Video abdecken. Veröffentlichen Sie private Quellmedien nicht in öffentlichen URLs, nur um eine Demo zu vereinfachen. Wenn die API eine temporäre Asset-URL zurückgibt, vermeiden Sie es, diese in Analysetools oder langlebige Logs zu schreiben.
Prüfen Sie Dateien vor dem Upload: Lehnen Sie nicht unterstützte Erweiterungen und MIME-Typen ab, erzwingen Sie die dokumentierten Größen- und Mengenlimits und zeigen Sie einen klaren Fehler, bevor Zeit für eine Generierungsanfrage verbraucht wird. Halten Sie die Upload-Kennung mit dem Task-Datensatz verknüpft, aber legen Sie interne Speicherpfade nicht auf einer öffentlichen Seite offen. Wenn ein Upload fehlschlägt, stoppen Sie vor dem Anlegen eines Generierungs-Tasks, statt eine unvollständige Anfrage zu senden.
Unterscheiden Sie bei Wiederholungen idempotente Lesezugriffe von kostenpflichtigen Generierungsübermittlungen. Eine GET-Statusabfrage zu wiederholen ist in der Regel etwas anderes als ein POST zu wiederholen, der bereits einen Task angelegt haben kann. Wenn der Client die Übergabeantwort verliert, nutzen Sie zuerst eine dokumentierte Request-Kennung oder einen Wiederherstellungsmechanismus für das Konto. Existiert keiner, zeigen Sie dem Betrieb einen unklaren Zustand, statt stillschweigend ein Duplikat zu erzeugen.
Checkliste für das Deployment
Testen Sie vor dem Ausliefern einer H3-Integration mindestens eine gültige Anfrage pro Modell-ID, die für Ihr Konto freigeschaltet ist. Ergänzen Sie Negativtests für gebrochene Dauern, nicht unterstützte Auflösungen, zu viele Referenzen, kombinierte Frame- und Referenzeingaben sowie Referenzen bei Turbo. Prüfen Sie, ob die Oberfläche inkompatible Werte nach einem Modellwechsel löscht.
Protokollieren Sie in der Staging-Umgebung die Request-Felder nach der Validierung und vergleichen Sie sie mit dem dokumentierten Gateway-Schema. Erfassen Sie keine API-Schlüssel oder privaten Mediendaten in Logs. Bestätigen Sie Abfrage-URL, Task-Zustände und Ergebnisfeld mit einem Nicht-Produktions-Fixture oder einem freigegebenen Testkonto. Dieser Artikel ruft keinen Live-Endpunkt auf und validiert kein Verhalten des Remotedienstes.
Prüfen Sie unmittelbar vor dem Launch den Kontopreis und den Modellkatalog der Nutzer. Modellverfügbarkeit und Preise sind kontobezogene Informationen; kopierte Werte aus einem alten Artikel können veralten, auch wenn die Request-Felder unverändert bleiben.
Verwandte Modelle und nächste Schritte
- Videomodelle durchsuchen
- Playground mit MiniMax H3 öffnen
- Playground mit MiniMax H3 Max Turbo öffnen
Prüfen Sie vor dem Deployment die exakte Modell-ID, die aktuelle Verfügbarkeit der Route, das Upload-Format, das Antwortschema und den Kontopreis in der API-Dokumentation, die Ihnen zur Verfügung steht.







