Tutorial
veo-3.1/image-to-video über die HiAPI API aufrufen: curl- und Python-Tutorial
Auf dieser Seite
Was der veo-3.1-Bild-zu-Video-Endpunkt erwartet
Bevor man die erste Codezeile schreibt, ist es hilfreich zu verstehen, um welche Art von Aufruf es sich handelt. veo-3.1/image-to-video liefert das Video nicht direkt in der HTTP-Antwort zurück, in der der Prompt gesendet wird. Es ist ein asynchroner Task-Endpunkt: Du beschreibst das gewünschte Video, die Plattform nimmt die Aufgabe an, und anschließend fragst Du das Ergebnis ab.
Konzeptionell besteht eine Anfrage aus zwei klar getrennten Teilen:
- Das Erstbild. Dies ist das Standbild, mit dem die Videogenerierung beginnt. Es legt Komposition, Motiv und Anmutung des Eröffnungsmoments fest. Alles Weitere erzeugt das Modell von diesem Ausgangspunkt aus.
- Die Generierungsoptionen. Dies sind die Parameter, die steuern, wie das Video erzeugt wird – zum Beispiel ob Audio generiert wird, die Ausgabeauflösung und die Cliplänge.
Diese Aufteilung ist aus zwei Gründen wichtig. Erstens macht sie Fehler leichter nachvollziehbar: Ein Bildproblem sieht anders aus als ein Parameterproblem, und man möchte beides unterscheiden können. Zweitens bedeutet es, dass auch der Code entsprechend organisiert sein sollte – ein Teil der Logik bereitet das Bild vor, ein anderer baut die Optionsmenge auf.
Aufrufer müssen mindestens bereitstellen: ein gültiges Erstbild sowie eine Entscheidung zu Audio, Auflösung und Dauer. Alles Übrige – Aufgabe einreichen, Status verfolgen, fertiges Video zurückgeben – übernimmt der Task-Lebenszyklus der Plattform. Deine Integration muss nur drei Dinge tun: eine korrekt formatierte Anfrage senden, die zurückgegebene Aufgaben-ID merken und pollen, bis die Aufgabe einen Endzustand erreicht.
Ein praktischer Hinweis vorab: Da der Aufruf asynchron ist, darf dein Code nicht davon ausgehen, dass das Video direkt nach dem Einreichen verfügbar ist. Gestalte den Ablauf von Anfang an entsprechend, dann wirken die folgenden Tutorial-Schritte selbstverständlich.
Das mentale Modell der zwei Teile
Halte diesen Rahmen beim Lesen der folgenden Abschnitte im Hinterkopf:
- Eingabe → vorbereitetes und validiertes Erstbild.
- Optionen → Audio, Auflösung, Dauer.
- Aufgabe → einreichen, ID abrufen, pollen, abholen.
Jeder der folgenden Abschnitte entspricht einem dieser Kästen.
Das Erstbild vorbereiten
Das Erstbild ist die wichtigste einzelne Eingabe beim Bild-zu-Video-Aufruf. Gib ihm daher einen eigenen Schritt in der Pipeline, statt es im Request-Builder zu verstecken. Der API-Aufruf muss auf dieses Bild verweisen können, was bedeutet, dass es in einer von der Plattform akzeptierten und lesbaren Form vorliegen muss.
Was vor dem Senden zu prüfen ist
- Das Bild lässt sich tatsächlich öffnen. Abgebrochene Downloads oder beschädigte Dateien sind die häufigste Ursache für verwirrende Fehler stromabwärts. Verifiziere vor dem Senden, dass das Bild fehlerfrei dekodiert werden kann.
- Das Format wird von der Plattform akzeptiert. Wenn deine Quelle ein Screenshot, ein Handyfoto oder ein Export aus einem Design-Tool ist, normalisiere sie vor dem Upload in ein breit unterstütztes Format. Einmal vorab konvertieren spart mehr Zeit als späteres Debugging.
- Die Abmessungen sind sinnvoll. Extrem kleine oder stark gestreckte Bilder bieten dem Modell wenig Material. Ist die Quelle zu klein, erwäge ein Hochskalieren oder wähle einen besseren Frame.
- Die Komposition ist ein guter Ausgangspunkt. Da dies das erste Bild ist, setzt sich die generierte Bewegung daraus fort. Wähle einen Frame, in dem das Motiv klar sichtbar ist und dessen Komposition du gern am Clipanfang siehst.
Von den Optionen getrennt halten
Organisiere den Code so, dass die Bildvorbereitung eine Referenz zurückgibt, die an den Request-Builder übergeben werden kann, statt Bildverarbeitung und Parameterzusammenstellung zu vermischen. Konkret:
# Pseudocode-Struktur, kein vollständiger Client
def prepare_first_frame(path):
image = load_and_validate(path) # dekodieren, Format prüfen, Abmessungen prüfen
ref = upload_or_encode(image) # etwas erzeugen, worauf der API-Aufruf verweisen kann
return ref
def build_request(first_frame_ref, options):
return {
"first_frame": first_frame_ref,
# Audio / Auflösung / Dauer kommen hierhin
}
Diese Trennung zahlt sich beim Debugging aus. Schlägt die Aufgabe fehl, kannst du prepare_first_frame separat erneut ausführen und bestätigen, dass die Bildseite intakt ist, bevor du irgendeinen Generierungsparameter anfasst.
Früh validieren, laut scheitern
Validiere auf deiner Seite und wirf bei Fehlern klare Exceptions. Ein falsch formatiertes oder unlesbares Bild sollte niemals ins Netz gelangen – fängst du es lokal ab, verwandelst du einen vagen asynchronen Task-Fehler in eine präzise, sofortige Exception aus deinem eigenen Code.
Generierungsoptionen festlegen: Audio, Auflösung und Dauer
Nach der Bildverarbeitung bleiben die Generierungsoptionen als Entscheidungen übrig. Sie verändern die Art der Ausgabe und sollten daher als explizite benannte Parameter behandelt werden, nicht als magische Werte, die im Request-Body vergraben sind.
Audio
Die Audio-Option steuert, ob das generierte Video eine Tonspur enthält. Das ist sowohl eine technische als auch eine Produktentscheidung:
- Wenn das Video stumm eingebettet wird – Hintergrundschleifen, automatisch abspielende Hauptvisuals – ist Audio meist nicht nötig, und sein Weglassen vereinfacht die Weiterverarbeitung stromabwärts.
- Wenn der Clip eigenständig mit Ton präsentiert wird – kurze Social-Media-Inhalte, Präsentationen – aktiviere Audio, sodass ein einziger Aufruf vollständiges Material liefert.
Entscheide je nach Anwendungsfall bewusst statt blind den Standardwert zu übernehmen; er beeinflusst sowohl die Ausgabe als auch die Art, wie deine nachgelagerte Pipeline die Datei behandelt.
Auflösung
Die Auflösung bestimmt die Pixelabmessungen des fertigen Videos. Wähle sie danach, wo das Video gezeigt wird und wie viel Detail der Inhalt benötigt, nicht einfach nach dem „größten verfügbaren Wert“. Ein Clip für einen kleinen eingebetteten Player profitiert nicht davon, in einer Größe generiert zu werden, die weit über die Fähigkeiten des Anzeigepanels hinausgeht. Wenn die Plattform eine Menge unterstützter Werte veröffentlicht, wähle explizit daraus und validiere clientseitig entsprechend, damit nicht unterstützte Werte schnell scheitern.
Dauer
Die Dauer legt die Länge des generierten Clips fest. Sie interagiert mit deiner Inhaltsplanung: Eine Einstellung, die zuerst die Szene etablieren und dann Bewegung zeigen soll, braucht mehr Zeit als eine einzelne Geste. Beachte, dass dies einer der Parameter ist, die am ehesten gemessen werden – die Abrechnung der Plattform wird anhand der generierten Ausgabe beschrieben, also achte bei Batch-Anfragen darauf, wie lang die Clips sind.
Die Optionen in einem Objekt zusammenfassen
Lege alle drei in derselben Optionsstruktur ab, sodass es nur eine Stelle zum Nachsehen und eine zum Ändern gibt:
options = {
"audio": True, # Tonspur generieren
"resolution": "...", # einer der unterstützten Werte
"duration": 8, # Sekunden des generierten Videos
}
Verwende die Werte, die für dein Konto und den aktuellen Endpunkt in der Dokumentation als unterstützt aufgeführt sind – lies sie aus der Dokumentation, statt geratene Werte hart zu kodieren, und validiere beim Erstellen der Anfrage, sodass fehlerhafte Werte nie zu einer fehlgeschlagenen Aufgabe werden.
Aufgabe mit curl einreichen
Jetzt führst du beide Teile zusammen und reichst ein. Beginne mit der Kommandozeile, denn curl macht die Anfrageform sichtbar und gibt dir eine schnelle Möglichkeit, Änderungen zu testen, bevor du Code schreibst.
Die Anfrage
Die Einreichungsanfrage sieht strukturell so aus – ersetze die Platzhalterwerte durch deine eigenen Zugangsdaten, Bildreferenz und Optionswerte:
curl -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_frame": "<Bildreferenz aus dem Upload-Schritt>",
"audio": true,
"resolution": "<unterstützter Wert>",
"duration": 8
}'
Einige Konventionen, die sich zu übernehmen lohnen:
- Lege den Schlüssel in einer Umgebungsvariable (
$HIAPI_API_KEY) ab, statt ihn in den Befehl zu kleben. Diese Gewohnheit setzt sich direkt in deinem Python-Code fort und hält den Schlüssel aus der Shell-Historie heraus. - Sende JSON mit explizitem
Content-Type-Header. - Trenne im Request-Body die Bildreferenz von den numerischen und booleschen Optionen, was das Zwei-Teile-Modell aus dem ersten Abschnitt widerspiegelt.
Die Antwort lesen
Da dies ein asynchroner Endpunkt ist, ist die Erfolgsantwort nicht das Video. Sie ist nur die Bestätigung, dass die Aufgabe angenommen wurde, und trägt die zum Verfolgen nötigen Informationen – vor allem die Aufgaben-ID, meist zusammen mit einem Statusfeld, das anzeigt, dass die Aufgabe in der Warteschlange steht oder läuft.
Lies sie in zwei Schritten. Bestätige zuerst, dass der HTTP-Status Annahme statt Clientfehler bedeutet. Parse dann den Antwort-Body und extrahiere die Aufgaben-ID:
curl -s -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | tee submit.json
Schreibst du die Antwort in submit.json, hast du etwas zum Inspizieren und zum Weitergeben an den Polling-Schritt. Schlägt die Einreichung fehl, ist der Fehler-Body dein erster und bester Hinweis – prüfe, ob er auf die Bildreferenz oder eine Option deutet, repariere genau diese Hälfte und reiche erneut ein.
Die asynchrone Aufgabe pollen, bis das Video bereit ist
Sobald du die Aufgaben-ID hast, wird der Workflow zu einer Schleife: Die Plattform nach dem Aufgabenstatus fragen und stoppen, wenn die Aufgabe einen Endzustand erreicht.
Der Lebenszyklus
Bild-zu-Video-Aufgaben durchlaufen wenige Zustände. Sie werden angenommen und eingereiht, dann verarbeitet und schließlich entweder erfolgreich abgeschlossen mit einem Video oder fehlgeschlagen mit einem Fehler. Dein Polling-Code muss nur drei Dinge unterscheiden:
- Noch in Verarbeitung – weiter warten.
- Erfolgreich – den Ausgabespeicherort lesen und das Video herunterladen oder speichern.
- Fehlgeschlagen – stoppen und einen Fehler werfen.
Verantwortungsvoll pollen
Zwei Gewohnheiten machen das Polling robuster:
- Zwischen den Prüfungen warten. Eine enge Schleife, die den Status-Endpunkt hämmert, verschwendet Anfragen ohne Nutzen; Generierung braucht echte Zeit. Nutze ein festes Intervall oder ein sanftes Backoff.
- Eine Frist setzen. Polle niemals unbegrenzt. Wähle eine maximale Anzahl von Versuchen oder eine maximale Dauer und behandle deren Überschreiten als klar berichtbaren Fehler.
# Skizze der Polling-Schleife
for i in $(seq 1 60); do
status=$(curl -s "https://api.hiapi.ai/v1/jobs/<job_id>" \
-H "Authorization: Bearer $HIAPI_API_KEY")
echo "$status"
# abbrechen, wenn das Statusfeld Erfolg oder Fehler meldet
sleep 5
done
Behandle die genauen Status-Strings und Endpunktpfade als Dinge, die gegen die aktuelle API-Dokumentation abgeglichen werden müssen, nicht als im Skript fest verankerte Annahmen.
Im Erfolgsfall
Wenn die Aufgabe Erfolg meldet, enthält die Antwort den Speicherort des fertigen Videos. Lade es zeitnah herunter und speichere es an einem dauerhaften Ort – Ergebnisse von Aufgaben auf asynchronen Plattformen sollten als etwas betrachtet werden, das jetzt abgeholt wird, nicht erst viel später per Lazy-Loading. Protokolliere die Aufgaben-ID zusammen mit der gespeicherten Datei, damit jede Ausgabe bis zur Anfrage zurückverfolgt werden kann, die sie erzeugt hat.
Dieselbe Anfrage in Python
Die Python-Version sollte keine zweite Implementierung sein – sondern dieselbe Anfrage, einmal ausgedrückt und wiederverwendet. Ziel ist eine einzelne Funktion, die einreicht und pollt, aufgebaut aus derselben Bildreferenz und demselben Optionsobjekt, die du zuvor validiert hast.
Ein Request-Body, ein Client
import os
import time
import requests
BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
session = requests.Session()
session.headers.update({
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
})
def build_body(first_frame_ref, options):
return {"first_frame": first_frame_ref, **options}
def submit(body):
r = session.post(f"{BASE}/veo-3.1/image-to-video", json=body, timeout=60)
r.raise_for_status()
data = r.json()
return data["job_id"]
def poll(job_id, interval=5, max_attempts=60):
for _ in range(max_attempts):
r = session.get(f"{BASE}/jobs/{job_id}", timeout=30)
r.raise_for_status()
data = r.json()
state = data.get("status")
if state in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"Aufgabe {job_id} konnte nicht rechtzeitig abgeschlossen werden")
def image_to_video(first_frame_ref, options):
job_id = submit(build_body(first_frame_ref, options))
result = poll(job_id)
if result["status"] == "failed":
raise RuntimeError(result.get("error", "Aufgabe fehlgeschlagen"))
return result # enthält den Speicherort des fertigen Videos
Warum diese Form
- Eine
Session. Die Wiederverwendung der Session fasst die Authentifizierungs-Header an einer Stelle zusammen und nutzt Verbindungen zwischen Einreichung und jedem Polling-Aufruf wieder. - Ein
build_body. Die curl-Anfrage und die Python-Anfrage nutzen denselben Request-Body – dieselben Schlüssel, dieselben Werte. Wenn du eine Option änderst, änderst du sie nur an einer Stelle. - Explizite Timeouts und Fristen. Beide Aufrufe haben Timeouts, und
pollist in der Anzahl der Versuche begrenzt, sodass eine hängende Aufgabe deinen Prozess niemals blockiert. - Fehler werden laut sichtbar.
raise_for_statusbeim Einreichen fängt Anfragefehler sofort ab; der explizite Fehlerzweig inimage_to_videofängt Fehler auf Aufgabenebene ab.
Falls du später andere Modelle über dieselbe Plattform aufrufen möchtest, lässt sich diese Struktur verallgemeinern: Session, Submit-Hilfsfunktion und Polling-Hilfsfunktion bleiben gleich, nur Endpunkt und Body-Builder ändern sich.
Fehlgeschlagene Bild-zu-Video-Aufrufe diagnostizieren
Wenn ein Aufruf kein Video erzeugt, grenze das Problem ein, indem du fragst, welche Phase fehlgeschlagen ist. Das Zwei-Teile-Anfragemodell gibt dir eine klare Checkliste.
Phase 1: Einreichung abgelehnt
Wenn der Einreichungsaufruf selbst einen Fehler zurückgibt, wurde nichts generiert – das ist eine gute Nachricht, denn das Problem liegt in der Anfrage.
- Problem mit der Bildreferenz. Die häufigste Einzelursache. Führe den Bildvorbereitungsschritt separat erneut aus und bestätige, dass er ein gültiges, lesbares, korrekt formatiertes Bild sowie eine von der API akzeptierte Referenz liefert. Prüfe zuerst abgebrochene Uploads und nicht unterstützte Formate.
- Ungültige Optionswerte. Eine nicht unterstützte Auflösung oder eine Dauer außerhalb des Bereichs wird bei der Einreichung abgelehnt. Validiere die Optionen vor dem Senden gegen die unterstützten Werte in der Dokumentation.
- Authentifizierung und Header. Bestätige, dass der Schlüssel tatsächlich gesendet wird (
Authorization: Bearer ...) und der Body als JSON übertragen wird. Beim manuellen Aufbau der Anfrage in curl werden leere oder fehlerhafte Bodies leicht übersehen.
Phase 2: Aufgabe eingereicht, aber fehlgeschlagen
Wird die Einreichung angenommen, aber das Polling endet mit einem Fehler, war die Anfrage korrekt formatiert; das Problem liegt im Inhalt oder in der Aufgabe selbst.
- Lies den Aufgabenfehler. Die Fehlerantwort erklärt besser als jede Vermutung, was schiefgelaufen ist. Protokolliere sie unverändert.
- Prüfe das Erstbild. Quellbilder ohne klares Motiv, mit extremem Beschnitt oder starker Verzerrung bieten dem Modell wenig Material. Ersetze sie durch einen saubereren Frame und versuche es erneut.
- Überdenke die Optionen. Eine sehr lange Dauer oder ungewöhnliche Einstellungskombinationen lohnen einen erneuten Test mit einer einfacheren Konfiguration, um zu isolieren, welcher Parameter problematisch ist.
Phase 3: Das Polling endet nie
Läuft deine Schleife in einen Timeout statt in einen Fehler, behandle es als Infrastrukturproblem, nicht als Inhaltsproblem. Bestätige, dass du die richtige Aufgaben-ID pollst, das Intervall nicht zu aggressiv ist und die Frist für die angeforderte Dauer ausreicht. Protokolliere die Aufgaben-ID beim Einreichen – ohne sie kannst du eine hängende Aufgabe gar nicht untersuchen.
Ein effektiver Debug-Ablauf
Wenn etwas schiefgeht, gehe in dieser Reihenfolge vor: das Bild lokal validieren, erneut einreichen und die Rohantwort erfassen, bei einem Aufgabenfehler diesen prüfen und dann die Optionen vereinfachen und erneut versuchen. Jeder Schritt testet genau eine Hälfte der Anfrage – deshalb zahlt sich die Trennung von Bild und Generierungsparametern im Code genau dann aus, wenn Fehler auftreten.
Damit hast du den vollständigen Zyklus: Erstbild vorbereiten, Audio, Auflösung und Dauer festlegen, asynchron einreichen und bis zum Abschluss pollen – ob mit curl oder Python ausgeführt, stets dieselbe Anfrage.
Ä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