Blog

Tutorial

So rufen Sie seedance-2.5-flash Text-zu-Video über die HiAPI-API auf (curl und Python)

Ein praxisorientierter Durchlauf für Entwickler: Endpunkt, Parameter, asynchrone Task-Verarbeitung sowie lauffähige curl- und Python-Beispiele

Nov 19, 2026
Titelbild: Auf tief indigoblauem Grund schieben sich ineinander verschachtelte breite Pfeile mit pfirsichfarbener Vorderkante stufenweise vorwärts und bilden eine geometrische Komposition wie ein Signalfluss.
Auf dieser Seite

Was seedance-2.5-flash/text-to-video für Sie bereitstellt

seedance-2.5-flash/text-to-video ist ein Endpunkt zur Text-zu-Video-Generierung auf der HiAPI-API. Sie senden einen Text-Prompt, der die gewünschte Szene beschreibt, und das Modell liefert das generierte Video zurück. Die Vereinbarung ist so einfach: Text rein, Video raus.

Da die Videogenerierung länger dauert als eine typische Chat-Completion, ist dieser Endpunkt asynchron. Ein einzelner Aufruf blockiert nicht, bis das Video fertig ist, sondern erstellt einen Generierungs-Task, dessen Ergebnis Sie abrufen, sobald der Task einen Endzustand erreicht hat. Wenn Sie schon einmal eine Media-API mit langer Laufzeit integriert haben, wird Ihnen diese Form vertraut vorkommen: absenden, Task-ID speichern, Ergebnis abrufen.

Die Integration auf Ihrer Seite besteht daher aus drei Dingen: eine gültige Submit-Anfrage erstellen, die Task-ID persistent speichern und das fertige Video zuverlässig abrufen. Dieses Tutorial führt Sie mit lauffähigem curl- und Python-Code durch diese drei Schritte und behandelt dann Parameterprüfung, die Abwägung zwischen Polling und Callback sowie die Fehlermuster, auf die die meisten Erstintegrationen stoßen.

Wenn Sie eine Pipeline bauen, die Prompts programmatisch in kurze Videoclips umwandelt – Content-Tools, Prototyp-Backends oder interne Generierungsdienste –, ist dieser Leitfaden für Sie geeignet. Wenn Sie eine synchrone Antwort benötigen oder statt Videogenerierung Bildgenerierung suchen, ist ein anderer Endpunkt besser geeignet. Wenn dies Ihrem Anwendungsfall entspricht, lesen Sie weiter zu den Voraussetzungen.

Voraussetzungen und Abrufen des API-Keys

Bevor Sie die erste Anfrage senden, bestätigen Sie drei Dinge.

HiAPI-Konto und API-Key

Alle Anfragen an diesen Endpunkt werden mit einem API-Key authentifiziert, der an Ihr HiAPI-Konto gebunden ist. Erstellen Sie den Key im Konto-Dashboard und vermeiden Sie es, ihn in die Versionsverwaltung einzuchecken. Die folgenden Beispiele lesen ihn aus einer Umgebungsvariable, sodass Sie ihn direkt in das Terminal oder Skript einfügen können, ohne den Schlüssel inline zu bearbeiten:

export HIAPI_API_KEY="your_api_key_here"

Ein Client, der HTTPS-Anfragen senden kann

Für den curl-Teil benötigen Sie curl, das auf macOS und den meisten Linux-Distributionen vorinstalliert ist. Für den Python-Teil benötigen Sie Python 3 und die Bibliothek requests (pip install requests). Ein herstellerspezifisches SDK ist nicht erforderlich – der Endpunkt ist reines HTTPS mit JSON-Body, sodass jeder HTTP-Client verwendet werden kann, von Node's fetch bis zu Pythons httpx.

Eine Möglichkeit, Zustand zwischen Anfragen zu speichern

Da die Generierung asynchron ist, benötigen Sie einen Ort, an dem Sie die vom Submit-Aufruf zurückgegebene Task-ID speichern – eine Datenbankzeile, eine Task-Queue, eine JSON-Datei während des Testens. Wenn Sie statt Polling einen Callback verwenden möchten, benötigen Sie außerdem einen HTTPS-Endpunkt, der für HiAPI erreichbar ist.

