Kurzvideos mit wan2.7-video/text-to-video@pro erstellen: ein End-to-End-hiapi-API-Workflow

Der Erfolg von Kurzvideos hängt von der Iterationsgeschwindigkeit ab: Du brauchst viele Kandidatenclips, im Hochformat, mit Ton und das schnell. Dieser Leitfaden dreht sich genau darum und nutzt wan2.7-video/text-to-video@pro auf hiapi – das Text-zu-Video-Modell von Alibabas Tongyi Wanxiang 2.7 mit Ausgabe bis 1080P, nativem Audio und Clips von bis zu 15 Sekunden. Jede Anfragestruktur, jede Parametergrenze und jede Fehlermeldung in diesem Artikel wurde beim Verfassen gegen die Live-API getestet, und die beiden eingebetteten Demo-Clips wurden exakt mit dem gezeigten Code erzeugt.

Was das Modell dir bietet

wan2.7-video/text-to-video@pro wird über den einheitlichen asynchronen Task-Endpunkt von hiapi (/v1/tasks) bereitgestellt. Wichtige Merkmale, gegen das Live-Schema verifiziert:

• Ausgabe: H.264 MP4, bis 1080P, mit nativer AAC-Tonspur – das Modell erzeugt passend zu deinem Prompt Umgebungsgeräusche und Soundeffekte, ohne separaten Audioschritt.
• Dauer: 2–15 Sekunden pro Clip (ganzzahlige Sekunden).
• Seitenverhältnisse: 16:9, 9:16, 1:1, 4:3, 3:4 – echtes Hochformat 9:16, passend für Shorts/Reels/TikTok-Formate, ohne Zuschneiden.
• Abrechnung: abgerechnet wird pro Sekunde des ausgegebenen Videos, zum Zeitpunkt des Verfassens ab $0.167/Sekunde – ein 5-Sekunden-1080P-Clip kostet etwa $0.84. Prüfe vor dem Massengenerieren unbedingt die Preisseite.

Für Videos gibt es keinen synchronen Modus: Du musst eine Aufgabe erstellen, bis zur Fertigstellung abfragen und dann das Ergebnis herunterladen.

Minimales lauffähiges Beispiel (curl)

Aufgabe erstellen:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video@pro",
    "input": {
      "prompt": "Makro-Studioaufnahme: Ein Tropfen königsblaue Tinte fällt in klares Wasser, entfaltet sich in Zeitlupe, die Tintenfäden strecken sich zu Wolkenformen, Hintergrund ist ein helles nahtloses Weiß, klares High-Key-Licht, sanftes Umgebungsbrummen",
      "ratio": "16:9",
      "resolution": "1080P",
      "duration": 4
    }
  }'

Antwort:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R"}, "message": "success"}

Ergebnis abfragen:

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGGS29FDZ8NRJW49YRQZ65R" \
  -H "Authorization: Bearer sk-YOUR_KEY"

Während des Renderings ist data.status gleich handling; nach Abschluss wechselt es zu success, und data.output[0].url enthält das MP4. Diese Anfrage hat genau diesen Clip erzeugt:

⚠️ Ausgabe-URLs sind temporäre Links mit einem expireAt-Zeitstempel. Lade die Datei sofort nach erfolgreicher Aufgabe in deinen eigenen Speicher herunter – verlinke sie nicht direkt und speichere sie nicht in einer Datenbank.

Vollständiges Eingabe-Schema (gegen die Live-API verifiziert)

Die API validiert input streng und lehnt unbekannte Felder ab. Hier ist die vollständige Liste der zulässigen Felder – direkt durch Abfragen des Endpunkts ermittelt, nicht von irgendwo kopiert:

Feld	Typ	Einschränkung	Pflichtfeld
prompt	string	Szenenbeschreibung; steuert auch das generierte Audio	✅
ratio	string	eines von 16:9, 9:16, 1:1, 4:3, 3:4	optional
resolution	string	720P oder 1080P	optional
duration	integer	2–15 (Sekunden)	optional
negative_prompt	string	Inhalte, die unterdrückt werden sollen (z. B. Wasserzeichen, Texteinblendungen)	optional
seed	integer	reproduzierbar zwischen Wiederholungen	optional
watermark	boolean	Schaltet das Anbieter-Wasserzeichen um	optional

Zwei Stolperfallen, die dir 400er ersparen:

• Das Feld heißt ratio, nicht aspect_ratio – die Bildmodelle auf hiapi verwenden aspect_ratio, dieses Videomodell nicht. Das Senden von aspect_ratio liefert additional properties 'aspect_ratio' not allowed.
• duration wird serverseitig validiert: duration: minimum: got 1, want 2 und maximum: got 999, want 15 sind die exakten Fehler, die du erhältst, wenn du den Bereich 2–15 verlässt.

End-to-End in Python: Prompt rein, veröffentlichungsfertiges MP4 raus

Das ist der komplette Workflow – erstellen, abfragen, herunterladen – ohne SDK, nur mit requests:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def make_short(prompt: str, out_path: str, duration: int = 5,
               ratio: str = "9:16", seed: int | None = None) -> str:
    payload = {
        "model": "wan2.7-video/text-to-video@pro",
        "input": {
            "prompt": prompt,
            "ratio": ratio,               # 9:16 = vertikales Kurzvideo
            "resolution": "1080P",
            "duration": duration,          # 2..15 Sekunden
            "negative_prompt": "Texteinblendungen, Wasserzeichen, verzerrte Hände",
        },
    }
    if seed is not None:
        payload["input"]["seed"] = seed

    task_id = requests.post(API, headers=HEADERS, json=payload).json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)

    video_url = task["output"][0]["url"]   # temporärer Link – bitte sofort herunterladen
    with open(out_path, "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    return out_path

make_short(
    "Nachtmarkt-Aufnahme in der goldenen Stunde, handgehalten im Hochformat: Ein "
    "Streetfood-Verkäufer schwenkt zischende Nudeln in einem lodernden Wok, Dampf und "
    "orangefarbene Funken wirbeln zur Kamera, Neonreklamen strahlen in weichem Pink und "
    "Türkis im unscharfen Hintergrund, geringe Schärfentiefe, dynamischer dokumentarischer "
    "Handheld-Look, mit Zischen und Knistern",
    "night-market.mp4",
    duration=5,
    seed=20260702,
)

Hier ist der Clip, den dieser Aufruf tatsächlich erzeugt hat – Hochformat 1080×1920, 5 Sekunden, das Zischen entsteht aus dem Prompt-Text:

In meinem Durchlauf war ein 4-Sekunden-16:9-Clip in etwa 3 Minuten fertig, ein 5-Sekunden-9:16-Clip etwas länger – rechne pro Clip mit einigen Minuten, frage etwa alle 10 Sekunden ab und überlaste den Endpunkt nicht.

Tipps für Kurzvideo-Prompts: Bewegung und Audio werden vom Prompt gesteuert

Das Schema hat keine Kamera- oder Bewegungsparameter – alles zu Bewegung, Tempo und Ton wird über die Prompt-Sprache gesteuert. Was sich in meinen Tests bewährt hat:

• Kameraverhalten explizit benennen: etwa "handheld" (handgehalten), "slow push-in" (langsames Heranfahren), "macro" (Makro), "shallow depth of field" (geringe Schärfentiefe). Das dokumentarische Wackeln des Nachtmarkt-Clips kommt allein vom Wort "handheld".
• Beschreibe das gewünschte Audio: Das Modell erzeugt Ton aus dem Prompt. "sizzling and crackling sounds" (Zischen und Knistern) und "gentle ambient hum" (sanftes Umgebungsbrummen) tauchten beide in der Ausgabespur auf.
• Den Hook nach vorne stellen: Bei Kurzvideos entscheidet die erste Sekunde. Setze das dynamischste Element (flammender Wok, Tintentropfen im Wasser) an den Anfang der Prompt-Beschreibung.
• negative_prompt defensiv einsetzen: "text overlay, watermark, distorted hands" (Texteinblendungen, Wasserzeichen, verzerrte Hände) beseitigt die häufigsten Fehler, ohne den Haupt-Prompt zu beeinflussen.
• Beim Iterieren seed fixieren: Seed fixieren, jeweils nur eine Prompt-Formulierung ändern und beobachten, welche Wirkung diese tatsächlich hat.

Brauchst du Kontrolle über das erste Bild? Nutze die Bild-zu-Video-Variante

Wenn dein Workflow mit einem gestalteten Keyframe beginnt – Produktbild, markengerechtes erstes Bild –, akzeptiert Text-zu-Video keine Bildeingabe. Das passende Modell wan2.7-video/image-to-video@pro kann das: Es akzeptiert ein media-Array aus {"url": "...", "type": "image"}-Objekten zusammen mit denselben Feldern prompt / resolution / duration und animiert das von dir gelieferte Bild, statt eines aus dem Nichts zu erzeugen. Derselbe aufgabenbasierte Ablauf, dieselbe Abrechnung pro Sekunde. Eine praktische Pipeline: Erzeuge mit einem Bildmodell ein Standbild, prüfe es und animiere erst dann das freigegebene Bild – so gibst du Videogenerierungskosten nur für bereits abgesegnete Bilder aus.

Häufige Fehler und was sie tatsächlich bedeuten

• invalid input: prompt: missing required field "prompt" – prompt ist das einzige Pflichtfeld.
• invalid input: ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4' – du hast ein vom Modell nicht unterstütztes Seitenverhältnis übergeben (oder dich vertippt).
• invalid input: <root>: additional properties '...' not allowed – unbekanntes Feld; das Schema ist streng, prüfe die Tabelle oben.
• status: "fail" mit TASK_FAILED – die Aufgabe ist nach dem Erstellen fehlgeschlagen; erstelle eine neue Aufgabe (verwende deinen seed erneut, um die Reproduzierbarkeit zu wahren).
• Die heruntergeladene Datei ist klein oder nicht abspielbar – du hast wahrscheinlich eine bereits abgelaufene Ausgabe-URL abgerufen. Prüfe expireAt erneut und lade sofort nach success herunter.

Fazit

Ein POST, eine Abfrageschleife, ein Download – das ist der ganze Weg vom Text-Prompt zum veröffentlichungsfertigen vertikalen MP4 mit Ton. Wenn du eine Kurzvideo-Pipeline baust, hole dir einen API-Key im Dashboard, starte mit der Python-Funktion oben und stöbere im Rest des Modellkatalogs – dasselbe /v1/tasks-Muster (wie in unserem seedance-2.0-fast-Leitfaden gezeigt) gilt für alle Videomodelle der Plattform, sodass ein Modellwechsel später nur eine Zeile kostet.