Blog

Tutorial

So rufen Sie wan2.7-video Text-zu-Video über die HiAPI API auf: curl und Python

Nov 12, 2026
HiAPI-Blogbeitragsbild: Auf tief petrolblauem Grund ein aus flächigen Schnitten gebildetes geometrisches Mineralquerschnittsmuster in Blaugrün- und Malachittönen, matt.
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, also wan2.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: ..." → Dictionary HEADERS.
  • -d '<json>' → json=payload. Ein Dictionary statt einer Zeichenkette zu übergeben bedeutet, dass requests die Serialisierung übernimmt und daher kein fehlerhaftes JSON versehentlich gesendet wird.
  • Das mit jq extrahierte .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 →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen