Die Seedance-Videogenerierung arbeitet mit asynchronen Aufgaben: Der Aufruf zum Erstellen liefert nur eine Aufgaben-ID, das Video erscheint nicht synchron in der Antwort. Die Anwendung muss den Status selbst abfragen, Fehler behandeln und das Ergebnis sichern, bevor der Download-Link abläuft.

Wer nach dem synchronen Muster von Chat Completions programmiert, läuft meist schon im ersten Schritt in einen Timeout. Dieser Artikel folgt der praktischen Reihenfolge: Base URL, Authentifizierung, Einreichung, Statusabfrage, Download, Callback und Idempotenz.

Hinweis: Seedance, ByteDance, Doubao, Volcengine und Volcano Ark sind Marken der jeweiligen Rechteinhaber. Dieser Artikel dient ausschließlich der technischen Erläuterung und begründet keine Kooperation, Vertretung oder Autorisierung. Schnittstellenpfade, Modellnamen und Preise richten sich nach der offiziellen Dokumentation und der Plattformdokumentation.

1. Zugangsparameter: Base URL, Modell und Authentifizierung

Die offizielle Daten-API von Volcano Ark verwendet die Base URL https://ark.cn-beijing.volces.com/api/v3; Videoaufgaben werden über /contents/generations/tasks erstellt. Die Authentifizierung erfolgt mit Authorization: Bearer $ARK_API_KEY, der Request-Body ist JSON.

Das Feld model akzeptiert eine Model ID oder eine Endpoint ID. Der Unterschied liegt in der Authentifizierung: Mit einem API-Key funktionieren meist beide; bei AK/SK-Signatur muss in der Regel die Endpoint ID angegeben werden, nicht die Model ID. Das ist eine der häufigsten Fallen bei Migration und Fehlersuche.

Vor der Anbindung außerdem prüfen: Ist das Modell freigeschaltet, reicht das Kontingent, und unterstützt der aktuelle Zugang die benötigte Dauer und Auflösung? Gateway-Nutzer prüfen zuerst die Plattformdokumentation, ob Videokanal und Aufgabenfelder mit dem offiziellen Verhalten übereinstimmen.

Aktion Methode und Pfad Hinweis
Aufgabe erstellen POST /contents/generations/tasks Liefert Aufgaben-ID, kein Video
Aufgabe abfragen GET /contents/generations/tasks/{id} Status und Ergebnis
Liste abfragen GET /contents/generations/tasks Batch-Abgleich und Nacharbeit
Aufgabe abbrechen Abbruch- oder Löschschnittstelle laut Dokumentation Meist nur für wartende Aufgaben wirksam

Die Unterstützung von Abbruch, Löschung und Listenabfrage unterscheidet sich je Plattform; vorab in der Dokumentation prüfen. Am Ende der Base URL nicht erneut /api/v3 anhängen, sonst entsteht ein Pfadfehler.

2. Aufgabe einreichen: Was ein POST enthalten muss

Ein typischer Erstellungsaufruf; die Felder dienen nur als Beispiel:

export ARK_API_KEY="your-api-key"
export BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

curl -sS -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {"type": "text", "text": "Hafen am frühen Morgen, Container werden verladen, langsame Luftaufnahme im Kreis, realistischer Stil"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}, "role": "first_frame"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false,
    "callback_url": "https://api.example.com/callbacks/seedance"
  }'

Wichtige Felder:

  • content ist ein Array; Text, Startbild, Referenzbild und Referenzvideo verwenden unterschiedliche type und role.
  • Die zulässigen Bereiche von duration, ratio und resolution hängen von der Modellversion ab; fremde Dokumentation nicht ungeprüft übernehmen.
  • watermark beeinflusst, ob das Ergebnis ein Wasserzeichen trägt; vor kommerzieller Nutzung die Plattformregeln prüfen.
  • callback_url dient der Benachrichtigung bei Abschluss; die tatsächliche Unterstützung hängt von der Plattform ab.
  • Felder wie seed, camera_fixed und return_last_frame werden nicht von allen Modellen unterstützt.

Nach erfolgreicher Einreichung die Aufgaben-ID sofort speichern und mit der Vorgangsnummer verknüpfen. Statusabfrage, Wiederholungen, Abgleich und Kosten Zuordnung hängen später von dieser ID ab.

3. Statusabfrage: Zustandsmodell und Backoff

Für die Abfrage genügt die Aufgaben-ID:

curl -sS "$BASE_URL/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $ARK_API_KEY"

Typische Zustände und Behandlung:

status Bedeutung Empfehlung
queued In der Warteschlange Weiter warten, bei Bedarf abbrechen
running Wird erzeugt Weiter abfragen, nicht erneut einreichen
succeeded Erfolgreich Ergebnis lesen und sofort sichern
failed Fehlgeschlagen Fehlercode speichern, Wiederholbarkeit prüfen
expired Zeitüberschreitung Timeout oder Parameter anpassen und neu senden
cancelled Abgebrochen Prüfen, ob geschäftlich gewollt

Nicht jede Sekunde fest abfragen. Sinnvoll ist ein Start bei 5 Sekunden, dann 10, 20 und höchstens etwa 30 Sekunden, mit etwas Jitter, damit mehrere Instanzen nicht gleichzeitig den Upstream treffen. Die Gesamtobergrenze nach Geschäftsanforderung setzen, etwa 10 Minuten; danach als „zu prüfen“ markieren statt unendlich zu warten.

Aufgabenaufzeichnungen sind meist nur begrenzt abrufbar; die offizielle Dokumentation nennt etwa 7 Tage. Danach hängt die Historie von der eigenen Aufgabentabelle ab. Statusänderungen daher zeitnah speichern.

4. Ergebnis herunterladen und sichern

Nach Erfolg enthält die Antwort eine Videoadresse. Diese ist meist befristet; die offizielle Dokumentation nennt etwa 24 Stunden, und manche Modelle begrenzen die Anzahl der Downloads. Sie ist keine dauerhafte CDN-Adresse für Frontend oder Kunden.

Richtig ist: Nach dem Erfolgsstatus sofort herunterladen, in den eigenen Objektspeicher übertragen und Aufgaben-ID, Vorgangsnummer, Objektpfad, Dateigröße und Prüfsumme erfassen. Erst danach die interne Adresse in die Geschäftsdatenbank schreiben. So bleiben alte Bestellungen auch nach Ablauf des Upstream-Links abrufbar und auslieferbar.

Beim Download große Dateien, Resume, Parallelitätsgrenzen und Wiederholungen berücksichtigen. Liefert die Antwort zusätzlich ein Startbild oder Audio, die Felder getrennt sichern und nicht nur das Video speichern.

5. Webhook oder Statusabfrage

Beide Wege liefern Ergebnisse, unterscheiden sich aber in Aktualität und Betriebsaufwand:

Weg Vorteile Nachteile Geeignet für
Webhook Geringe Latenz, weniger Leerabfragen Öffentlich erreichbar, Signaturprüfung, Replay-Schutz nötig Produktive asynchrone Aufgaben
Polling Einfach, keine öffentliche Erreichbarkeit Verzögerung, zusätzliche Anfragen Interne Werkzeuge, Tests, Rückfallebene
Hybrid Callback als Hauptweg, Polling als Absicherung Status-Deduplizierung nötig Die meisten Produktionssysteme

In der Produktion ist „Callback plus Abgleich“ am robustesten: Der Callback liefert geringe Latenz, ein geplanter Job prüft Datensätze ohne Endzustand als Absicherung. Die Callback-Schnittstelle muss Signaturen prüfen und idempotent arbeiten; ein Eingang darf nicht doppelt gespeichert oder doppelt Folgeprozesse auslösen. Verlorene Callbacks sind nicht selten und taugen nicht als einzige Benachrichtigung.

6. Idempotenz und doppelte Einreichung

Videoaufgaben sind teuer und langsam; doppelte Einreichungen kosten deutlich mehr als bei Text. Vier Ebenen:

  • Vor dem Senden einen Idempotenzschlüssel aus Vorgangsnummer und Version bilden und zuerst die Datenbank prüfen.
  • Aufgaben-ID und Vorgangsnummer mit eindeutigem Index versehen, damit die Datenbank doppelte Datensätze verhindert.
  • Ein Request-Timeout bedeutet nicht, dass die Aufgabe fehlgeschlagen ist. Zuerst per Idempotenzschlüssel oder Aufgabenliste prüfen, ob keine Aufgabe entstanden ist, dann wiederholen.
  • Nur bei 429, 5xx und Netzwerkfehlern wiederholen; 400-Parameterfehler und Ablehnungen durch die Inhaltsprüfung nicht blind wiederholen.

Auch Abbruch und Neusendung brauchen einen Grund im Datensatz. Sonst entstehen für dieselbe Bestellung mehrere Videos, was Kosten und Abgleich erschwert. Ein täglicher Abgleichjob prüft Status, Kosten und Ergebnisse.

