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
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.
POSTerstellt 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/jsonteilt 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
timeoutverhindert, 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
**optionshält die Aufrufstelle lesbar, und das Hinzufügen vonresolutionoderdurationwird 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
failedexplizit, 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 →-
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
-
Tutorial
gemini-4-neon Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Integrationshinweise
-
Tutorial
seedance-2.5-flash 图生视频 API 教程:curl 与 Python Requests
Eine praktische Integrationsübung für Entwickler: Anfragestruktur, Start-/Endbild-Eingaben, asynchrones Polling und Fehlersuche