Mit dem Key und einem funktionsfähigen Client können Sie die Anfrage absenden.

Die erste funktionsfähige Anfrage mit curl senden

Der Submit-Aufruf ist ein POST mit einem JSON-Body. Der genaue Endpunktpfad und der Name des Authentifizierungs-Headers sind auf der Modellseite dokumentiert – verwenden Sie diese Werte unverändert und leiten Sie sie nicht von anderen APIs ab. Der Aufruf sieht folgendermaßen aus:

curl -X POST "$HIAPI_BASE_URL/v1/models/seedance-2.5-flash/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
  }'

Einige Anmerkungen zu den einzelnen Teilen:

  • Methode und Pfad. POST erstellt einen neuen Generierungs-Task. Der Pfad identifiziert das Modell; bestätigen Sie ihn auf der Modellseite, bevor Sie ihn in Ihre eigene Konfiguration kopieren.
  • Header. Der Authorization-Header trägt Ihren Key, Content-Type: application/json teilt dem Server mit, wie der Body zu parsen ist.
  • Body. Mindestens muss ein prompt-String gesendet werden. Der Prompt ist die kreative Eingabe – alles, was das Modell rendert, stammt daraus, daher sollten Sie Subjekt, Bewegung, Beleuchtung und Kameraführung explizit angeben.

Wenn die Anfrage akzeptiert wird, enthält die Antwort ein Task-Objekt. Sie erhalten nicht sofort eine Video-URL. Extrahieren Sie die Task-ID aus der Antwort und speichern Sie sie. Die genauen Feldnamen sind Teil des auf der Modellseite dokumentierten Antwortschemas; betrachten Sie diese als einzige Wahrheitsquelle und hardcodieren Sie keine Vermutungen in Ihren Client, bevor Sie eine echte Antwort gesehen haben.

Sie können zunächst mit curl die Rohantwort prüfen und dann denselben Aufruf in den Code übernehmen, nachdem Sie ihre Form verstanden haben.

Parameter auswählen: Prompt, Auflösung und Dauer

Nur prompt ist zwingend erforderlich, aber mehrere optionale Parameter bestimmen das Ausgabeergebnis und die Kosten der Anfrage. Legen Sie diese bewusst fest, statt blind die Standardwerte zu akzeptieren.

Prompt

Der Prompt ist der Parameter mit dem größten Einfluss. Schreiben Sie ihn wie ein Briefing an einen Kameramann: Subjekt, Aktion, Umgebung, Beleuchtung und Kamerastil. "A cyclist weaving through a neon-lit Tokyo street at night, handheld camera, shallow depth of field" vermittelt dem Modell viel mehr Informationen als "a city". Halten Sie den Prompt innerhalb der auf der Modellseite dokumentierten Längenbegrenzung.

Auflösung

Eine höhere Auflösung bedeutet mehr Details und größere Ausgabedateien, möglicherweise auch längere Generierungszeiten. Die Videogenerierung wird üblicherweise nach Ausgabedauer abgerechnet, aber prüfen Sie die aktuelle Abrechnungsgrundlage und etwaige Auflösungsstufen im Preispanel und in der Modelldokumentation, statt Annahmen zu treffen. Wählen Sie die niedrigste Auflösung, die Ihr Lieferziel erfüllt – nachträgliches Upscaling ist oft günstiger, als alles in höchster Qualität zu generieren.

Dauer

Die Dauer bestimmt, wie viele Sekunden Video das Modell generiert, und beeinflusst in der Regel sowohl Latenz als auch Kosten. Kürzere Clips eignen sich besser zum Iterieren: Verfeinern Sie den Prompt bei kürzerer Dauer, bis die Bewegung stimmt, und generieren Sie dann mit der endgültigen Länge neu.

Validierung vor dem Senden

Bevor Sie Werte in Produktionscode übernehmen, prüfen Sie auf der Modellseite die zulässigen Bereiche für jeden Parameter – erlaubte Dauern, unterstützte Auflösungen und etwaige Enum-Werte. Validieren Sie dann clientseitig: Lehnen Sie Dauern außerhalb des Bereichs und unbekannte Auflösungswerte ab, bevor die Anfrage Ihren Prozess verlässt. So verwandeln Sie eine Klasse von serverseitigen Validierungsfehlern in sofortige, kostengünstige Fehlschläge in Ihren eigenen Logs.

