Seedance API Produktions-Checkliste für Text-zu-Video-Teams

Ein Seedance API-Prototyp kann nach einem erfolgreichen Video bereits fertig wirken. Eine Produktionsintegration ist erst dann wirklich fertig, wenn Ihr System langsame Jobs, doppelte Ereignisse, wechselnde Modellrouten, partielle Fehler und unsichere Kosten überstehen kann.

Dieser Unterschied ist wichtig, weil Videogenerierung keine normale Request-Response-Funktion ist. Die Anwendung übermittelt Arbeit, wartet, empfängt Statusänderungen, speichert eine große Ausgabedatei und entscheidet, ob ein Fehler erneut versucht werden soll. Der Modellaufruf ist nur eine Stufe in einem längeren Workflow.

Diese Checkliste macht aus diesem Workflow einen Produktionsvertrag, den Ihr Produkt-, Plattform- und Finanzteam gemeinsam prüfen kann.

Hinweis zur aktuellen Route: Flatkeys öffentliches Modellverzeichnis führte bei der Prüfung dieses Leitfadens am Montag, 27. Juli 2026 seedance-2.5 für Text-zu-Video und Bild-zu-Video sowie seedance-2.0-i2v für Bild-zu-Video auf. Behandeln Sie diese Namen als Zustand des Katalogs, nicht als permanente Konstanten. Bestätigen Sie das aktuelle Flatkey-Modellverzeichnis, bevor Sie live gehen oder eine Allowlist ändern.

Die kurze Antwort

Verbinden Sie Ihre benutzerseitige Anfrage nicht direkt mit einem Aufruf des Videoanbieters. Setzen Sie eine dauerhafte Job-Schicht dazwischen.

Ihr minimaler Produktionspfad sollte folgendermaßen aussehen:

1. die Generierungsanfrage des Nutzers annehmen und validieren
2. den eigenen Idempotenzschlüssel und die Job-ID zuweisen
3. die Anfrage speichern, bevor die Modellroute aufgerufen wird
4. den Job über einen serverseitigen Adapter übermitteln
5. Webhook- und Polling-Updates idempotent verarbeiten
6. abgeschlossene Medien in von Ihnen kontrollierten Speicher kopieren
7. Latenz, Fehlerursache, Modellroute und geschätzte Kosten erfassen
8. einen stabilen Produktstatus bereitstellen, der unabhängig von der Formulierung des Anbieters ist

Wenn einer dieser Schritte fehlt, lässt sich die Integration zwar möglicherweise immer noch gut demonstrieren, aber der Betrieb ist dann schwerer sicher zu handhaben.

Warum Seedance API-Produktionsarbeit anders ist

Textgenerierung liefert oft in einem einzigen HTTP-Austausch eine brauchbare Antwort. Videogenerierung verhält sich gewöhnlich wie ein verteilter Batch-Job. Eine Nutzeraktion kann einen Anwendungs-Request, ein Deployment, eine Browser-Sitzung oder sogar die temporäre URL überdauern, unter der schließlich das Ergebnis liegt.

Die praktischen Folgen werden leicht unterschätzt:

Das Ziel ist nicht, den Provider zu verbergen. Es geht darum, zu verhindern, dass providerspezifisches Verhalten zu einem dauerhaften Vertrag Ihres Produkts wird.

1. Frieren Sie den Produktvertrag ein, bevor Sie das Payload festlegen

Beginnen Sie mit der Erfahrung, die Sie Ihren Nutzern versprechen, nicht mit den heute verfügbaren Feldern des Providers.

Definieren Sie:

• akzeptierte Eingabetypen: nur Text, Bild plus Text oder beides
• unterstützte Seitenverhältnisse und Dauerbereiche
• maximale Upload-Größe und akzeptierte Medienformate
• Moderations- und Rechteprüfungen vor dem Absenden
• erwartete Statusaktualisierungen und Abbruchverhalten
• Aufbewahrungsdauer der Ausgabe
• ob ein fehlgeschlagener Job ein Benutzerkontingent verbraucht
• was „Retry“ im Produkt bedeutet

Übersetzen Sie diesen Vertrag dann innerhalb eines Adapters in die aktuelle Seedance-Route.

