Tutorial
So verwendest du pixverse-v6-max Image-to-Video über die HiAPI API: curl, Python und eine funktionierende Anfrage
Auf dieser Seite
Was der pixverse-v6-max Image-to-Video-Endpunkt verlangt
Der Endpunkt pixverse-v6-max/image-to-video auf HiAPI ist eine asynchrone, bildkonditionierte Videogenerierungsaufgabe. Dieser eine Satz bestimmt praktisch jede Entscheidung, die du bei der Integration triffst.
Der Endpunkt nimmt ein Quellbild (das erste Frame) sowie eine Reihe von Generierungsparametern entgegen und gibt eine Aufgabenreferenz zurück, kein fertiges Video. Das eigentliche Rendering findet serverseitig statt und kann je nach gewählten Parametern von einigen Sekunden bis zu mehreren Minuten dauern. Dein Client ist dafür verantwortlich, die Aufgabe einzureichen und dann wiederholt ihren Status abzufragen, bis sie einen Endzustand meldet.
Vergleiche das mit synchroner Bildbearbeitung: Bei der synchronen Bearbeitung sendest du einen POST-Request-Body und erhältst das transformierte Bild in derselben HTTP-Antwort. Hier sieht der Ablauf so aus:
POSTdein Bild und die Parameter an den Generierungsendpunkt.- Erhalte eine Aufgabenkennung (meist zusammen mit einem initialen Status).
GETden Aufgabenstatus in Intervallen, bis die Aufgabe abgeschlossen ist oder fehlschlägt.- Lies die generierte Video-URL aus dem Antwortkörper der abgeschlossenen Aufgabe.
Durch diese Trennung gibt es zwei verschiedene Fehlerklassen: Probleme in der Einreichungsphase (Authentifizierungsfehler, fehlerhafter Request-Body, abgelehntes Bild) und Probleme in der Ausführungsphase (Aufgabe wird angenommen, schlägt dann aber fehl oder bleibt hängen). Eine gute Integration behandelt beide explizit – die konkrete Checkliste findest du im späteren Abschnitt zur Fehlerbehebung.
Noch etwas solltest du im Hinterkopf behalten: Das Quellbild ist der Anker. Das Modell beginnt die Animation ausgehend von diesem ersten Frame, daher haben Bildqualität, Seitenverhältnis und Inhalt einen größeren Einfluss auf die Ausgabe als jeder Prompt-Text, den du mitgibst. Behandle die Korrektheit des Uploads als vorrangiges Anliegen, nicht als nachträglichen Gedanken.
API-Schlüssel und Endpunkt vorbereiten
Bevor du die erste Anfrage sendest, brauchst du nur zwei Dinge: einen HiAPI-API-Schlüssel und die korrekte Basis-URL für diesen Endpunkt.
Deinen Schlüssel erhalten
Erstelle einen API-Schlüssel in der Konsole deines HiAPI-Kontos. Behandle ihn wie ein Passwort: Lege ihn in einer Umgebungsvariable ab, nicht im Quellcode oder in der Shell-Historie.
export HIAPI_API_KEY="your_key_here"
Wenn du lokal eine .env-Datei verwendest, füge sie zu .gitignore hinzu, bevor du irgendetwas committest. Jeder Schlüssel, der in geteilten Logs, Screenshots oder Repositories auftaucht, sollte sofort rotiert werden.
Basis-URL und Pfad verstehen
Der Endpunkt liegt unter dem HiAPI-API-Host, der Modellpfad lautet pixverse-v6-max/image-to-video. In den folgenden Beispielen wird die Basis-URL als https://api.hiapi.ai dargestellt, und der vollständige Pfad wird daraus zusammengesetzt. Wenn dein Konto oder deine Region dir einen anderen Host gibt, ersetze ihn konsequent – eine Nichtübereinstimmung von Host und Schlüssel ist eine der häufigsten Ursachen für 401, was Entwickler oft fälschlich für einen „ungültigen Schlüssel“ halten.
Wähle dein Werkzeug
- curl für eine erste schnelle Verifikation – es schließt alle Variablen außer der Anfrage selbst aus.
- Python 3 mit
requests(oderhttpx) für die eigentliche Integration.
python3 -c "import requests; print(requests.__version__)"
Wenn eine Versionsnummer ausgegeben wird, bist du bereit. Die Beispiele in diesem Artikel benötigen kein SDK; alles ist reines HTTP, was auch bedeutet, dass du es später in jede Sprache portieren kannst. Sobald Schlüssel und Host bestätigt sind, kannst du mit dem Aufbau der Anfrage beginnen.
Anfrage mit curl aufbauen
Beginne mit der minimalen Anfrage, die tatsächlich erfolgreich ist, und füge dann Parameter hinzu. Der folgende Request-Body zeigt die Struktur einer vollständigen Image-to-Video-Einreichung.
curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://your-cdn.example.com/first-frame.jpg",
"duration": 5,
"aspect_ratio": "16:9"
}'
Hier passieren drei Dinge:
- Authentifizierung erfolgt über einen Bearer-Token im
Authorization-Header. - Der Request-Body ist JSON, daher wird das Bild als URL-String übergeben (wie du stattdessen eine lokale Datei übergibst, erfährst du im nächsten Abschnitt).
- Zwei Generierungsparameter –
durationundaspect_ratio– sind Felder auf oberster Ebene.
Eine erfolgreiche Einreichung gibt ein JSON-Objekt zurück, das eine Aufgabenkennung enthält. Fange sie ab:
JOB_ID=$(curl -s -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image":"https://your-cdn.example.com/first-frame.jpg","duration":5,"aspect_ratio":"16:9"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "$JOB_ID"
Frage sie dann ab:
curl -s "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Prüfe im Fehlerfall immer das Statusfeld und den rohen Fehler-Response-Body. curl kann bei Exit-Code 0 dennoch Fehler-JSON ausgeben, daher solltest du dich in Skripten nicht nur auf den Exit-Code verlassen.
Das erste Frame-Bild korrekt bereitstellen
Das Quellbild ist der häufigste Fehlerpunkt; nahezu jede Ablehnung lässt sich auf eine von vier Ursachen zurückführen.
1. Das Bild ist nicht erreichbar
Wenn du eine URL übergibst, müssen die HiAPI-Server sie GETen können – aus deren Netzwerk, nicht aus deinem. Eine localhost-URL, ein privater Bucket, eine signierte URL, die nach sechzig Sekunden abläuft, oder ein Endpunkt hinter einem VPN werden fehlschlagen. Verwende eine öffentlich lesbare Object-Storage-URL oder einen CDN-Link und bestätige in einer frischen Browser-Sitzung ohne Cookies, dass er lädt.
2. Das Bildformat wird nicht unterstützt
Bleibe bei Standard-Webformaten – JPEG, PNG, WebP. Dateien mit seltenen Erweiterungen, HEIC aus Handykameras oder animierte GIFs sind riskant. Wenn deine Pipeline ein spezielles Format erzeugt, transkodiere es vorher.
3. Das erste Frame passt nicht zum angegebenen Seitenverhältnis
Das ist subtil. Wenn dein Quellbild quadratisch ist, du aber 16:9 anforderst, muss der Dienst die Eingabe zuschneiden, auffüllen oder ablehnen. Das Verhalten kann variieren, und keines davon ist das, was die meisten Entwickler wollen. Schneide das Bild vor dem Upload selbst zu oder füge schwarze Balken hinzu, sodass die Bildgeometrie bereits dem aspect_ratio entspricht, den du anfordern wirst. Das macht die Ausgabe vorhersagbar und vermeidet eine verschwendete Aufgabe.
4. Das Bild ist zu groß oder zu klein
Sehr hochauflösende Standbilder (z. B. 8K-Kameraausgaben) verbrauchen Bandbreite und können abgelehnt oder herunterskaliert werden; winzige Thumbnails lassen dem Modell kaum etwas zum Animieren. Normalisiere das Bild auf eine sinnvolle lange Kante als Teil eines Vor-Upload-Schritts.
Lokale Dateien übergeben
Wenn der Endpunkt für das Bildfeld Multipart-Uploads akzeptiert, sieht das Muster so aus:
curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-F "image=@./first-frame.jpg" \
-F "duration=5" \
-F "aspect_ratio=16:9"
Beachte, dass numerische Felder bei Multipart zu Strings werden. Prüfe in der Endpunkt-Referenz, welche Content-Types akzeptiert werden, und bevorzuge in Produktions-Pipelines die URL-Form – so bleiben große Binärdateien vollständig von deinem Anwendungsserver fern.
Dauer und Seitenverhältnis festlegen
Diese beiden Felder haben größeren Einfluss auf Kosten und Ausgabe als alles andere im Request-Body.
duration
duration wird in Sekunden angegeben und bezeichnet die Länge des generierten Clips. Es ist auch das Feld mit dem direktesten Bezug zur Abrechnung – die Echtzeitpreisgestaltung basiert auf der angeforderten Ausgabedauer, wähle sie also bewusst und nicht standardmäßig den Maximalwert. Praktische Empfehlungen:
- Beginne mit der kürzesten Dauer, die deine Geschichte erzählt. Fünf-Sekunden-Clips eignen sich hervorragend für Loops, Produktteaser oder Social Hooks.
- Verwende längere Dauern nur, wenn die Einstellung tatsächlich mehr Zeit braucht; ein statisches erstes Frame, das lange animiert wird, driftet oft und verliert an Kohärenz.
- Validiere clientseitig: Lehne Nicht-Integer-, Null-, negative und absurd große Werte ab, bevor die Anfrage deinen Dienst verlässt.
if not isinstance(duration, int) or not 1 <= duration <= 8:
raise ValueError("duration out of supported range")
Bestätige den aktuell unterstützten Bereich in der Endpunkt-Referenz und spiegele ihn in deiner Validierungslogik – hardcode keine Annahmen aus diesem Artikel.
aspect_ratio
aspect_ratio ist ein String wie "16:9", "9:16" oder "1:1". Er steuert die Geometrie des Ausgabebilds.
16:9für Querformat: YouTube, Web-Hero-Videos, Desktop-Wiedergabe.9:16für Hochformat: Reels, Shorts, TikTok-artige Platzierungen.1:1für Feeds und Thumbnails.
Zwei Regeln ersparen dir Ärger. Erstens: Lass das Quellbild zum angeforderten Verhältnis passen – ein Hochformat-First-Frame in einer Querformat-Anfrage führt zu einem Zuschnitt, den du wahrscheinlich nicht willst. Zweitens: Behandle das Verhältnis als Enum, nicht als Freitext: Validiere gegen eine Whitelist, damit ein Tippfehler wie "16x9" schnell in deinem Code fehlschlägt statt erst nach einem Roundtrip.
Alles andere
Wenn der Endpunkt zusätzliche Generierungssteuerungen bereitstellt, lass sie aus deiner ersten Anfrage heraus. Ein minimaler, verifiziert funktionierender Request-Body ist deine Baseline; füge jeweils nur einen Parameter hinzu und vergleiche die Ausgabe. Diese Disziplin macht sofort ersichtlich, welches Feld eine Regression verursacht hat.
Dieselbe Anfrage in Python implementieren
Das Folgende ist die Python-Übersetzung des curl-Ablaufs. Die Abhängigkeiten sind bewusst schlank gehalten: requests plus die Standardbibliothek.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit(image_url: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
resp = requests.post(
f"{BASE}/v1/pixverse-v6-max/image-to-video",
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": image_url, "duration": duration, "aspect_ratio": aspect_ratio},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def fetch(job_id: str) -> dict:
resp = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
job_id = submit("https://your-cdn.example.com/first-frame.jpg")
print("submitted", job_id)
Einige bewusste Entscheidungen, die es sich zu übernehmen lohnt:
raise_for_status()beim Einreichen aufrufen.400oder401sollten sofort als Exception sichtbar werden, nicht alsKeyError, wenn du versuchst,["id"]aus dem Fehler-Response-Body zu lesen.- Explizite Timeouts. Ohne Timeout hängt eine stockende Verbindung deinen Worker unbegrenzt auf.
- Konfiguration aus der Umgebung lesen. Basis-URL und Schlüssel werden nie im Code hartkodiert.
- Kleine, typisierte Hilfsfunktionen.
submitgibt den Aufgaben-ID-String zurück;fetchgibt ein Dict zurück. Parsing an einer Stelle zu zentralisieren bedeutet, dass eine Schemaänderung nur eine Zeile kostet.
Wenn du httpx bevorzugst, ersetze es durch httpx.post(...) und httpx.get(...); die Aufrufe sind ansonsten identisch. Für alles, was in einem Web-Request-Handler läuft, reiche hier ein und übergib die Aufgaben-ID an einen Hintergrund-Worker, anstatt den HTTP-Request des Nutzers auf die Videogenerierung warten zu lassen.
Die asynchrone Aufgabe bis zum Abschluss abfragen
Das Polling ist der Teil, den die meisten Tutorials übergehen und der die meisten Vorfälle verursacht. Die Schleife selbst ist kurz; die Disziplin drumherum ist entscheidend.
def wait_for_video(job_id: str, timeout: int = 600, interval: int = 5) -> str:
deadline = time.time() + timeout
while time.time() < deadline:
job = fetch(job_id)
status = job.get("status")
if status == "completed":
return job["output"]["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"job {job_id} ended as {status}: {job.get('error')}")
time.sleep(interval)
raise TimeoutError(f"job {job_id} did not finish within {timeout}s")
Die wichtigsten Punkte, die oben kodiert sind:
- Immer eine Deadline setzen. Videogenerierung ist langsam; eine unbegrenzte Schleife wird zu unbegrenzten Kosten und hängenden Workern. Zehn Minuten sind eine vernünftige Obergrenze für kurze Clips – passe sie an deine Dauereinstellung an.
- Endzustände unterscheiden. Nur
completedliefert eine URL.failedundcancelledsind ebenfalls Endzustände – höre auf zu pollen und lege das error-Feld offen. - Ein vernünftiges Intervall verwenden. Alle paar Sekunden reicht aus. Den Status-Endpunkt zu hämmern führt zu Rate-Limits und liefert dir keine neuen Informationen.
- Sanftes Backoff für lange Aufgaben: Erhöhe das Intervall nach der ersten Minute von 3 Sekunden auf 10 Sekunden. Das reduziert die Last, ohne dir zusätzliche Latenzkosten zu verursachen.
- Aufgaben-IDs persistieren. Speichere sie zusammen mit deinen eigenen Datensätzen, damit du nach einem Prozess-Neustart das Polling wieder aufnehmen kannst, ohne dieselbe Aufgabe erneut einzureichen – und erneut zu bezahlen.
- Niemals direkt aus dem Browser mit deinem API-Schlüssel pollen. Proxy die Statusprüfung über dein Backend.
Wenn eine Aufgabe abgeschlossen ist, lade das Video zeitnah in deinen eigenen Speicher herunter, anstatt für immer auf die zurückgegebene URL zu verlinken; generierte Asset-URLs sind nicht garantiert dauerhaft gültig.
Fehlgeschlagene und hängende Aufgaben beheben
Arbeite diese Checkliste der Reihe nach ab. Jeder Schritt isoliert eine Ebene.
Einreichungsfehler (Aufgabe nie erstellt)
401 Unauthorized– Der Schlüssel fehlt, ist falsch formatiert, wurde widerrufen oder mit dem falschen Host kombiniert. Prüfe, ob der Header genauAuthorization: Bearer <key>lautet, mit genau einem Leerzeichen dazwischen und ohne überflüssige Zeilenumbrüche in der Umgebungsvariable.403 Forbidden– Der Schlüssel ist gültig, aber für dieses Modell oder diesen Endpunkt nicht erlaubt. Prüfe den Ressourcenpfad Zeichen für Zeichen:pixverse-v6-max/image-to-video.400 Bad Request– Dein JSON ist fehlerhaft formatiert oder ein Feld ist ungültig. Dekodiere den Fehler-Response-Body; er benennt normalerweise das problematische Feld. Häufige Ursachen:durationist ein String statt einer Zahl,"16x9"statt"16:9", fehlendesimage.422-artige Validierungsfehler – Das Feld ist vorhanden, liegt aber außerhalb des Bereichs. Prüfe die Endpunkt-Referenz, statt zu raten.429 Too Many Requests– Du reichst zu schnell ein. Stelle Einreichungen in eine Warteschlange und wiederhole sie mit exponentiellem Backoff und Jitter; wiederhole niemals in einer engen Schleife.
Ausführungsfehler (Aufgabe erstellt, aber nicht erfolgreich)
- Status
failedmit einem bildbezogenen Fehler – Der Abruf der Quell-URL ist nach der Einreichung fehlgeschlagen. Das ist die klassische „funktioniert in meinem Browser“-Falle: Die URL benötigt ein Cookie, einen Referrer oder eine IP-Whitelist. Stelle das Bild öffentlich neu bereit. - Status
failedmit einem Inhalts- oder Validierungsfehler – Das Quellbild wurde aus technischen Gründen abgelehnt (Format, Geometrie, Größe). Transkodiere, skaliere und schneide es erneut auf das angegebene Seitenverhältnis zu. - Aufgabe bleibt nach deiner Deadline im Status „queued“ oder „processing“ hängen – Bestätige zunächst, dass du die richtige Aufgaben-ID liest (Copy-Paste-Fehler sind überraschend häufig). Prüfe dann, ob sich der Status tatsächlich nicht geändert hat oder ob dein Polling die falsche Basis-URL getroffen hat. Wenn sie wirklich hängt, brich sie ab und reiche sie einmal erneut ein, sofern die API das erlaubt; wiederholtes stilles erneutes Einreichen ist genau die Art, wie Budgets verschwinden.
Eine zeitsparende Gewohnheit
Protokolliere bei jedem Aufruf die vollständige Request-ID, Aufgaben-ID, den HTTP-Status und den Response-Body – und maskiere den Schlüssel. Wenn um zwei Uhr morgens etwas schiefgeht, ist eine Request-ID der Unterschied zwischen einer Fünf-Minuten-Reparatur und einer Stunde Rätselraten. Beginne mit dem minimalen, verifiziert funktionierenden Request-Body und füge jeweils nur einen Parameter hinzu, dann brauchst du diese Checkliste kaum überhaupt.
Ä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