Dieselbe Regel gilt für Parameternamen. Kopieren Sie sie aus der Dokumentation; ein Tippfehler wie ein zusätzlicher Unterstrich im Dauerfeld wird oft abgelehnt oder stillschweigend ignoriert, und stillschweigendes Ignorieren ist der schwerer zu findende Bug.

Dieselbe Anfrage mit Python senden

Im Folgenden der äquivalente Submit-Code in Python. Er liest den Key aus einer Umgebungsvariable, sendet den JSON-Body, prüft den Statuscode und gibt die Task-ID aus den dokumentierten Antwortfeldern zurück.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def submit_video(prompt: str, **options) -> str:
    payload = {
        "prompt": prompt,
        **options,  # e.g. resolution="720p", duration=5
    }
    response = requests.post(
        f"{BASE_URL}/v1/models/seedance-2.5-flash/text-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    body = response.json()
    task_id = body["id"]  # confirm the field name on the model page
    return task_id


if __name__ == "__main__":
    task_id = submit_video(
        "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
    )
    print("submitted task:", task_id)

Es gibt einige bewusste Entscheidungen in diesem Code:

  • Timeout. Der Submit-Aufruf sollte schnell zurückkehren, aber ein explizites timeout verhindert, dass ein hängender Socket Ihren Worker blockiert.
  • raise_for_status(). Bei HTTP-Fehlern sofort fehlschlagen, statt den Fehler-Response-Body als Erfolgsantwort zu parsen.
  • Keyword-Optionen. Die Übergabe von **options hält die Aufrufstelle lesbar, und das Hinzufügen von resolution oder duration wird sehr einfach, sobald Sie die genauen Namen auf der Modellseite bestätigt haben.
  • ID zurückgeben. Die Aufgabe der Funktion endet beim Absenden. Speichern Sie die ID in einem persistenten Speicher – der nächste Abschnitt verwendet sie, um das Ergebnis abzurufen.

In einer echten Pipeline behandeln Sie submit_video als einen Schritt in einem queue-gesteuerten Workflow: in die Queue einreihen, die zurückgegebene Task-ID zusammen mit Ihrem Task-Datensatz speichern und einen separaten Worker das Ergebnis abrufen lassen.

Asynchrone Ergebnisse verarbeiten: Polling vs. Callback

Nach dem Absenden haben Sie eine Task-ID, aber noch kein Video. Es gibt zwei Möglichkeiten, diese Lücke zu überbrücken.

Polling

Fragen Sie den Task-Status-Endpunkt in festen Intervallen ab, bis der Task einen Endzustand erreicht, und rufen Sie dann die Ausgabe-URL aus der abgeschlossenen Antwort ab.

import time
import requests


def wait_for_video(task_id: str, timeout_s: int = 600) -> dict:
    deadline = time.time() + timeout_s
    delay = 2.0
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",  # confirm path on the model page
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()
        state = task["status"]
        if state == "completed":
            return task
        if state == "failed":
            raise RuntimeError(task.get("error", "generation failed"))
        time.sleep(delay)
        delay = min(delay * 1.5, 15)  # gentle backoff, capped
    raise TimeoutError(f"task {task_id} did not finish in time")

Drei praktische Regeln für das Polling:

  • Backoff. Beginnen Sie mit einer kurzen Verzögerung und erhöhen Sie sie schrittweise. Ständiges Polling mit hoher Frequenz verschwendet Kontingent und erhöht die Last, ohne Nutzen zu bringen.
  • Obergrenze setzen. Jede Polling-Schleife benötigt eine Deadline. Die Videogenerierung kann eine Weile dauern, aber eine unbegrenzte Schleife lässt Ihren Worker schließlich wegen eines hängenden Tasks ewig hängen.
  • Status unterscheiden. Behandeln Sie failed explizit, damit ein schlechter Prompt nicht stillschweigend als Timeout gewertet wird.

Callback

Wenn Sie eine HTTPS-Callback-URL registrieren, kann HiAPI Sie benachrichtigen, wenn der Task abgeschlossen ist, und so das Polling vollständig vermeiden. Zwei Regeln machen Callbacks sicher und zuverlässig:

  • Erst verifizieren, dann vertrauen. Behandeln Sie den Callback als nicht authentifizierte Eingabe, bis Sie seine Signatur oder Herkunft über den in der Plattformdokumentation beschriebenen Mechanismus verifiziert haben.
  • Idempotent bleiben. Callbacks können mehrfach zugestellt werden. Verwenden Sie die Task-ID als Schlüssel für Ihren Handler und machen Sie die Verarbeitung wiederholter Zustellungen zu einem No-Op – speichern Sie das Ergebnis nur einmal und bestätigen Sie wiederholte Zustellungen.

Unabhängig von der gewählten Methode ist das Abrufen des Ergebnisses idempotent: Das Abrufen der Ergebnis-URL für einen abgeschlossenen Task sollte dasselbe Video zurückgeben, sodass Wiederholungen nach Netzwerkfehlern sicher sind.

Häufige Fehler und ihre Behebung

Die meisten Fehlschläge lassen sich auf wenige Kategorien zurückführen. Arbeiten Sie diese Checkliste durch, bevor Sie nicht dokumentiertes Verhalten annehmen.

Authentifizierungsfehler

401 oder 403 bedeutet fast immer, dass der Key fehlt, falsch formatiert oder abgelaufen ist. Prüfen Sie, ob der Authorization-Header vorhanden ist, ob das Authentifizierungsschema genau der Dokumentation entspricht und ob die Umgebungsvariable den Key tatsächlich enthält – ein leerer String erzeugt einen verwirrenden, aber authentifizierungsbezogenen Fehler.

Validierung abgelehnt

Ein 4xx mit einer Validierungsmeldung bedeutet, dass der Server Ihre Parameter abgelehnt hat. Lesen Sie die zulässigen Bereiche auf der Modellseite erneut und bestätigen Sie die Parameternamen Zeichen für Zeichen. Wenn Dauer oder Auflösung außerhalb des Bereichs liegen, besteht die Lösung in der zuvor beschriebenen clientseitigen Validierung – schnell in Ihrem eigenen Code fehlschlagen, statt einen Roundtrip zum Server zu machen.

Task bleibt in einem Nicht-Endzustand hängen

Wenn das Polling nie completed oder failed sieht, läuft der Task möglicherweise noch, oder Ihre Polling-Schleife fragt die falsche Task-ID ab. Protokollieren Sie die von Ihnen übermittelte ID und die abgefragte ID und vergleichen Sie sie. Ihre Schleife sollte außerdem eine Deadline erzwingen; wenn die Deadline ausgelöst wird, sollte die Task-ID offengelegt werden, statt blind zu wiederholen.

Ergebnis kommt nach einem Callback nicht an

Wenn Sie sich auf Callbacks verlassen, prüfen Sie, ob Ihr Endpunkt öffentlich über HTTPS erreichbar ist, ob er schnell einen Erfolgsstatus zurückgibt, statt schwere Arbeit inline auszuführen, und ob wiederholte Zustellungen idempotent behandelt werden. Wenn der Callback-Handler bei der zweiten Zustellung für denselben Task einen Fehler wirft, sieht es so aus, als wäre das Ergebnis verloren gegangen.

Derselbe Job wird doppelt übermittelt

Wenn Ihr Worker den Submit-Aufruf nach einem Timeout wiederholt, können doppelte Tasks entstehen. Zeichnen Sie vor dem Aufruf des Endpunkts einen clientseitigen Request-Key oder eine Job-ID in Ihrer eigenen Datenbank auf und prüfen Sie diese vor einer Wiederholung, damit das Absenden auf Ihrer Seite idempotent bleibt.

Allgemeine Regel: Wenn ein Fehler auftritt, lesen Sie zuerst den Fehler-Response-Body und die Modelldokumentation, bevor Sie den Code ändern. Wenn ein Wert oder Feld nicht dokumentiert ist, vermeiden Sie es, seine Existenz anzunehmen – verifizieren Sie ihn auf der Modellseite und passen Sie die Anfrage entsprechend an.

Ä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