Diese Trennung schützt Sie vor zwei häufigen Fehlermustern. Erstens kann ein Routen-Update Parameter hinzufügen oder umbenennen, ohne dass ein Frontend-Redesign erzwungen wird. Zweitens kann Ihre Anwendung nicht unterstützte Kombinationen ablehnen, bevor Geld für einen aussichtslosen Job ausgegeben wird.

2. Verwenden Sie Ihre eigene Job-ID und Idempotenzschlüssel

Jede Anfrage benötigt zwei Bezeichner:

• Produkt-Job-ID: der stabile Bezeichner, der in Ihrem gesamten System angezeigt wird
• Idempotenzschlüssel: der Bezeichner, der verwendet wird, um versehentliche doppelte Übermittlungen zu verhindern

Verwenden Sie keine Provider-Task-ID als primären Schlüssel. Sie existiert erst nach dem Absenden, und sie kann sich ändern, wenn Sie absichtlich über eine andere Route erneut senden.

Ein einfacher Anfrage-Datensatz kann so aussehen:

type VideoJob = {
  id: string;
  idempotencyKey: string;
  accountId: string;
  requestedModel: string;
  resolvedModel: string | null;
  providerTaskId: string | null;
  status: "accepted" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
  attempt: number;
  outputUrl: string | null;
  failureCode: string | null;
  createdAt: string;
  updatedAt: string;
};

Erstellen Sie diesen Datensatz vor dem ausgehenden API-Aufruf. Wenn die Anwendung nach dem Absenden abstürzt, aber bevor die Antwort gespeichert wird, gibt Ihnen der Idempotenzschlüssel eine Möglichkeit zur Abstimmung, anstatt blind für eine weitere Generierung zu zahlen.

3. Platzieren Sie Seedance hinter einem serverseitigen Adapter

Halten Sie die providerspezifische Request-Erstellung in einem einzigen Modul. Der Rest Ihres Produkts sollte einen normalisierten Befehl senden wie:

type GenerateVideoCommand = {
  prompt: string;
  sourceImageUrl?: string;
  aspectRatio: "16:9" | "9:16" | "1:1";
  durationSeconds: number;
  qualityProfile: "draft" | "standard" | "high";
};

Der Adapter ist verantwortlich für:

• das Auflösen von qualityProfile auf ein aktuell verfügbares Modell und dessen Einstellungen
• das serverseitige Hinzufügen der Authentifizierung
• das Übersetzen Ihrer Auswahl für Seitenverhältnis und Dauer in das aktive API-Schema
• das Absenden der Aufgabe
• das Normalisieren von Provider-Fehlern
• das Speichern der Provider-Task-ID
• das Melden ausreichender Metadaten für Kosten- und Zuverlässigkeitsanalysen

Flatkey gibt Teams einen API-Schlüssel, einen stabilen Router-Endpunkt, ein gemeinsames Guthaben und zentrale Sichtbarkeit der Nutzung über Modellfamilien hinweg. Für Teams, die diese Zugriffsschicht bereits verwenden, sollten Sie die Seedance-spezifische asynchrone Logik im Adapter belassen, statt Routenannahmen über die Codebasis zu verteilen. Der frühere Leitfaden zu einer stabilen OpenAI-kompatiblen Base-URL für Seedance-API-Teams erklärt diese Grenze ausführlicher.

4. Modellieren Sie den Workflow als Zustandsmaschine

Lassen Sie keine beliebigen Status-Strings in die Produktlogik einfließen. Normalisieren Sie sie.

stateDiagram-v2
    [*] --> accepted
    accepted --> queued: submit accepted
    accepted --> failed: validation or submit error
    queued --> running: provider starts work
    queued --> failed: terminal provider error
    running --> succeeded: output verified
    running --> failed: terminal provider error
    accepted --> cancelled: cancelled before submit
    queued --> cancelled: cancellation confirmed
    succeeded --> [*]
    failed --> [*]
    cancelled --> [*]

Erlauben Sie nur Vorwärtsübergänge, es sei denn, Sie führen einen expliziten Wiederherstellungsprozess aus. Ein spätes running-Ereignis darf einen bereits als succeeded markierten Job nicht überschreiben. Ein doppeltes succeeded-Webhook darf nicht zwei Speicherkopien oder zwei Kundenbenachrichtigungen auslösen.

Speichern Sie das rohe Provider-Ereignis separat für das Debugging, treffen Sie Produktentscheidungen jedoch auf Basis des normalisierten Zustands.

5. Verwenden Sie Webhooks und Polling zusammen

Webhooks sind effizient, aber sie garantieren nicht, dass Ihre Anwendung jedes Ereignis genau einmal und in der richtigen Reihenfolge verarbeitet. Polling ist langsamer, aber für die Abgleichung wertvoll.

Verwenden Sie beides:

• Webhook-Pfad: Statusaktualisierungen mit geringer Latenz
• Polling-Pfad: geplante Wiederherstellung für Jobs, die sich kürzlich nicht geändert haben

Ihr Webhook-Handler sollte:

1. den Callback authentifizieren, wenn die aktive API eine Verifikation unterstützt
2. das Ereignis parsen, ohne inline schwere Arbeit zu erledigen
3. einen Ereignis-Fingerprint in eine Deduplizierungstabelle schreiben
4. die Verarbeitung in eine Warteschlange stellen
5. schnell Erfolg zurückgeben

Ihr Reconciliation-Worker sollte nur Jobs pollen, die nach einer sinnvollen Verzögerung noch nicht terminal sind. Fügen Sie Jitter hinzu, damit ein Deployment nicht dazu führt, dass Tausende von Statusprüfungen im selben Moment ausgeführt werden.

Die anbieterspezifischen Webhook- und Query-Felder können sich ändern. Prüfen Sie sie während der Implementierung anhand der aktuellen offiziellen API-Referenz, statt einen alten Payload aus einem Blogbeitrag zu übernehmen.

6. Retry-Entscheidungen nach Fehlerklasse treffen

„Fehlgeschlagene Jobs erneut versuchen“ ist keine Richtlinie. Es ist ein Kostenrisiko.

Normalisieren Sie Fehler in Klassen:

Die letzte Unterscheidung ist besonders wichtig. Wenn das Video erfolgreich generiert wurde, aber Ihr Speicherkopiervorgang fehlgeschlagen ist, erzeugt eine erneute Video-Generierung unnötige Kosten und kann ein anderes Ergebnis liefern.

Legen Sie ein Retry-Budget pro Job fest. Eine vernünftige Richtlinie könnte mehr Statusprüfungen und Speicher-Kopierversuche als Generierungsübermittlungen erlauben.

7. Ausgaben in Speicher kopieren, den Sie kontrollieren

Behandeln Sie jede vom Anbieter gehostete Ergebnis-URL als Transferort, nicht als dauerhaftes Produkt-Asset.

Nachdem ein Job erfolgreich war:

1. prüfen, dass die Antwort den erwarteten Medientyp enthält
2. mit einer Größen- und Zeitbegrenzung herunterladen
3. validieren, dass die Datei nicht leer oder offensichtlich abgeschnitten ist
4. eine Prüfsumme berechnen
5. sie in Ihren Objektspeicher kopieren
6. Dauer, Abmessungen, Codec und Größe speichern
7. den Produkt-Job erst dann auf succeeded umstellen, wenn die dauerhafte Kopie verfügbar ist

Wenn Ihr Produkt Nutzern erlaubt, das ursprüngliche Anbieter-Asset herunterzuladen, bevor der Kopiervorgang abgeschlossen ist, stellen Sie das als separaten vorübergehenden Zustand dar. Versprechen Sie nicht stillschweigend Dauerhaftigkeit.

8. Kostenkontrollen hinzufügen, bevor Sie die Funktion freigeben

Video-Jobs sind teuer genug, dass Produktlimits vor dem öffentlichen Launch vorhanden sein sollten.

Definieren Sie mindestens:

• eine Ausgabengrenze pro Schlüssel oder Team
• eine Modell-Zulassungsliste für den Anwendungsschlüssel
• eine maximale Anzahl gleichzeitiger Jobs pro Konto
• eine maximale Dauer und ein Qualitätsprofil pro Tarif
• ein tägliches Übermittlungslimit für neue oder nicht vertrauenswürdige Konten
• einen Circuit Breaker, wenn Fehlerrate oder Kosten pro Erfolg steigen

Die öffentliche Dokumentation von Flatkey beschreibt Obergrenzen pro Schlüssel, optionale Modell-Zulassungslisten und Nutzungstransparenz über Usage & Logs oder die Ledger-API. Verwenden Sie diese Kontrollen als Schutzgeländer auf der Zugriffsebene und fügen Sie dann Produkt-Quoten auf Grundlage Ihrer eigenen Pläne und Ihres Missbrauchsrisikos hinzu.