7. Häufige Fehler und Diagnose

  • 401 AuthenticationError: Key fehlt, ist ungültig oder der Header ist falsch; auch eine nicht passende Base URL kann die Ursache sein.
  • 403 AccessDenied, AccountOverdueError: fehlende Rechte, überfälliges Konto oder nicht freigeschalteter Dienst.
  • 404 ModelNotOpen, UnsupportedModel: Modell nicht freigeschaltet oder Name falsch geschrieben.
  • 400 SensitiveContentDetected: Prompt oder Material löst die Inhaltsprüfung aus; Material ändern statt wiederholen.
  • 400 InvalidParameter: Feldname, Dauer, Seitenverhältnis oder Auflösung außerhalb des erlaubten Bereichs.
  • 429 RateLimitExceeded: Parallelität senken und exponentiell zurückweichen; bei Bedarf höheres Kontingent beantragen.
  • failed oder expired: error.code und error.message lesen und Parameterfehler, Prüfablehnung sowie Upstream-Störung unterscheiden.

Fehlercode-Strings können sich mit der Plattform ändern; maßgeblich sind die tatsächliche Antwort und die Fehlercodedokumentation. Originalcode, Request-ID und anonymisierte Parameter gemeinsam protokollieren; das verkürzt die Diagnose deutlich.

8. Migrationscheckliste

Beim Wechsel von der offiziellen Schnittstelle zu einem Gateway oder zwischen Plattformen Punkt für Punkt prüfen:

  1. Base URL und Authentifizierung vollständig ersetzen, nicht nur den Key.
  2. Klären, ob model eine Model ID oder Endpoint ID erwartet und ob das zur Authentifizierung passt.
  3. Feldnamen, Dauer, Seitenverhältnis und Auflösung im neuen Kanal prüfen.
  4. Deckt die Statusliste Warteschlange, Lauf, Erfolg, Fehler, Timeout und Abbruch ab?
  5. Laufzeit des Ergebnislinks, Downloadlimit und Sicherungslogik testen.
  6. Ist die Callback-Adresse öffentlich erreichbar, Signaturprüfung und Idempotenz umgesetzt?
  7. Sind Idempotenzschlüssel, Aufgabentabelle, Abgleichjob und Warnungen aktiv?
  8. Wurden Rate-Limits, Timeouts, Wiederholungen und Parallelität unter Last getestet?

Nach der Migration zuerst eine kleine Charge senden und Erfolgsquote, Durchschnittsdauer sowie Kosten pro Video vergleichen, dann schrittweise erhöhen. Ohne Abgleichmechanismus nicht sofort den gesamten Traffic umstellen.

Häufige Fragen

Liefert die Seedance API Videos synchron?

Meist nicht. Das Erstellen liefert nur eine Aufgaben-ID; danach Status abfragen oder auf einen Callback warten und das Video nach Erfolg herunterladen. Ein synchrones Design läuft leicht in Timeouts und doppelte Einreichungen.

Wie lange bleiben Aufgaben-ID und Ergebnis verfügbar?

Laut offizieller Dokumentation sind Aufgaben etwa 7 Tage abfragbar, der Videolink etwa 24 Stunden gültig. Für dauerhafte Aufbewahrung selbst in den Objektspeicher übertragen.

Welches Abfrageintervall ist sinnvoll?

Start bei 5 Sekunden, dann schrittweise auf 15 bis 30 Sekunden erhöhen und eine Gesamtobergrenze setzen. Festes hochfrequentes Abfragen verschwendet Anfragen und löst eher Rate-Limits aus.

Werden Webhook-Callbacks unterstützt?

Die offizielle Erstellungschnittstelle bietet ein Feld callback_url; die Zustellung hängt jedoch von Netz und Plattformstrategie ab. Ob ein Gateway Callbacks unterstützt, steht in der Plattformdokumentation; für die Produktion ist Polling als Rückfallebene sinnvoll.

Werden fehlgeschlagene Aufgaben berechnet?

Die Regeln unterscheiden sich je Plattform und Fehlerart. Vor der Anbindung klären, wie Prüfablehnung, Timeout und Abbruch abgerechnet werden, und mit einer kleinen Charge die Rechnung prüfen.

Nächste Schritte

Zuerst mit kürzester Dauer und niedriger Auflösung eine Aufgabe durchspielen, dann Aufgabentabelle, Statusabfrage, Sicherung und Abgleich ergänzen. Für einen einheitlichen Zugang kann man sich bei ZSQH AI Gateway registrieren und auf der Seite Modellpreise den Seedance-Kanal sowie die Abrechnung prüfen.

Weiterlesen: