Fehler bei Seedance treten auf zwei Ebenen auf: Zum einen scheitert die HTTP-Anfrage, etwa mit 401, 403, 400 oder 429; zum anderen ist die Anfrage erfolgreich, die Aufgabe endet aber mit failed oder expired. Ein 200 von der Einreichungsschnittstelle als Erfolg zu werten, ist der häufigste Fehlschluss bei der Anbindung einer Video-API. Die richtige Reihenfolge lautet: zuerst den HTTP-Statuscode prüfen, dann Aufgabenstatus und error-Feld, erst zuletzt Prompt ändern oder Modell wechseln.

Dieser Beitrag gliedert nach Fehlertypen und nennt Ursachen, Bearbeitungsreihenfolge sowie einen wiederverwendbaren Fehlerbehandlungscode. Schnittstellenpfade, Statusbezeichnungen und Kontingentregeln können sich mit der Version ändern; maßgeblich sind die Dokumentation auf dieser Website und die offizielle Dokumentation.

Hinweis: Seedance, Doubao und Volcano Engine sind Marken von ByteDance und verbundenen Unternehmen. Dieser Beitrag dient der technischen Erläuterung und begründet keine Zugehörigkeits- oder Fürsprachebeziehung. Pfade und Felder in den Beispielen dienen nur der Demonstration; vor dem Aufruf die Dokumentation prüfen.

1. Zuerst Anfragefehler und Aufgabenfehler unterscheiden

Phänomen Ebene Häufige Ursache Behandlung
401 HTTP Key fehlt, Formatfehler, abgelaufen Authentifizierung korrigieren
403 HTTP Fehlende Rechte, Modell nicht freigeschaltet, Regionsbeschränkung Rechte und Freischaltung prüfen
400 HTTP Parameter außerhalb des Bereichs, falscher Modellname, Material nicht erreichbar Parameter anhand der Dokumentation ändern
429 HTTP Parallelität, Rate oder Quote begrenzt Backoff, Parallelität senken
5xx HTTP Upstream-Überlast oder temporäre Störung Backoff, Kanal wechseln
failed Aufgabe Prüfung abgelehnt, Materialproblem, Generierungsfehler error lesen, Material korrigieren
expired Aufgabe Zeitlimit ohne Abschluss oder Ergebnisabruf Aufgabe neu erstellen, Frist prüfen
Download fehlgeschlagen Ergebnis URL abgelaufen, Authentifizierung, Netzwerk Erneut abrufen oder umspeichern

Das Log erfasst mindestens Zeitpunkt, HTTP-Statuscode, Fehlercode, Modellname, task_id, Geschäftsvorgangsnummer und Dauer. Vollständige Keys nicht protokollieren und signierte Ergebnis-URLs nicht unverändert ausgeben.

2. 401 und 403: zuerst Header und Key prüfen

401 bedeutet, dass die Identität nicht verifiziert wurde, und hängt meist nicht von Modellfähigkeit oder Guthaben ab. Der Reihe nach prüfen:

  • Ist Authorization gleich Bearer <key>? Volcano Ark verwendet den API-Key als Bearer-Token.
  • Enthält der Key Leerzeichen, Zeilenumbrüche oder überflüssige Anführungszeichen, und wird die Umgebungsvariable tatsächlich geladen?
  • Gehören Base-URL und Key zur selben Plattform und Region?
  • Wurde der Key gelöscht, rotiert, deaktiviert, oder fehlt die Projektberechtigung?
  • Überschreibt oder verwirft ein Reverse-Proxy den Authorization-Header?

403 deutet eher auf ein Rechteproblem hin: Modell nicht freigeschaltet, Konto ohne Recht für dieses Modell, Regions- oder Compliance-Beschränkung. Bei 401 lässt sich mit einem neuen Key und einer minimalen Anfrage schnell eingrenzen; bei 403 sind Freischaltungsstatus und Kontorechte in der Konsole zu prüfen, Codeänderungen helfen meist nicht.

3. 429: Drosselung, Parallelität und Quote

429 bedeutet, dass die Anfrage Rate-, Parallelitäts- oder Quotengrenzen überschreitet. Häufige Auslöser:

  • Mehrere Dienste teilen einen Key und verdrängen sich gegenseitig.
  • Batch-Aufgaben starten gleichzeitig zur vollen Stunde und erzeugen einen Verkehrsimpuls.
  • Retries ohne Backoff senden bei Fehlern immer schneller und erzeugen einen Retry-Sturm.
  • Lange Aufgaben belegen die gesamte Parallelität, kurze Aufgaben kommen nicht mehr durch.

Die Prinzipien: exponentielles Backoff mit zufälligem Jitter, Parallelität senken, Keys nach Projekt trennen, zeitlich versetzt einreichen. Nicht ohne Backoff in einer Schleife wiederholen; hochfrequentes Senden während eines 429 verwandelt die Drosselung in eine Dauerstörung. Bei tatsächlich hohem Parallelitätsbedarf vorab die Quotenobergrenze klären und einen Ersatzkanal vorbereiten.

