Tutorial
So rufen Sie wan2.7-video Text-zu-Video über die HiAPI API auf: curl und Python
Auf dieser Seite
Was Sie in diesem Tutorial erstellen werden
Nach dem Lesen dieses Leitfadens verfügen Sie über eine funktionierende kleine Pipeline: Sie übermitteln über die HiAPI API einen Text-zu-Video-Auftrag an wan2.7-video/text-to-video – einmal mit curl und einmal mit Python – und warten dann, bis die Videogenerierung abgeschlossen ist.
Beide Aufrufe sind bewusst äquivalent gestaltet. Die curl-Version ist die Referenzimplementierung, die Sie in ein Terminal einfügen können, um zu prüfen, ob Anmeldedaten und Anfragekörper korrekt sind. Die Python-Version kapselt dieselbe Anfrage in eine Funktion, die sich leicht in Skripte oder Dienste einbetten lässt, und enthält Polling, Fehlerbehandlung sowie sinnvolle Standardwerte.
Da die Videogenerierung deutlich langsamer ist als Chat-Completions, ist der gesamte Ablauf asynchron: Sie übermitteln einen Auftrag, erhalten eine Kennung und fragen dann ab, bis der Auftrag einen Endzustand meldet. Der Rest dieses Textes ist um diesen Lebenszyklus herum organisiert, sodass die Gesamtstruktur auch dann weiterhin gilt, wenn Sie später auf Bild-zu-Video oder andere Videomodelle derselben Endpunktfamilie umsteigen.
Bevor Sie die erste Anfrage senden
Für einen erfolgreichen ersten Aufruf müssen zunächst drei Voraussetzungen erfüllt sein.
Anmeldedaten
Sie benötigen einen HiAPI-API-Schlüssel, der über den Authorization-Header als Bearer-Token gesendet wird. Bewahren Sie ihn in einer Umgebungsvariable auf und schreiben Sie ihn nicht in den Quellcode:
export HIAPI_API_KEY="your-key-here"
Bekannter Modellbezeichner
Der Modellbezeichner ist eine exakte Zeichenkette. In diesem Tutorial lautet der Wert wan2.7-video/text-to-video – einschließlich des Aufgabensuffixes. Ähnliche Schreibweisen wie wan2.7-video oder wan2.7/text-to-video werden abgelehnt. Kopieren Sie den Bezeichner daher aus der Modellliste und schreiben Sie ihn nicht aus dem Gedächtnis.
Ein bewertbarer Prompt
Das iterative Verfeinern der Videogenerierung ist teuer. Schreiben Sie vorab einen konkreten Prompt (Subjekt, Aktion, Kamerabewegung, Beleuchtung, Stil), damit Sie bei der Rückkehr der Ergebnisse beurteilen können, ob Sie die Einstellungen oder die Formulierung anpassen müssen.
Außerdem benötigen Sie einen HTTP-Client und eine Möglichkeit, JSON zu lesen. Auf der Shell-Seite verwenden Sie curl plus jq; auf der Skriptseite Python plus requests.
Struktur des Anfragekörpers
Eine Text-zu-Video-Anfrage ist ein JSON-Objekt, dessen Felder sich in drei Gruppen einteilen lassen.
Identität
model– der exakte Modellbezeichner, alsowan2.7-video/text-to-video.
Inhalt
prompt– der Text, der das gewünschte Video beschreibt. Dies ist das maßgebliche Feld; beschreiben Sie konkret Bewegung, Bildkomposition und Stil, statt Adjektive zu häufen.negative_prompt– optional. Beschreibt, was nicht erscheinen soll. Nützlich zur Unterdrückung häufiger Artefakte, aber kein Ersatz für einen gut geschriebenen Prompt.
Generierungseinstellungen
duration– die Länge des Ausgabesegments.resolution– die Größen-/Auflösungsstufe der Ausgabe.seed– optional. Legen Sie ihn fest, wenn Sie zwei Prompts oder zwei Einstellungsänderungen von einem stabilen Ausgangspunkt aus vergleichen möchten.
Ein minimaler Anfragekörper benötigt nur model und prompt; die Plattform wendet für die übrigen Felder Standardwerte an. Standardwerte sind jedoch nicht Ihre Entscheidungen – warum Sie sie in der Produktion explizit setzen sollten, erfahren Sie im Abschnitt zu Dauer und Auflösung weiter unten.
Halten Sie den Anfragekörper flach und überschaubar. Nur Felder zu verschachteln, die tatsächlich Unterobjekte sind, macht Anfragen lesbarer und Schemafehler leichter erkennbar.
Aufgabe mit curl übermitteln
Nachfolgend ein vollständiges Übermittlungsbeispiel. Der Endpunkt nimmt JSON entgegen und gibt eine Aufgabenkennung statt des Videos selbst zurück.
curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-video/text-to-video",
"prompt": "Langsame Kamerafahrt durch eine regenasse Neon-Gasse bei Nacht, reflektierende Pfützen am Boden, geringe Schärfentiefe, filmisches Color Grading",
"duration": 5,
"resolution": "720p"
}'
Nach erfolgreicher Übermittlung wird ein Objekt mit Aufgaben- bzw. Job-Kennung und Status zurückgegeben. Die Struktur sieht ungefähr so aus:
{
"id": "job_abc123",
"status": "queued",
"model": "wan2.7-video/text-to-video"
}
Zwei Dinge sind zu beachten. Erstens ist status nicht succeeded – zu diesem Zeitpunkt wurde noch nichts gerendert. Zweitens enthält die Antwort keine Video-URL. Diese URL erscheint erst, wenn der Auftrag einen Endzustand erreicht hat.
Wenn Sie die Kennung für den Polling-Schritt in der Shell-Sitzung behalten möchten:
JOB_ID=$(curl -s -X POST "$HIAPI_BASE_URL/v1/video/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | jq -r '.id')
echo "$JOB_ID"
Den Anfragekörper nach payload.json auszulagern hält den Befehl kurz und erleichtert es, den Prompt zwischen mehreren Läufen anzupassen.
Aufgabe mit Python übermitteln
Die Python-Version ist dieselbe Anfrage, nur komfortabler. Was bei curl ein Header oder ein JSON-Schlüssel ist, wird hier zum Schlüsselwortargument.
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",
}
payload = {
"model": "wan2.7-video/text-to-video",
"prompt": (
"Langsame Kamerafahrt durch eine regenasse Neon-Gasse bei Nacht, "
"reflektierende Pfützen am Boden, geringe Schärfentiefe, filmisches Color Grading"
),
"duration": 5,
"resolution": "720p",
}
resp = requests.post(
f"{BASE_URL}/v1/video/generations",
headers=HEADERS,
json=payload,
timeout=30,
)
resp.raise_for_status()
job = resp.json()
print(job["id"], job["status"])
Die Entsprechung zur Shell-Version ist eins zu eins:
-H "Authorization: ..."→ DictionaryHEADERS.-d '<json>'→json=payload. Ein Dictionary statt einer Zeichenkette zu übergeben bedeutet, dassrequestsdie Serialisierung übernimmt und daher kein fehlerhaftes JSON versehentlich gesendet wird.- Das mit
jqextrahierte.id→job["id"].
Zwei Python-spezifische Gewohnheiten lohnt es sich, gleich jetzt zu etablieren. Setzen Sie für den Übermittlungsaufruf immer ein timeout – die Anfrage ist klein und sollte schnell zurückkehren; ein langes Hängen bedeutet daher ein Verbindungsproblem und nicht das Rendern. Und rufen Sie raise_for_status() auf, bevor Sie den Antwortkörper lesen, damit ein Fehler auf HTTP-Ebene einen klaren Traceback liefert statt eines verwirrenden KeyError bei job["id"].
Asynchrone Aufgaben und Polling behandeln
Das Polling ist der Teil, an dem die meisten Integrationen entweder robust oder instabil werden. Aufgaben haben einen Lebenszyklus – üblicherweise in der Warteschlange, in Bearbeitung und dann erfolgreich oder fehlgeschlagen als Endzustand – und Ihre Schleife muss alle drei Fälle behandeln.
def wait_for_job(job_id, interval=5, max_attempts=120):
url = f"{BASE_URL}/v1/video/generations/{job_id}"
for attempt in range(max_attempts):
r = requests.get(url, headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "succeeded":
return data
if status in ("failed", "cancelled"):
raise RuntimeError(f"Job {job_id} ended as {status}: {data.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Job {job_id} still not finished after {max_attempts} polls")
In dieser Schleife gibt es einige Designpunkte, die wichtiger sind, als sie scheinen:
Endzustände explizit prüfen. Jeden Status außer succeeded als „weiter warten“ zu behandeln bedeutet, dass fehlgeschlagene Aufgaben stillschweigend Ihr gesamtes Polling-Budget aufbrauchen. Prüfen Sie auf Fehlerzustände und werfen Sie eine Ausnahme.
Das Polling-Intervall bewusst wählen. Das Rendern von Videos dauert Dutzende Sekunden bis Minuten. Alle 200 Millisekunden abzufragen erhöht nur die Last und liefert keine neuen Informationen. Beginnen Sie mit etwa 5 Sekunden; wenn Aufgaben häufig sehr lange laufen, erhöhen Sie das Intervall statt die Anzahl der Versuche.
Die Schleife immer begrenzen. Eine Obergrenze für max_attempts verwandelt ein endloses Hängen in einen diagnostizierbaren TimeoutError. Protokollieren Sie außerdem die Aufgaben-ID – die benötigen Sie bei der Fehlersuche.
Ratenlimits einhalten. Wenn Sie Stapel übermitteln, senden Sie nicht alle Polling-Anfragen gleichzeitig. Ein gemeinsamer Poller, der in festen Abständen läuft, oder eine einfache clientseitige Drosselung halten Sie innerhalb der Limits.
Bei Erfolg enthält die Antwort den Speicherort des fertigen Assets. Laden Sie es sofort herunter und behandeln Sie den Aufgaben-Datensatz nicht als dauerhaften Speicher.
Dauer und Auflösung wählen
Diese beiden Einstellungen beeinflussen die Ausgabe stärker als jeder andere Parameter, und beide wirken sich auf die Laufzeit der Aufgabe und die Kosten aus. Die Abrechnung erfolgt nach Ausgabesekunden, und die Auflösung bestimmt den Aufwand pro Sekunde – betrachten Sie daher beide als bewusste Entscheidungen für Ihren konkreten Anwendungsfall und nicht als Felder, die man auf Standardwerten belassen kann.
Dauer
Längere Segmente geben der Bewegung Raum zur Entfaltung, aber jede zusätzliche Sekunde bedeutet mehr Rendering und höhere Kosten, und lange Generierungen neigen eher zu Kohärenzproblemen. Praktische Empfehlungen:
- Kurz (wenige Sekunden) – Social-Media-Loops, Produkt-Keyvisuals, B-Roll. Am günstigsten zu iterieren und am leichtesten zu beurteilen.
- Mittel – narrative Akzente, Establishing Shots.
- Lang – nur verwenden, wenn die Geschichte es wirklich erfordert. Wenn Sie ein langes Video benötigen, erwägen Sie, mehrere kurze Segmente zu generieren und diese im Schnitt zu kombinieren; das ist oft günstiger als ein einzelnes langes Rendering und gibt Ihnen mehr Kontrolle.
Während der Prompt-Iteration sollten Sie das kürzestmögliche Segment generieren, das das Modell zulässt. Beurteilen Sie bei dieser Länge Bildkomposition und Bewegung und verlängern Sie erst, wenn Sie zufrieden sind.
Auflösung
Höhere Auflösung bedeutet mehr Pixel pro Frame, längere Renderzeiten und höhere Kosten. Auf kleinen Bildschirmen ist sie jedoch weniger wichtig, als Sie vielleicht denken. Eine 1080p-Masterversion eignet sich für die Lieferung an Kunden; ein 720p-Entwurf (oder niedriger) genügt, um zu beurteilen, ob ein Prompt funktioniert.
Das effiziente Muster ist ein zweistufiger Workflow: Prompt und Dauer in niedriger Auflösung festlegen und dann den finalen Auftrag in Lieferauflösung erneut ausführen. Iterieren Sie nicht mit der höchsten Einstellung – Sie geben den Großteil Ihres Budgets für verworfenes Material aus.
Häufige Fehler beheben
Die meisten Fehler entstehen durch die Art und Weise, wie die Anfrage aufgebaut ist, nicht durch das Modell selbst. Bevor Sie Schlüsse über die Fähigkeiten des Modells ziehen, prüfen Sie die folgenden Problemklassen der Reihe nach.
401 / 403 – Probleme mit den Anmeldedaten
Prüfen Sie, ob der Schlüssel in der Umgebung gesetzt ist, die der Prozess tatsächlich sieht (ein in einer Shell exportierter Schlüssel ist für einen systemd-Dienst nicht sichtbar), ob der Header Authorization: Bearer <key> lautet und ob die Variable keine abschließenden Leerzeichen enthält. Geben Sie beim Debuggen nur die ersten Zeichen des Schlüssels aus, niemals den vollständigen Schlüssel.
404 – Falscher Pfad oder falsches Modell
Der Endpunktpfad und der Modellbezeichner sind zwei verschiedene Dinge, und beide müssen exakt stimmen. Überprüfen Sie die URL, an die Sie POSTen, und stellen Sie sicher, dass wan2.7-video/text-to-video zeichengenau aus der Modellliste kopiert wurde. Ein gültiger Schlüssel mit einer falschen Modellzeichenkette liefert weiterhin einen not-found-ähnlichen Fehler.
400 – Fehlerhaft formatierter Anfragekörper
Dies ist die häufigste Kategorie. Zu den üblichen Ursachen gehören: numerische Felder wie duration, die als Zeichenkette "5" gesendet werden, Prompts, die als Liste statt als Zeichenkette gesendet werden, oder ein Anfragekörper, der versehentlich doppelt kodiert wurde. Die schnellste Triage besteht darin, denselben curl-Befehl erneut zu senden – wenn der Shell-Aufruf gelingt und der Python-Aufruf fehlschlägt, liegt das Problem in der Art, wie das Skript das Dictionary aufbaut, und nicht in der Anfrage selbst.
422 / Validierungsfehler
Syntaktisch gültig, aber semantisch problematisch: Die Dauer liegt außerhalb des unterstützten Bereichs, eine unbekannte Auflösungsstufe wurde angegeben oder ein Pflichtfeld fehlt. Lesen Sie die Fehlermeldung – sie benennt in der Regel das problematische Feld.
Aufgabe schlägt nach der Übermittlung fehl
Der Übermittlungsaufruf ist erfolgreich, aber das Rendering ist nicht gelungen. Dies kann eine Ablehnung durch die Inhaltsrichtlinien oder ein vorübergehender Rendering-Fehler sein. Protokollieren Sie die Aufgaben-ID und die Fehlernutzlast; wenn es sich um ein vorübergehendes Problem handelt, ist das erneute Senden derselben Nutzlast ein sinnvoller erster Schritt. Tritt dasselbe bei demselben Prompt wiederholt auf, ändern Sie die Prompt-Formulierung oder die Generierungseinstellungen, statt dieselbe Anfrage wiederholt zu wiederholen.
Polling endet nie
Wenn ein Auftrag deutlich länger als vergleichbare Aufgaben im Status „in Bearbeitung“ verweilt, stellen Sie das Polling ein, protokollieren Sie die Aufgaben-ID und behandeln Sie ihn als fehlgeschlagene Aufgabe. Langschwänzige Fälle sind selten genug, dass ein begrenztes Timeout mit klarer Fehlermeldung besser ist als eine offene Schleife.
Beginnen Sie bei jedem neuen Problem mit der curl-Referenzimplementierung: Sie nimmt Ihren Code aus der Gleichung und isoliert so, ob das Problem in der Anfrage oder im Client liegt.
Ä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