Bevor Sie eine neue Route aktivieren, vergleichen Sie den aktuellen Katalog und die Flatkey-Preisgestaltung. Betten Sie keinen numerischen Preis aus diesem Artikel in die Anwendungslogik ein; Preise und Routenverfügbarkeit sind aktualisierbare Daten.

9. Messen Sie den gesamten Job, nicht nur die API-Latenz

Für einen asynchronen Seedance-API-Workflow kann eine erfolgreiche Übermittlung dennoch eine schlechte Kundenerfahrung verursachen.

Mindestens erfassen:

• Annahmequote der Übermittlung
• Wartezeit in der Warteschlange
• Generierungszeit
• Gesamtzeit bis zur dauerhaften Ausgabe
• Erfolgsrate nach aufgelöstem Modell
• Fehlerrate nach normalisierter Fehlerklasse
• Verzögerung bei der Webhook-Zustellung
• Erfolgsrate bei der Wiederherstellung per Polling
• Fehlerrate beim Speichern der Ausgabe
• Kosten pro übermitteltem Job
• Kosten pro erfolgreicher dauerhafter Ausgabe
• Anzahl verhinderter Doppelübermittlungen

Verwenden Sie Perzentile, nicht nur Durchschnittswerte. Eine mediane Generierungszeit kann gesund aussehen, während die langsamsten zehn Prozent der Jobs die meisten Support-Tickets verursachen.

Erfassen Sie außerdem requestedModel und resolvedModel getrennt. Dadurch werden Routenänderungen sichtbar und Sie erhalten Belege für Rollback-Entscheidungen.

10. Modelländerungen als Migrationen ausrollen

Eine Katalogänderung ist nicht bloß ein String-Ersetzung. Behandeln Sie sie wie ein Abhängigkeits-Upgrade.

Bevor Sie Produktionsverkehr auf eine neue Seedance-Route umstellen:

1. bestätigen Sie die aktuelle Route im Live-Modelverzeichnis
2. vergleichen Sie unterstützte Eingaben und Ausgabegrenzen
3. führen Sie einen festen Evaluierungssatz über Ihre gängigen Prompt-Typen hinweg aus
4. vergleichen Sie Erfolgsrate, Latenz, Ausgabeakzeptanz und Kosten
5. testen Sie Webhook-, Polling- und Fehlernormalisierung
6. rollen Sie einen kleinen Verkehrsanteil als Canary aus
7. bewahren Sie eine Rollback-Route, bis das Canary stabil ist
8. aktualisieren Sie die Modell-Allowlist und das operative Runbook

Wenn Ihre Anwendung eine "Qualität"-Einstellung anbietet, ordnen Sie sie einem Fähigkeitsprofil statt einer dauerhaften Modell-ID zu. So können Sie die zugrunde liegende Route ändern, ohne die Produkt-API zu beschädigen.

Checkliste zur Produktionsreife

Verwenden Sie diese Liste als Startfreigabe.

Anfrage und Zugriff

• [ ] API-Schlüssel bleiben serverseitig
• [ ] der Anwendungsschlüssel hat ein Ausgabenlimit und eine Modell-Allowlist
• [ ] jede Anfrage hat eine interne Job-ID und einen Idempotenzschlüssel
• [ ] Eingaben werden vor dem Absenden validiert
• [ ] die aktuelle Seedance-Modellroute wird im Live-Katalog geprüft

Asynchrone Ausführung

• [ ] anbieterspezifische Logik lebt in einem Adapter
• [ ] Produktstatus verwenden eine normalisierte Zustandsmaschine
• [ ] Webhook-Ereignisse werden bei Unterstützung authentifiziert und dedupliziert
• [ ] Polling gleicht veraltete nicht-endgültige Jobs ab
• [ ] späte oder doppelte Ereignisse können endgültige Zustände nicht zurücksetzen

Zuverlässigkeit und Kosten

• [ ] das Wiederholungsverhalten variiert je nach Fehlerklasse
• [ ] Generierungswiederholungen haben ein striktes Budget
• [ ] Wiederholungen beim Kopieren der Ausgabe regenerieren keine erfolgreichen Videos
• [ ] Parallelität und tägliche Joblimits werden durchgesetzt
• [ ] ein Circuit Breaker kann eine beeinträchtigte Route pausieren