4. 400: Parameterfehler sind die Mehrheit

400 lässt sich meist direkt aus der Fehlermeldung lokalisieren. Besonders prüfen:

  • Modellname und Version: aus der Dokumentation kopieren, Suffixe nicht aus dem Gedächtnis zusammensetzen.
  • Dauer: Die Bereiche unterscheiden sich je Modell, beispielsweise 4–30 Sekunden bei 2.5, 4–15 Sekunden bei 2.0 und 2–12 Sekunden bei 1.0.
  • Auflösung und Seitenverhältnis: prüfen, ob das Modell 4K, 21:9 oder adaptiv unterstützt.
  • Anzahl der Referenzmaterialien: bei 2.5 höchstens 30 Bilder, 10 Videos und 10 Audioclips; 2.0 hat niedrigere Obergrenzen.
  • Bild- oder Video-URL: muss für die Plattform erreichbar sein, keine interne Adresse und kein Link mit Login-Pflicht.
  • Bearbeitungs- oder Fortsetzungsaufgaben: Manche Modi erlauben nur automatische Dauer, keine manuell eingegebenen Sekunden.
  • Audioeingabe: Einige Versionen unterstützen keine reine Audioeingabe.

Am zeitsparendsten ist ein minimales Repro mit dem Beispiel-Request der Dokumentation und anschließendem schrittweisem Hinzufügen der eigenen Parameter. Nach jedem Parameter testen, dann lässt sich das konkrete Feld eingrenzen.

5. Aufgabenstatus failed und expired

Eine erfolgreiche Einreichung bedeutet nur, dass die Aufgabe in der Warteschlange ist. Die Abfrage kennt üblicherweise die Status queued, running, succeeded, failed und expired. Bei failed das error-Feld lesen: Ablehnung durch die Inhaltsprüfung, unzulässiges Eingabematerial, nicht lesbares Referenzbild oder Ausnahme im Generierungsprozess erfordern völlig unterschiedliche Reaktionen.

expired tritt häufig auf, wenn eine Aufgabe die Ausführungsfrist überschreitet, ohne abgeschlossen oder das Ergebnis abgerufen zu sein. Laut Dokumentation ist execution_expires_after konfigurierbar, standardmäßig 48 Stunden; die Task-ID bleibt 7 Tage erhalten. Nach Fristablauf bringt weiteres Polling keine Wiederherstellung, die Aufgabe muss neu erstellt werden. Bei Callbacks beachten: Wird ein Callback nicht innerhalb von 5 Sekunden bestätigt, wird er dreimal wiederholt; die Callback-Schnittstelle muss idempotent sein.

Eine Ablehnung durch die Prüfung nicht durch das Austauschen weniger Wörter umgehen. Zuerst Materialrechte, Porträtrechte, Markenelemente und Inhaltsrichtlinien klären und dann über eine erneute Einreichung entscheiden.

6. Timeouts und Polling

Timeouts in drei Ebenen trennen: Verbindungs-Timeout des Clients, Timeout einer einzelnen Abfrage und Gesamt-Deadline der Aufgabe. Die Einreichungsschnittstelle gibt meist schnell eine task_id zurück; zeitaufwendig sind Warteschlange und Rendering. Ein zu kurzer HTTP-Timeout wertet eine normale Einreichung als Fehler, ein zu langer blockiert den Thread-Pool.

Für das Polling empfiehlt sich ein Start bei 5 Sekunden mit schrittweisem Backoff auf 15–30 Sekunden und einer Gesamt-Deadline. Unterstützt der Dienst Callbacks, diese bevorzugen und Polling als Rückfallebene nutzen. Nach einem Timeout nicht sofort erneut einreichen, sondern über Geschäftsvorgangsnummer oder Idempotenzschlüssel prüfen, ob bereits eine Aufgabe läuft.

7. Fehlgeschlagener Ergebnisdownload

Eine erfolgreiche Aufgabe bedeutet nicht, dass die Datei vorliegt. Die video_url ist oft eine signierte temporäre Adresse mit Gültigkeitsdauer; wer sie direkt speichert und erst Stunden später herunterlädt, erhält häufig 403 oder 404. Vorgehen:

  • Nach Erfolg sofort per Streaming in den eigenen Objektspeicher herunterladen.
  • Downloadfehler separat wiederholen, nicht die Generierungsaufgabe neu erstellen.
  • Content-Type, Dateigröße und Abspielbarkeit prüfen.
  • Vollständige signierte URLs nicht ins Log schreiben.

8. Beispiel: Fehlerbehandlung mit Backoff und Idempotenz

Der folgende Code behandelt Einreichung, Polling und Download getrennt und wiederholt nur vorübergehende Fehler. Pfade und Felder richten sich nach der Dokumentation auf dieser Website.

import os, time, random, requests

BASE = os.environ["SEEDANCE_BASE_URL"].rstrip("/")
HEADERS = {
    "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
    "Content-Type": "application/json",
}

