So verwendest du seedance-2.0-fast über die hiapi API: curl, Python und ein lauffähiger Request

Dieser Leitfaden zeigt den minimalen Request zum Erzeugen eines Videos mit seedance-2.0-fast, alle Eingabefelder, die das Modell tatsächlich akzeptiert, und wie du per Polling oder Callback auf das Ergebnis wartest. Jede unten gezeigte Request-Struktur und Fehlermeldung wurde gegen die echte API verifiziert, sodass du den Code direkt übernehmen kannst.

Was du baust und was du vorbereiten musst

Das Ziel ist einfach: einen Text-Prompt senden und eine herunterladbare MP4-URL zurückbekommen. seedance-2.0-fast ist die geschwindigkeitsoptimierte Variante von Seedance 2.0 – sie tauscht die maximale Auflösung (Deckel bei 720p) gegen schnellere Generierung und eignet sich damit ideal für Vorschauen, Iterationsschleifen und große Mengen kurzer Videoclips.

Du brauchst nur eines: einen hiapi API-Schlüssel. Hole ihn dir in deinem Dashboard; sein Format sieht wie sk-... aus. Alle Videomodelle (auch dieses) laufen über den einheitlichen asynchronen Task-Endpunkt: Du POST /v1/tasks, um einen Task anzulegen, und holst das Ergebnis dann über die Task-ID ab. Für Videos gibt es keinen synchronen Modus.

Den aktuellen Preis pro Clip findest du auf der Preisseite (das Modell ist gerade erst gestartet, also verlasse dich auf diese Seite und nicht auf beliebige Zahlen aus Blogartikeln).

Minimales lauffähiges Beispiel (curl)