Ausgabe und Beobachtbarkeit

• [ ] erfolgreiche Medien werden in kontrollierten Speicher kopiert
• [ ] Ausgabemetadaten und Prüfsumme werden gespeichert
• [ ] angeforderte und aufgelöste Modell-IDs werden protokolliert
• [ ] Kosten pro erfolgreicher dauerhafter Ausgabe werden gemessen
• [ ] Operatoren haben ein Runbook für hängende, fehlgeschlagene und doppelte Jobs

Wo Flatkey passt

Flatkey entfernt nicht die Notwendigkeit einer asynchronen Video-Job-Schicht. Es reduziert die Zugriffs- und Governance-Arbeit rund um diese Schicht: ein Konto, ein Guthaben, API-Key-Kontrollen, eine stabile Router-Oberfläche, ein Live-Modellkatalog und zentralisierte Nutzungsaufzeichnungen.

Für eine erste Integration beginnen Sie mit dem umfassenderen Seedance API-Schnellstart für Text-zu-Video-Produktteams. Wenn sich das Feature der Produktion nähert, wenden Sie diese Checkliste auf die Queue-, Status-, Retry-, Speicher- und Beobachtbarkeits-Schichten rund um den Modellaufruf an.

Wenn Ihr Team entscheidet, welche aktuelle Route und welche Nutzungskontrollen zum Rollout passen, prüfen Sie die Live-Modelle und Preise, bevor Sie die Produktionskonfiguration freigeben.

Häufig gestellte Fragen

Ist die Seedance API synchron oder asynchron?

Behandeln Sie die Videogenerierung als asynchronen Job. Ihr Produkt sollte Arbeit einreichen, seine eigene Job-ID zurückgeben und Statusaktualisierungen über Webhooks und/oder Polling gemäß der aktuellen API-Referenz verarbeiten.

Sollte ich eine Provider-Task-ID als Primärschlüssel meiner Datenbank verwenden?

Nein. Erstellen Sie vor der Einreichung Ihre eigene stabile Job-ID. Speichern Sie die Provider-Task-ID als externe Referenz, damit Sie abgleichen, erneut einreichen oder Routen ändern können, ohne den Produktbezeichner zu ändern.

Brauche ich sowohl Webhooks als auch Polling?

Für ein robustes Produktionssystem: ja. Webhooks liefern schnelle Updates; Polling stellt Jobs wieder her, deren Ereignisse verzögert, verpasst oder nicht verarbeitet wurden.

Wann ist es sicher, einen fehlgeschlagenen Seedance-Job erneut zu versuchen?

Wiederholen Sie nur nach Klassifizierung des Fehlers. Kapazitäts- und Netzwerkfehler können wiederholbar sein. Validierungs-, Authentifizierungs-, Sicherheits- oder andere endgültige Fehler erfordern in der Regel eine Konfigurations- oder Benutzeränderung. Wenn das Absenden ein Timeout hatte, gleichen Sie es über den Idempotency-Key ab, bevor Sie einen weiteren kostenpflichtigen Job senden.

Soll ich das generierte Video selbst speichern?

Ja. Kopieren Sie die fertige Ausgabe in von Ihnen kontrollierten Speicher, validieren Sie die Datei und speichern Sie die Metadaten. Von Anbietern gehostete Ergebnis-URLs sollten nicht als permanenter Produktspeicher betrachtet werden, es sei denn, die aktuellen Bedingungen garantieren dieses Verhalten ausdrücklich.

Wie sollte ich mit einer neuen Seedance-Modellversion umgehen?

Behandeln Sie sie als Migration: Verifizieren Sie den aktuellen Katalog, führen Sie einen festen Evaluierungssatz aus, vergleichen Sie Qualität, Latenz, Fehler und Kosten, leiten Sie Traffic im Canary-Verfahren und behalten Sie einen Rollback-Pfad, bis die Änderung stabil ist.

Welches Seedance-Modell sollte ich fest codieren?

Vermeiden Sie es, ein Modell dauerhaft auf Basis eines statischen Artikels fest zu verdrahten. Lösen Sie ein Produktfähigkeitsprofil auf ein Modell auf, das im aktuellen Flatkey-Modellverzeichnis aufgeführt ist, und speichern Sie die gewählte Route in der Konfiguration, damit Betreiber sie sicher ändern können.