def submit(payload, max_retries=5):
    # Vor dem Aufruf die Aufgabentabelle nach der Geschäftsvorgangsnummer prüfen; vorhandene task_id wiederverwenden
    for attempt in range(max_retries):
        try:
            r = requests.post(
                f"{BASE}/contents/generations/tasks",
                headers=HEADERS, json=payload, timeout=(5, 30),
            )
        except requests.Timeout:
            time.sleep(min(2 ** attempt, 20) + random.random())
            continue
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(min(2 ** attempt, 20) + random.random())
            continue
        if r.status_code >= 400:
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")
        return r.json()["id"]
    raise RuntimeError("submit retries exhausted")

def wait(task_id, deadline_seconds=900):
    deadline = time.time() + deadline_seconds
    delay = 5
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/contents/generations/tasks/{task_id}",
            headers=HEADERS, timeout=(5, 30),
        )
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(delay)
            delay = min(delay * 1.5, 30)
            continue
        r.raise_for_status()
        data = r.json()
        if data["status"] == "succeeded":
            return data["content"]["video_url"]
        if data["status"] in ("failed", "expired"):
            raise RuntimeError(f"{data['status']}: {data.get('error')}")
        time.sleep(delay)
        delay = min(delay * 1.5, 30)
    raise TimeoutError(task_id)

def download(url, path):
    with requests.get(url, stream=True, timeout=(5, 120)) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(1024 * 256):
                f.write(chunk)

Der Code wiederholt bewusst keine 400-, 401- und 403-Fehler. Parameter- und Authentifizierungsfehler werden durch beliebig viele Retries nicht erfolgreich, sie vergrößern nur Log und Kosten.

9. Retry, Idempotenz und Support-Checkliste

Retries eignen sich nur für vorübergehende Fehler: 429, 5xx und Verbindungs-Timeouts. 400, 401, 403 und eine Ablehnung durch die Prüfung sollten nicht automatisch wiederholt werden. Entscheidend für Idempotenz ist nicht die Retry-Zahl, sondern die Geschäftsvorgangsnummer: vor dem Einreichen die Aufgabentabelle prüfen, nach dem Einreichen die task_id speichern und bei doppelten Anfragen die vorhandene Aufgabe wiederverwenden.

Vor der Kontaktaufnahme mit dem Dienstleister die Informationen anhand dieser Checkliste zusammenstellen:

  1. Zeitpunkt, HTTP-Statuscode, Fehlercode und vollständige Fehlermeldung, anonymisiert.
  2. Modellname, Dauer, Auflösung, Seitenverhältnis und Anzahl der Referenzmaterialien.
  3. task_id, Geschäftsvorgangsnummer, Anzahl der Einreichungen und Polling-Abfragen.
  4. Eine minimale Reproduktionsanfrage ohne Nutzerdaten und Schlüssel aufbewahren.
  5. Anfragefehler von Aufgabenstatus failed oder expired unterscheiden.
  6. Prüfen, ob die Material-URL öffentlich erreichbar ist und die Antwort zu langsam kommt.
  7. Quote, Parallelität und Kontorechte bestätigen, um 429 und 403 auszuschließen.
  8. Request-ID und Reproduktionszeitpunkt beifügen, dann zur Untersuchung einreichen.

Häufig gestellte Fragen

Warum schlägt die Aufgabe fehl, obwohl die Einreichung 200 zurückgibt?

200 bedeutet nur, dass die Aufgabe erstellt wurde. Die Videogenerierung ist asynchron; der endgültige Status steht im Feld status und im error-Feld der Abfrage.

Bedeutet 429 unzureichendes Guthaben?

Nicht unbedingt. 429 zeigt meist eine Begrenzung von Rate, Parallelität oder Quote; ein Guthabenproblem kann einen anderen Fehler liefern. Zuerst Parallelität, geteilte Keys und Retry-Strategie prüfen.

Kann nach einer fehlgeschlagenen Aufgabe direkt wiederholt werden?

Zuerst error lesen. Bei Ablehnung durch die Prüfung oder unzulässigem Material scheitert eine unveränderte Wiederholung meist erneut; bei Netzwerk- oder Upstream-Störungen ist Backoff sinnvoll. Vor dem Retry per Geschäftsvorgangsnummer eine Idempotenzprüfung durchführen.

Wie häufig sollte gepollt werden?

Start bei 5 Sekunden, schrittweises Backoff auf 15–30 Sekunden und eine Gesamt-Deadline setzen. Callbacks bevorzugen, Polling als Rückfallebene.

Was tun, wenn die Ergebnis-URL nicht mehr öffnet?

Meist ist die Gültigkeit abgelaufen oder die Signatur ungültig. Nach Erfolg sofort in den Objektspeicher umspeichern; ist die Frist bereits verstrichen, die Aufgabe erneut abfragen oder neu erstellen, nicht wiederholt die alte URL aufrufen.

Nächster Schritt

Erstellen Sie zunächst im ZSQH AI Gateway einen Test-Key und proben Sie 401, 429, Parameterfehler und Aufgabenfehler jeweils einmal, um Alarme und Retry-Strategie zu bestätigen. Modellverfügbarkeit und Abrechnung richten sich nach den Modellpreisen.

Weiterführende Beiträge