Task anlegen:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "input": {
      "prompt": "A paper boat drifts down a rain-soaked street at dusk, cinematic, slow dolly-in",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

Die Task-ID in der Antwort steht unter data.taskId:

{
  "data": {
    "taskId": "task_abc123..."
  }
}

Frage diesen Task ab, bis der Status einen Endzustand erreicht:

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

Wenn data.status gleich "success" ist, steht die Video-URL unter data.output[0].url. Diese URL ist signiert und läuft ab – lade die Datei sofort herunter und verlinke sie nicht per Hotlink:

curl -o clip.mp4 "<the output url>"

Alle Eingabefelder (verifiziert)

Nur prompt ist erforderlich. Jedes Feld, das nicht in dieser Tabelle steht, wird mit 400 abgelehnt – das Schema erlaubt keine zusätzlichen Eigenschaften.

Feld	Typ	Erforderlich	Akzeptierte Werte
prompt	string	Ja	Mindestlänge 3 Zeichen
duration	Ganzzahl	Nein	4–15 (Sekunden)
resolution	string	Nein	480p, 720p
aspect_ratio	string	Nein	1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive

Zwei Punkte verdienen besondere Beachtung:

• duration ist eine Ganzzahl, kein String. Sendest du "duration": "5", schlägt die Validierung mit dem Fehler duration: got string, want integer fehl.
• Es gibt keinen Bildeingang. seedance-2.0-fast unterstützt nur Text-zu-Video; Felder wie image_urls werden vom Schema abgelehnt. Wenn du Bild-zu-Video benötigst, sieh dir die Anleitung zum Bild-zu-Video-API-Workflow an, um Modelle zu finden, die das unterstützen.

Derselbe Ablauf in Python

Kein SDK nötig – requests reicht:

import time
import requests

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

def create_task(prompt: str, duration: int = 5,
                resolution: str = "720p", aspect_ratio: str = "16:9") -> str:
    payload = {
        "model": "seedance-2.0-fast",
        "input": {
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    r = requests.post(API_BASE, json=payload, headers=HEADERS, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task(
    "A barista pours latte art in a sunlit cafe, shallow depth of field"
)
task = wait_task(task_id)
video_url = task["output"][0]["url"]

# The URL is signed and expires — persist the bytes immediately.
with open("clip.mp4", "wb") as f:
    f.write(requests.get(video_url, timeout=120).content)
print("saved clip.mp4")

Behandle jeden Status außer success / fail als "läuft noch" – so bleibt die Schleife robust, selbst wenn sich die Namen der Zwischenzustände künftig ändern.

Hinweise für den Produktivbetrieb

Callbacks statt Polling

Für alles, was über ein Skript hinausgeht, registriere beim Anlegen des Tasks einen Callback und überspringe das Polling ganz:

{
  "model": "seedance-2.0-fast",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.com/hooks/hiapi", "when": "final" }
}

Mit "when": "final" erhält dein Endpunkt genau ein POST, sobald der Task einen Endzustand erreicht. Polling eignet sich für CLI und Notebook; bei hohem Durchsatz sind Callbacks überlegen (keine verschwendeten Requests und keine Verzögerung durch Polling-Intervalle). Falls dein Hook nicht auszulösen scheint, sieh dir die Anleitung zur Fehlersuche bei Callbacks an – fast immer liegt es an der Erreichbarkeit der URL oder daran, dass dein Handler eine Nicht-2xx-Antwort zurückgibt.

Idempotenz

Das Anlegen von Tasks ist nicht kostenlos, also verhindere doppelte Übermittlungen auf deiner Seite: Sorge dafür, dass jedes Geschäftsereignis höchstens einem POST /v1/tasks-Aufruf entspricht (speichere z. B. die taskId zusammen mit deiner Bestell-/Task-Zeile, bevor du es erneut versuchst). Stürzt dein Prozess nach dem Anlegen des Tasks ab, kannst du wiederherstellen, indem du die gespeicherte taskId erneut liest und GET /v1/tasks/<id> fortsetzt – der Task läuft serverseitig weiter, unabhängig davon, ob du pollst oder nicht.

Fehler, die dir tatsächlich begegnen

Symptom	Bedeutung	Behebung
400 mit error_code: "INVALID_REQUEST"	Die Eingabe besteht die Schema-Validierung nicht; message nennt das konkrete Feld, z. B. duration: maximum: got 20, want 15	Korrigiere das Feld; nur die vier Felder aus der Tabelle sind erlaubt
401 mit error.code: "permission_denied"	Der Schlüssel ist ungültig oder gültig, aber für dieses Modell nicht freigeschaltet	Prüfe den Schlüssel im Dashboard; Modellberechtigungen werden pro Schlüssel vergeben
404 mit "task not found" beim GET	Die Task-ID ist falsch oder gehört nicht zu diesem Konto	Verwende die beim Anlegen zurückgegebene taskId und dasselbe Konto
Task-Status ist "fail" mit einem error-Objekt	Die Generierung selbst ist fehlgeschlagen	Lies error.code/error.message; passe den Prompt an und versuche es erneut

Achte auf die zwei Fehlerverpackungen: Validierungsfehler legen message auf die oberste Ebene, während Authentifizierungsfehler unter error verschachtelt sind. Wenn du generische Middleware schreibst, musst du beide Fälle behandeln.

Wofür sich seedance-2.0-fast eignet

Wenn du 1080p- oder 4K-Ausgabe benötigst, verwende stattdessen das vollständige seedance-2.0 – gleicher Endpunkt, gleicher Ablauf, höhere Auflösungsobergrenze (und es verlangt eine explizite Angabe von aspect_ratio). Für einen umfassenderen Vergleich der Seedance-Reihe mit anderen Videomodellen auf der Plattform sieh dir den Videomodell-Vergleich an. Die vollständige Parameterreferenz für jedes Modell findest du in der Dokumentation; die Modellseite verfolgt den aktuellen Stand zu Fähigkeiten und Preisen.

Häufige Fragen

Welche Auflösungen unterstützt seedance-2.0-fast? 480p und 720p. Das ist der Preis für die Geschwindigkeit – das vollständige seedance-2.0 erreicht im gleichen /v1/tasks-Ablauf bis zu 1080p und 4k.

Kann ich mit seedance-2.0-fast Bild-zu-Video machen? Nein. Das Eingabeschema akzeptiert nur prompt, duration, resolution und aspect_ratio; Bildfelder werden mit einem Validierungsfehler abgelehnt. Zu den Bild-zu-Video-Optionen auf hiapi sieh dir die Anleitung zum Bild-zu-Video-Workflow an.

Wie lang kann das erzeugte Video sein? duration akzeptiert Ganzzahlen von 4 bis 15 Sekunden. Werte außerhalb dieses Bereichs scheitern an der Validierung, bevor ein Task angelegt wird (abgelehnte Requests werden nicht berechnet).

Soll ich pollen oder Callbacks verwenden? Für Skripte und geringe Parallelität reicht Polling etwa alle 5 Sekunden. Im Produktivmaßstab übergibst du beim Anlegen callback: {"url": ..., "when": "final"}, damit hiapi den Endzustand an dich pusht – ein Request statt Dutzender.

Warum erhalte ich hier 401 permission_denied, obwohl ein Schlüssel bei anderen Modellen funktioniert? Der Modellzugriff ist pro Schlüssel begrenzt. Ein 401 mit permission_denied bei diesem Modell bedeutet, dass der Schlüssel existiert, aber nicht für seedance-2.0-fast freigeschaltet ist – prüfe die Modellberechtigungen dieses Schlüssels im Dashboard.

Wie lange ist die Ausgabe-URL gültig? Es ist eine signierte URL, die abläuft. Lade die MP4 sofort nach erfolgreichem Task herunter und speichere sie selbst; bette die rohe Ausgabe-URL nirgendwo ein, wo sie langfristig bestehen bleibt.