Tutorial
So verwenden Sie minimax-h3-max-turbo/image-to-video über die HiAPI API: curl, Python und funktionierende Anfragebeispiele
Auf dieser Seite
Was dieser Endpunkt tut und wann Sie ihn einsetzen
minimax-h3-max-turbo/image-to-video nimmt ein Quellbild plus einen Text-Prompt entgegen und gibt ein kurzes Video zurück, das mit diesem Bild als Ausgangspunkt beginnt. Das Bild dient als erstes Frame (oder visueller Anker), sodass die Ausgabe dessen Komposition, Farbstimmung und Identität des Motivs übernimmt. Der Prompt beschreibt dann, was als Nächstes geschehen soll – Kamerabewegung, Aktion des Motivs, Atmosphäre.
Wann Sie ihn statt Text-zu-Video wählen
Text-zu-Video ist das richtige Werkzeug, wenn Sie keine Referenzvisuals haben und möchten, dass das Modell alles selbst erschafft. Bild-zu-Video ist die richtige Wahl, wenn das erste Frame selbst der Punkt ist: Sie haben ein bereits freigegebenes Produktbild, ein Keyframe aus einem Storyboard, ein Charakterdesign oder ein von einem Nutzer hochgeladenes Foto, das animiert werden soll und dabei erkennbar bleiben muss. Konkret setzen Teams diesen Endpunkt in folgenden Fällen ein:
- Das erste Frame ist vertraglich vorgegeben. Das Marketingteam benötigt exakt das Hauptbild als Eröffnung, nicht ein ähnliches Bild.
- Konsistenz über mehrere Clips hinweg ist wichtig. Die Wiederverwendung desselben Quellbildes hält eine Figur oder ein Produkt über eine Reihe von Clips hinweg stabil.
- Sie animieren Nutzerinhalte. Von Endnutzern hochgeladene Fotos sollen animiert und nicht neu interpretiert werden.
- Sie möchten den Prompt-Spielraum fokussierter halten. Bewegung zu beschreiben ist einfacher, als die gesamte Szene von Grund auf zu beschreiben, sodass der Prompt kurz und vorhersehbar bleibt.
Dieser Endpunkt ist asynchron: Sie übermitteln eine Aufgabe und rufen später das gerenderte Video ab. Diese Form eignet sich gut für warteschlangengetriebene Backends, was im Folgenden ausführlich beschrieben wird. Die vollständige Parameterübersicht finden Sie auf der Modellseite.
Voraussetzungen und Aufbau der Anfrage
Bevor Sie den Endpunkt aufrufen, stellen Sie sicher, dass Sie vier Dinge haben:
- Einen API-Schlüssel. Erstellen Sie ihn in Ihrem HiAPI-Konto und senden Sie ihn als Bearer-Token. Behandeln Sie ihn als geheim – betten Sie ihn niemals in Client-Code ein.
- Eine Basis-URL. Alle Anfragen gehen an den einheitlichen API-Host von HiAPI; der Endpunktpfad ist der Modellbezeichner.
- Ein Quellbild, erreichbar oder kodierbar – entweder eine öffentliche HTTPS-URL oder eine Base64-Nutzlast, je nachdem, welche Form das Anfrage-Schema akzeptiert.
- Einen HTTP-Client –
curlfür einen Schnelltest und eine beliebige Standardbibliothek oderrequestsin Python für die eigentliche Integration.
Bestandteile der Anfrage
Unabhängig von der Sprache enthält jede Aufgabenübermittlung dieselben konzeptionellen Bestandteile:
- Modell / Endpunkt –
minimax-h3-max-turbo/image-to-video, Teil des Anfragepfads und zur Klarheit im Anfragekörper wiederholt. - Quellbild – das erste Frame. Dies ist das Feld, das Bild-zu-Video von Text-zu-Video unterscheidet, und das Feld, das am häufigsten Validierungsfehler verursacht.
- Prompt – die Beschreibung von Bewegung und Szene. Beschreiben Sie nur, was sich ändert, nicht das, was im Bild bereits vorhanden ist.
- Optionale Generierungshinweise – Steuerung von Dauer und Auflösungsstil, sofern der Endpunkt diese anbietet. Senden Sie nur im Schema dokumentierte Parameter; unbekannte Schlüssel sind eine häufige Quelle von 4xx-Antworten.
Die Übermittlung gibt eine Aufgabenkennung und einen Status zurück. Das Video selbst kommt später über eine zweite Anfrage – deshalb ist der Abschnitt zum Polling unten ebenso wichtig wie der Aufruf zur Übermittlung.
Eine funktionierende curl-Anfrage
Der folgende Befehl übermittelt eine Bild-zu-Video-Aufgabe. Ersetzen Sie vor der Ausführung die Platzhalter – die großgeschriebenen Markierungen in spitzen Klammern – durch Ihre eigenen Werte.
curl -X POST "https://api.hiapi.ai/v1/<ENDPOINT_PATH>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3-max-turbo/image-to-video",
"image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
"prompt": "Langsames Heranfahren an das Produkt, weiches Studiolicht wandert über die Oberfläche, geringe Schärfentiefe."
}'
Einige praktische Hinweise zu diesem Befehl:
- Schlüssel aus einer Umgebungsvariable lesen.
$HIAPI_API_KEYverhindert, dass der Schlüssel in der Shell-Historie landet – vorausgesetzt, Sie exportieren ihn, statt ihn inline einzufügen. - Für den ersten Test eine öffentliche Bild-URL verwenden. So schließen Sie die Base64-Kodierung als Faktor aus und bestätigen gleichzeitig, dass Authentifizierung und Verbindung funktionieren.
- Den JSON-Anfragekörper klein halten. Die
-d-Nutzlast ist die gesamte Anfrage; ein fehlendes Komma erzeugt hier einen verwirrenden 400 statt eines klaren Schema-Fehlers. - Den Prompt in Anführungszeichen setzen. Prompts mit Satzzeichen zerstören eine nicht in Anführungszeichen gesetzte Shell-Zeichenkette.
Die Antwort ist ein Aufgabenobjekt, nicht das Video. Erfassen Sie daraus die Aufgaben-ID – Sie werden diese ID für die Polling-Anfrage verwenden. Wenn der Aufruf sofort fehlschlägt, springen Sie zum Abschnitt zur Fehlerbehebung; Authentifizierungs- und Nutzlastfehler zeigen sich in diesem Schritt, nicht später.
Dieselbe Anfrage in Python
Im Folgenden finden Sie den entsprechenden Übermittlungsaufruf in Python mit requests. Er setzt voraus, dass HIAPI_API_KEY in einer Umgebungsvariable gesetzt ist.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1/<ENDPOINT_PATH>"
payload = {
"model": "minimax-h3-max-turbo/image-to-video",
"image": "https://<YOUR_PUBLIC_IMAGE_HOST>/first-frame.jpg",
"prompt": (
"Langsames Heranfahren an das Produkt, weiches Studiolicht wandert "
"über die Oberfläche, geringe Schärfentiefe."
),
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
response.raise_for_status()
job = response.json()
print(job["id"], job.get("status"))
Wichtige Punkte, die Sie bei der Anpassung dieses Snippets beibehalten sollten:
- Ein Timeout ist keine Option. Die Übermittlung ist schnell, aber ein hängender Socket in einem Web-Request-Handler reißt Ihren Worker mit in den Abgrund.
- Erst
raise_for_status(), dann parsen. So wird aus einem stillen 401 eine Ausnahme, die Sie tatsächlich protokollieren können. - Die Aufgaben-ID zurückgeben, nicht die Antwort. In einem Dienst sollte die Übermittlungsfunktion den Bezeichner zurückgeben, damit ein separater Poller – oder eine Hintergrundaufgabe – das Warten übernimmt.
- Die Nutzlast in einer Variable halten. Nach einem erfolgreichen Aufruf erfordert der Austausch der Bild-URL gegen eine signierte Upload-URL oder eine Base64-Zeichenkette nur eine Zeile.
Hier wird bewusst ein einfacher HTTP-Client statt einer Wrapper-Bibliothek verwendet: Die Form der Anfrage ist der Vertrag, und Sie sollten in der Lage sein, sie in jeder Sprache Ihres Technologie-Stacks zu reproduzieren.
Bild und erstes Frame vorbereiten
Die meisten fehlgeschlagenen Bild-zu-Video-Aufgaben scheitern am Bild, nicht am Prompt. Ein paar Gewohnheiten vermeiden das.
Format und Bereitstellung
Verwenden Sie ein standardmäßiges, breit unterstütztes Rasterformat – JPEG oder PNG – und stellen Sie sicher, dass die URL öffentlich abrufbar ist, ohne Cookies, ohne Weiterleitung auf eine Anmeldeseite und ohne Abhängigkeit von einer signierten URL, die nach der Übermittlung abläuft. Wenn Ihre Assets in einem privaten Bucket liegen, erzeugen Sie eine signierte URL mit einer Lebensdauer, die deutlich länger ist als die voraussichtliche Laufzeit der Aufgabe. Entfernen Sie bei Base64-Nutzlasten das data-URI-Präfix, wenn das Schema rohe kodierte Bytes erwartet, und stellen Sie sicher, dass die kodierte Größe deutlich innerhalb der dokumentierten Grenzen liegt.
Abmessungen und Bildkomposition
Das Modell rendert das Video in einer festen Ausgabegröße, sodass das Quellbild angepasst wird. Zwei Konsequenzen:
- Passen Sie das Seitenverhältnis an das gewünschte Ergebnis an. Ein Hochformat-Porträtfoto, das in ein Querformat-Rendering eingespeist wird, wird beschnitten oder mit schwarzen Balken versehen, und das Motiv kann aus dem Zentrum geraten.
- Lassen Sie Spielraum für Bewegung. Wenn der Prompt eine Kamerafahrt nach vorn oder eine Aufwärtsbewegung des Motivs beschreibt, lassen Sie im Quellbild in dieser Richtung Platz.
Das erste Frame intakt halten
Das Eröffnungsframe wird hauptsächlich durch das Bild selbst bestimmt. Formulieren Sie den Prompt als Anweisung für das, was nach dem ersten Frame geschieht: Beschreiben Sie Kameraverhalten, Aktion des Motivs und Lichtveränderungen. Vermeiden Sie es, die Szene neu zu beschreiben – wenn das Bild bereits „roter Stuhl auf weißem Boden“ zeigt, erhöht eine wiederholte Beschreibung oft die Drift statt die Treue. Wenn das Ergebnis vom Quellbild abweicht, kürzen Sie zuerst den Prompt, bevor Sie das Bild austauschen.
Gehen Sie nicht davon aus, dass nicht dokumentierte Parameter existieren. Wenn eine gewünschte Steuerungsmöglichkeit nicht im Schema enthalten ist, erreichen Sie sie über den Prompt oder die Bildvorbereitung.
Den Lebenszyklus asynchroner Aufgaben handhaben
Bild-zu-Video-Aufgaben sind nicht synchron. Das Muster lautet Übermitteln → Abfragen → Abrufen, und eine Produktionsintegration sollte alle drei Schritte explizit implementieren.
1. Übermitteln und persistieren
Senden Sie die Übermittlungsanfrage und speichern Sie sofort die zurückgegebene Aufgaben-ID, idealerweise zusammen mit Ihrer eigenen Korrelations-ID, einem Hash der Anfrage-Nutzlast und einem Zeitstempel. Wenn der Prozess zwischen Übermittlung und Speicherung stirbt, haben Sie für eine Aufgabe bezahlt, die nicht mehr abrufbar ist.
2. Polling mit Backoff
Fragen Sie den Status-Endpunkt der Aufgabe mit der gespeicherten ID ab. Das Rendern von Videos dauert deutlich länger als die Bilderzeugung, daher:
- Beginnen Sie mit einem moderaten Intervall – einige Sekunden – und erhöhen Sie es mit zunehmender Aufgabendauer, statt den Endpunkt mit fester Rate zu bombardieren.
- Begrenzen Sie die Gesamtwartezeit auf eine für die Aufgabe angemessene Obergrenze und betrachten Sie die Aufgabe dann als abgelaufen, und entscheiden Sie, ob Sie es erneut versuchen.
- Behandeln Sie Endzustände als endgültig: Sobald eine Aufgabe Erfolg oder Fehlschlag meldet, stellen Sie das Polling ein.
import time
def wait_for_job(poll_fn, job_id, max_wait=600):
deadline = time.time() + max_wait
interval = 5
while time.time() < deadline:
job = poll_fn(job_id)
if job["status"] in ("succeeded", "failed"):
return job
time.sleep(interval)
interval = min(interval * 1.5, 30)
raise TimeoutError(f"Aufgabe {job_id} wurde nicht innerhalb von {max_wait}s abgeschlossen")
3. Ausgabe abrufen und speichern
Nach dem Erfolg enthält das Aufgabenobjekt den Ort des Ergebnisses. Laden Sie das Video zeitnah herunter und kopieren Sie es in Ihren eigenen Speicher – die Ausgabe-URL sollte als temporäre Ressource betrachtet werden, nicht als Ihre dauerhafte Asset-Bibliothek. Protokollieren Sie die Aufgaben-ID neben der gespeicherten Datei, damit der Support jeden Clip auf seine Anfrage zurückführen kann.
Bei Wiederholungsversuchen fragen Sie nur Aufgaben erneut ab, deren ID Sie gespeichert haben; senden Sie niemals blind erneut, sonst entstehen doppelte Renderings und doppelte Abrechnungen.
Fehlerbehebung bei häufigen Fehlern
Authentifizierungsfehler (401 / 403)
Prüfen Sie zuerst den Authorization-Header: das Wort Bearer, ein Leerzeichen, dann der Schlüssel, und kein abschließender Zeilenumbruch, der beim Kopieren des Schlüssels mitgekommen ist. Vergewissern Sie sich, dass der Schlüssel aktiv ist und zu dem Konto gehört, das Sie erwarten. Wenn curl funktioniert, Python aber nicht, geben Sie die Länge des Headers aus – eine leere Umgebungsvariable erzeugt ein scheinbar gültiges, aber nutzloses Token.
Fehlerhafte oder nicht unterstützte Bildnutzlast (400 / 422)
Der häufigste nicht authentifizierungsbezogene Fehler. Prüfen Sie der Reihe nach:
- Die Bild-URL lässt sich auflösen und leitet nicht auf eine HTML-Anmeldeseite weiter.
- Das Format ist JPEG oder PNG, nicht WebP, HEIC oder eine PDF-Vorschau.
- Die Größe nach Kodierung oder Download liegt innerhalb der dokumentierten Grenzen.
- Die Base64-Nutzlast hat kein
data:-Präfix und keine durch Zeilenumbrüche entstandenen Leerzeichen. - Das Bild ist nicht beschädigt – rufen Sie es selbst ab und öffnen Sie es, bevor Sie die API beschuldigen.
Unbekannte oder ungültige Parameter
Ein falsch geschriebener Feldname oder ein Parameter, den der Endpunkt nicht bereitstellt, führt normalerweise zu einem Validierungsfehler, der das Feld benennt. Entfernen Sie spekulative Parameter und bauen Sie die Anfrage anhand der im Dokument festgelegten Mindestanforderungen neu auf.
Rate Limits (429)
Verwenden Sie exponentielles Backoff und beachten Sie etwaige Retry-Hinweise in der Antwort. Wiederholen Sie nicht in einer engen Schleife; das verschärft die Begrenzung. Wenn Sie häufig darauf stoßen, übermitteln Sie Aufgaben stapelweise über eine Warteschlange, statt sie inline aus einer Benutzeranfrage auszulösen.
Aufgaben-Timeouts und hängendes Polling
Wenn eine Aufgabe innerhalb Ihres Budgets nie einen Endzustand erreicht, protokollieren Sie die Aufgaben-ID und den Statusverlauf und stellen Sie das Polling ein. Anhaltende Timeouts deuten meist auf ein zu großes oder ungewöhnliches Bild bei der Übermittlung hin, prüfen Sie daher erneut den Abschnitt zur Bildvorbereitung. Senden Sie nicht automatisch erneut, ohne eine Obergrenze für Versuche festzulegen.
Produktions-Checkliste vor dem Go-live
Bevor dieser Endpunkt echten Verkehr erhält, verifizieren Sie Folgendes:
- Timeouts überall. Die Übermittlung nutzt ein kurzes Timeout, das Polling hat eine Obergrenze für die Gesamtwartezeit, Wiederholungsversuche haben eine harte Obergrenze. Keine unbegrenzten
while True-Schleifen. - Wiederholungen mit Backoff. Wiederholen Sie 429- und vorübergehende 5xx-Antworten; wiederholen Sie niemals Validierungsfehler – sie schlagen auf dieselbe Weise fehl.
- Aufgaben-IDs in den Logs. Protokollieren Sie pro Anfrage die Aufgaben-ID, Ihre Korrelations-ID und den Endstatus. Das ist das nützlichste Debug-Artefakt, das Sie behalten können.
- Ausgaben in Ihrem eigenen Speicher. Kopieren Sie fertige Videos von der zurückgegebenen URL in persistenten Speicher und bewahren Sie die Referenz auf das Quellbild für Reproduzierbarkeit auf.
- Bildvalidierung an der Peripherie. Weisen Sie falsche Formate und überdimensionierte Uploads ab, bevor sie die API erreichen, damit Nutzer sofort einen klaren Fehler erhalten statt eines asynchronen Fehlschlags Minuten später.
- Kostenbewusstsein. Generierungen werden pro Ausgabe eines gerenderten Videos abgerechnet, daher sollten Sie Aufgabenvolumen und -dauer pro Nutzer oder Feature verfolgen. Prüfen Sie das aktuelle Preispaneel, statt Annahmen in Code oder Dokumentation fest zu verdrahten.
- Canary-Prompts. Halten Sie in Ihrer Testsuite eine Reihe bekanntermaßen funktionierender Bilder und Prompts bereit und führen Sie sie nach jeder Integrationsänderung aus, um zu bestätigen, dass der Anfragevertrag weiterhin gilt.
Sobald der asynchrone Lebenszyklus – Übermitteln, Persistieren, Abfragen, Speichern – korrekt gehandhabt wird, ist dieser Endpunkt unkompliziert. Rufen Sie das genaue Schema von der Modellseite ab und implementieren Sie dann das oben beschriebene Muster aus Übermittlung und Polling.
Ä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