Tutorial
So rufst du minimax-h3-max-turbo Text-zu-Video über die HiAPI API auf
- Modell
- minimax-h3-max-turbo
Auf dieser Seite
Was dieser Endpunkt leistet und wann er passt
minimax-h3-max-turbo/text-to-video ist ein Text-zu-Video-Modell-Endpunkt, der über die HiAPI API bereitgestellt wird. Du sendest einen Text-Prompt, der die Zielszene beschreibt, plus einige wenige Parameter zur Steuerung der Ausgabeform, und HiAPI liefert das generierte Video zurück. Dieses Modell eignet sich hervorragend, wenn du eine Textbeschreibung, aber kein Ausgangsmaterial hast: Marketing-Clips, Social-Media-Übergangseinstellungen, Storyboard-Vorschauen, Hintergrund-Loopvideos für Apps oder die Batch-Erzeugung von Varianten desselben kreativen Konzepts.
Vor dem Schreiben von Code lohnen sich einige Eigenschaften zur Beachtung:
- Es ist ein Generierungs-Endpunkt, keine Vorlage. Die Ausgabe ist nur strukturell vorhersehbar (du bekommst ein Video), der Inhalt selbst ist nicht vorhersehbar. Betrachte jeden Task als vollständig neues Rendering und entwirf Prompts auf Wiederverwendbarkeit hin.
- Er ist asynchron. Der Submit-Aufruf liefert nicht direkt die fertigen Videobytes. Du erhältst zunächst ein Task-Handle und pollst dann das Ergebnis. Jede Integration, die eine synchrone Antwort annimmt, scheitert beim ersten Timeout.
- Die Ausgabe wird durch die Request-Parameter bestimmt. Dauer und Auflösung verändern die Rendering-Kosten und die tatsächliche Laufzeit, daher sind die von dir gewählten Parameter zugleich Latenz- und Budgetentscheidungen.
- Kein Quellmedium erforderlich. Du musst weder Video noch Bild hochladen; Prompt und Parameter sind die gesamte Eingabefläche.
Wann solltest du eine andere Lösung verwenden? Wenn du bereits Material hast und es umstilisieren oder erweitern willst, ist dies nicht der passende Endpunkt. Wenn du Frame-genaue Kontrolle über Kamerabewegung oder präzise Komposition benötigst, ist ein Text-Prompt zu locker. Und wenn du nur ein statisches Bild brauchst, ist der Text-zu-Bild-Endpunkt günstiger und schneller. Wenn der Prompt als Shot-Spezifikation ausreicht, verwende minimax-h3-max-turbo/text-to-video.
Der Rest dieses Leitfadens behandelt der Reihe nach Authentifizierung, einen lauffähigen curl-Aufruf, den äquivalenten Python-Aufruf, den Task-Lebenszyklus, die wichtigsten Parameter, die Fehler, auf die du stoßen wirst, und die Härtungsschritte vor dem Go-live.
Voraussetzungen und Authentifizierung
Vor der ersten Anfrage brauchst du drei Dinge:
- Einen API-Schlüssel deines HiAPI-Kontos. Behandle ihn als Geheimnis: lade ihn aus einer Umgebungsvariable, committe ihn niemals ins Repository und rotiere ihn sofort, falls er kompromittiert wird.
- Die HiAPI-Basis-URL. Alle Aufrufe in diesem Leitfaden gehen an denselben Basis-Host; das Modell wird über das Pfadsegment gewählt, nicht über eine eigene Domain pro Modell.
- Einen HTTP-Client. curl für den Smoke-Test, eine beliebige Standardbibliothek oder einen HTTP-Client für den Service-Code.
Wie der Schlüssel übergeben wird
HiAPI authentifiziert Anfragen über einen Bearer-Token im Authorization-Header. Die Form ist immer dieselbe:
export HIAPI_API_KEY="your_api_key_here"
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Zwei Gewohnheiten ersparen dir viel Debugging-Zeit:
- Die Header-Schreibweise muss exakt stimmen. In
Authorizationdas A groß, nachBearergenau ein Leerzeichen, dann der Schlüssel. Ein fehlendes Leerzeichen ist die häufigste Ursache für mysteriöse 401er. - Sende immer
Content-Type: application/json. Server, die JSON erwarten, lehnen Requests ohne diesen Header ab oder parsen den Body falsch; die Fehlermeldung, die du erhältst, spricht dann oft von einem fehlenden Feld statt von der eigentlichen Ursache.
Erst verifizieren, dann entwickeln
Beginne nicht sofort mit dem Video-Endpunkt. Mache zuerst einen günstigen, schnellen Aufruf, um sicherzustellen, dass Schlüssel und Basis-URL korrekt aufgelöst werden, und fahre dann fort. Wenn diese Plausibilitätsprüfung fehlschlägt, funktioniert nichts weiter unten, und du debuggst auf der falschen Ebene. Halte den Schlüssel an genau einer Stelle im Code – einem kleinen Client-Modul –, sodass eine spätere Rotation nur eine Zeile ändert.
Lauffähige curl-Anfrage
Der Submit-Aufruf sendet den Prompt und die Parameter als JSON-Body an den Modellpfad. Hier ist der minimale lauffähige Aufruf:
curl -sS -X POST "$HIAPI_BASE_URL/minimax-h3-max-turbo/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Bei Sonnenaufgang eine langsame Luftaufnahme, die über einen nebligen Kiefernwald gleitet, weiches Volumenlicht, filmisch",
"duration": 5,
"resolution": "720p"
}'
Was die einzelnen Teile bewirken:
-X POST– Generierungs-Tasks werden per POST erstellt.- Die URL – Basis-Host plus Pfad
minimax-h3-max-turbo/text-to-video. Lege den Basis-Host in eine Variable, damit Tests und Produktion denselben Codepfad nutzen können. Authorization– der im vorigen Abschnitt beschriebene Bearer-Token.Content-Type– deklariert den JSON-Body.prompt– die einzige erforderliche kreative Eingabe. Beschreibe sie wie eine Shot-Vorgabe: Motiv, Kamerabewegung, Beleuchtung und Stimmung. Kurze Nominalphrasen führen zu vagen Ergebnissen; ein bis zwei Sätze mit konkreter visueller Richtung wirken deutlich besser.durationundresolution– Parameter zur Steuerung der Ausgabeform, dazu gibt es unten einen eigenen Abschnitt.
Verwende -sS, damit curl still bleibt, aber Fehler ausgibt, und leite die Antwort in der Erkundungsphase durch ein Pretty-Print-Werkzeug. Die Antwort ist JSON mit einer Task-Kennung; speichere sie, denn du brauchst sie, um das fertige Video abzufragen. Erwarte nicht, dass diese Antwort Videobytes enthält.
Wenn du beim Debuggen sehen willst, was tatsächlich gesendet wurde, kannst du -v für ausführliche Ausgabe hinzufügen, aber entferne sie, bevor du Logs teilst, denn die ausführliche Ausgabe kann Header enthalten.
Der äquivalente Python-Aufruf
Die Python-Version ist dieselbe Anfrage, nur dass der Schlüssel aus der Umgebung geladen und die Antwort geparst wird. Hier ist ein kleiner wiederverwendbarer Client:
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
MODEL_PATH = "/minimax-h3-max-turbo/text-to-video"
def submit_video(prompt: str, duration: int = 5, resolution: str = "720p") -> dict:
payload = {"prompt": prompt, "duration": duration, "resolution": resolution}
resp = requests.post(
f"{BASE_URL}{MODEL_PATH}",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job = submit_video(
"Bei Sonnenaufgang eine langsame Luftaufnahme, die über einen nebligen Kiefernwald gleitet, weiches Volumenlicht, filmisch"
)
print(job)
Hinweise zur Anpassung:
json=payloadsetzt Body und Content-Type zugleich; serialisiere nicht zusätzlich manuell.timeout=30begrenzt den Submit-Aufruf. Das Einreichen ist schnell, das Rendering nicht – deshalb ist der Timeout hier kurz und das Warten übernimmt das Polling.raise_for_status()macht aus Nicht-2xx-Antworten eine Exception, sodass Authentifizierungs- und Validierungsfehler sofort auffallen, statt still einen Fehler-Body zurückzugeben, den du später fälschlich als Task interpretierst.- Gib das geparste JSON als Dictionary zurück und extrahiere die Task-Kennung an der Aufrufstelle. So bleibt die Hilfsfunktion allgemein, und der Orchestrierungscode entscheidet, was damit geschieht.
Wenn du einen asynchronen Stack verwendest, gilt dieselbe Form für den HTTP-Client deiner Wahl: Header einmal bauen, Body per POST senden, Status prüfen, geparsten Body zurückgeben.
Den asynchronen Task-Lebenszyklus handhaben
Generierung braucht Zeit, daher ist der Endpunkt in Submit und Polling aufgeteilt. Der Lebenszyklus ist immer: einreichen, Task-Kennung erhalten, den Task bis zum terminalen Status pollen, dann die Ausgabe abrufen.
Einreichen
Sende den zuvor beschriebenen POST und lies die Task-Kennung aus der Antwort. Logge sie sofort und verknüpfe sie mit deiner eigenen Request-ID, damit ein späteres Polling-Scheitern auf den ursprünglichen Prompt zurückverfolgt werden kann.
Polling mit Backoff
Polls nicht in einer engen Schleife. Beginne mit einem kurzen Intervall und fahre dann mit Backoff hoch:
def wait_for_job(job_id: str, max_wait: int = 600) -> dict:
deadline = time.time() + max_wait
interval = 2.0
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}{MODEL_PATH}/{job_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
status = job.get("status")
if status in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 15.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
Drei Details machen diesen Code zuverlässig. Erstens die Deadline: immer irgendwann aufgeben und einen Timeout werfen, statt endlos zu pollen. Zweitens der gedeckelte Backoff: mit wenigen Sekunden starten, schrittweise multiplizieren und das Intervall kappen, damit kontinuierlich Fortschritt entsteht, ohne die API zu häufig zu treffen. Drittens die Behandlung terminaler Zustände: nur Erfolg und Fehler als terminal betrachten und das Task-Objekt zurückgeben, damit der Aufrufer verzweigen kann.
Ergebnis abrufen
Sobald der Task Erfolg meldet, enthält die Antwort den Ort des fertigen Videos. Lade es zügig herunter oder streame es in deinen eigenen Speicher und protokolliere die URL zusammen mit der Task-ID. Nimm nicht an, dass der Link dauerhaft gültig ist, und rufe das Video nicht in jeder Polling-Iteration ab. Polle den Task-Status und hole das Video dann einmal bei Erfolg.
Die Parameter Dauer und Auflösung
Zwei Request-Parameter bestimmen die Ausgabe und zugleich Rendering-Zeit und Kosten des Aufrufs.
duration
Die Länge des generierten Segments. Je länger das Segment, desto proportional länger die Rendering-Zeit, was ein längeres Polling-Fenster und eine höhere Wahrscheinlichkeit bedeutet, dass dein Client-Timeout auslöst. Praktische Empfehlungen:
- Passe die Dauer an den Anwendungsfall an. Social-Media-Übergangseinstellungen sind kurz; ein Hintergrund-Loop muss nur lang genug sein, um akzeptabel zu loopen. Längere Inhalte zu generieren als tatsächlich gezeigt werden, ist reine Verschwendung.
- Beginne beim Iterieren klein. Stimme den Prompt bei kürzerer Dauer ab und rendere den erfolgreichen Prompt dann in der endgültigen Länge neu.
- Bedenke, dass die Kosten mit der Ausgabegröße wachsen. Die Abrechnung erfolgt nach Ausgabelänge, daher ist die Dauer sowohl ein kreativer als auch ein Budget-Hebel.
resolution
Die räumliche Qualität der Ausgabe. Höhere Auflösung bringt mehr Details, kostet aber mehr Rendering-Zeit und mehr Geld. Empfehlungen:
- Wähle nach dem Auslieferungskontext, nicht nach dem Datenblatt. Wenn das Video in einem Feed oder kleinen Player erscheint, bringt eine höhere Auflösung als dort nötig keinen Nutzen.
- Bei niedriger Auflösung iterieren, in hoher Auflösung ausliefern. Vorschau mit niedrigerer Auflösung, solange du den Prompt noch änderst, dann den freigegebenen Prompt in Auslieferungsauflösung neu einreichen.
- Höhere Einstellungen bedeuten längeres Warten. Setze die Polling-Deadline auf die größte von dir erlaubte Kombination, nicht auf die kleinste.
Lege beide Werte in einem gemeinsamen Konfigurationsobjekt ab statt über den Code verstreut, damit der Wechsel von Vorschau zu Produktion eine bewusste und sichtbare Änderung ist und kein vergessenes Literal.
Häufige Fehler debuggen
Die meisten Fehlschläge lassen sich in vier Kategorien einordnen. Ordne das Symptom der Kategorie zu, bevor du Code änderst.
Authentifizierungsfehler
Ein 401 bedeutet, dass HiAPI deine Anmeldedaten nicht akzeptiert. Prüfe der Reihe nach: der Authorization-Header ist vorhanden und korrekt geschrieben; nach Bearer steht genau ein Leerzeichen; der Schlüssel ist aktuell gültig und stammt nicht aus einem anderen Projekt; die Umgebungsvariable ist tatsächlich geladen (ein Zeilenumbruch am Ende beim Einfügen des Schlüssels ist ein Klassiker). Prüfe das, indem du die Länge der Variable ausgibst, nicht den Schlüssel selbst.
Validierungsfehler
Ein 4xx außer 401 bedeutet meist, dass der Request-Body fehlerhaft ist. Content-Type fehlt oder ist nicht application/json; prompt fehlt oder ist leer; duration oder resolution liegen außerhalb der erlaubten Menge. Lies die Fehlermeldung wörtlich; sie nennt meist das problematische Feld. Reproduziere mit der curl-Version, denn dort verdeckt keine Bibliotheksschicht den Body.
Timeouts
Es gibt zwei verschiedene Timeouts. Ein Submit-Timeout bedeutet, dass der POST selbst nicht zurückkehrt, was meist auf den Netzwerkpfad oder einen zu aggressiven Client-Timeout hindeutet. Ein Polling-Timeout bedeutet, dass der Task vor deiner Deadline keinen terminalen Status erreicht hat; entweder dauert das Rendering tatsächlich länger, oder deine Deadline ist auf Vorschau-Einstellungen statt auf Produktions-Einstellungen ausgelegt. Behebe Letzteres, indem du max_wait für große Dauer und große Auflösung erhöhst, nicht indem du das Polling-Intervall verkürzt.
Polling-Fehler
Die versteckteren. Polling ohne Sleep verschwendet Quota und provoziert Rate-Limits; Polling mit festem kurzem Intervall hat denselben Effekt. Die falsche Task-ID pollen, meist weil du eine Variable zwischen mehreren Submits wiederverwendet hast. Zwischenzustände als Fehler behandeln. Und die Video-URL in jeder Iteration abrufen statt einmal bei Erfolg. Logge die Task-ID und jeden beobachteten Status; die Sequenz zeigt dir sofort, welcher dieser Fälle vorliegt.
Produktions-Checkliste vor dem Go-live
Der Weg vom funktionierenden Skript zum unbeaufsichtigt laufenden Service bedeutet, dieselbe Anfrage mit einigen zusätzlichen Schichten zu umgeben.
- Retries mit Jitter. Wiederhole transiente Netzwerkfehler und 5xx-Antworten mit exponentiellem Backoff und Randomisierung. Wiederhole niemals Validierungsfehler; sie scheitern genauso und verbrauchen Quota.
- Überall begrenzte Timeouts. Kurzer Timeout für den Submit, längere Deadline für das Polling (ausgelegt auf deine erlaubte maximale Dauer und Auflösung) und auch für den Video-Download einen Timeout.
- Strukturiertes Logging. Logge deine Request-ID, Task-ID, jeden beobachteten Statusübergang und das Endergebnis, aber niemals API-Schlüssel oder vollständige Header. Wenn um drei Uhr nachts etwas schiefgeht, ist dieses Log dein einziges Beweismittel.
- Idempotenz in deiner Schicht. Führe eine Zuordnung von deiner eigenen Request-ID zur Task-ID, damit Client-Retries nicht still ein zweites Rendering erzeugen.
- Kostenkontrolle. Die Abrechnung erfolgt nach Ausgabelänge, also setze Obergrenzen für die vom Service akzeptierte maximale Dauer und Auflösung und halte Prompt-Vorschauen auf niedrigeren Einstellungen, bis das finale Rendering durch Mensch oder Regel freigegeben ist.
- Schlüssel-Hygiene. Lade Schlüssel aus einem Secret Store, rotiere sie planmäßig, verwende unterschiedliche Schlüssel für Test und Produktion, damit ein kompromittierter Testschlüssel kein Produktionsbudget verbrauchen kann.
- Ergebnis-Zuordnung. Sobald ein Task erfolgreich ist, kopiere das fertige Video sofort in Speicher unter deiner Kontrolle und behandle die Auslieferungs-URL als temporären Link.
Wenn all das umgesetzt ist, wird der Endpunkt zu einer verlässlichen Abhängigkeit statt zu einer Quelle von Überraschungen. Bestätige zuerst die Anmeldedaten mit der obigen curl-Anfrage, integriere dann den Python-Client in deinen Service und umhülle ihn mit den Prüfungen aus dieser Liste.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen