TokenLab Seedance Materials: Wiederverwendbare Videoreferenzen für Produktions-Workflows

Wenn Ihr Team schon einmal dieselbe Face-Swap-URL in drei verschiedene API-Aufrufe kopiert hat, wissen Sie bereits, warum es die Seedance-Materialbibliothek gibt. Wiederverwendbare Videoreferenzen funktionieren besser als Assets mit Lebenszyklusstatus als als einmalige URLs, die aus einer Tabelle in jede Generierungsanfrage kopiert werden. TokenLab weist diese Assets Ihrer Organisation zu, sodass Sie Referenzen speichern, verifizieren und über Aufrufe hinweg wiederverwenden können. Wir haben die Workflow-Struktur getestet: Gruppen organisieren Material von echten Personen, Assets enthalten die eigentliche Referenz, und Generierungsaufrufe verwenden IDs erst, nachdem der Status ACTIVE erreicht wurde. Ein Team, das früher eine Tabelle mit Bildlinks führte und dasselbe Referenzvideo fünfmal neu hochlud, kann diese Gewohnheit beispielsweise durch eine einzige Material-Asset-ID ersetzen.

Wichtige Erkenntnisse

• Ein Material-Asset ist das generierungsbereite Referenzobjekt; eine Materialgruppe ist der Container, der zusammengehörige Assets organisiert, insbesondere für Workflows mit echten Personen.
• Verwenden Sie die id eines Material-Assets als material_asset_id (oder innerhalb von material_asset_ids) erst, nachdem der Status ACTIVE erreicht wurde.
• Es gibt zwei Bibliothekstypen: aigc_avatar für virtuelle Avatare und andere nicht reale, wiederverwendbare Referenzen sowie liveness_face für Materialgruppen mit echten Personen, die eine Verifizierung erfordern.
• TokenLab kann kompatible Bildeingaben (image, image_url, image_urls, reference_images, start_image, end_image) automatisch in Material-Assets umwandeln, ohne dass ein separater Upload-Schritt erforderlich ist.
• Wenn die Vorbereitung länger als 60 Sekunden dauert, gibt die API 409 seedance_material_preparing zusammen mit auto_material_asset_ids zurück, die Sie abfragen und erneut versuchen können.
• Seedance ist die aktuelle öffentliche Modellfamilie, die dieses Materialsystem unterstützt. Überprüfen Sie die genauen Fähigkeiten pro Modell in der Dokumentation, bevor Sie eine Abhängigkeit von einer bestimmten Stufe aufbauen.

Seedance-Materialbibliothek: Assets und Gruppen

Ein Seedance-Material ist eine wiederverwendbare Referenz – Bild, Video oder Audio –, die TokenLab als organisationsbezogenes Asset speichert und nicht als anfragebezogene URL. Anstatt bei jedem create-video-Aufruf einen Rohdateilink zu übergeben, laden oder importieren Sie die Referenz einmal, warten, bis sie generierungsbereit ist, und referenzieren sie dann in beliebig vielen nachfolgenden Aufrufen über ihre ID.

Dies ist aus drei praktischen Gründen wichtig. Erstens verschwenden wiederholte Uploads Bandbreite und erhöhen die Latenz bei jeder Anfrage, insbesondere bei großen Referenzvideos. Zweitens laufen Roh-URLs ab, werden rotiert oder vom ursprünglichen Speichersystem widerrufen. Ein von TokenLab verwaltetes Material-Asset weist diese Fragilität nicht auf. Drittens, und das ist für Teams, die charakter- oder markenkonsistente Videopipelines aufbauen, am relevantesten, bieten Materialien eine stabile Kennung, die Sie versionieren, prüfen und austauschen können, ohne jedes Mal Ihre Generierungslogik anpassen zu müssen.

Material-Assets vs. Materialgruppen

Die zwei Kernobjekte in diesem System sind das Material-Asset und die Material-Asset-Gruppe. Es ist leicht, diese zu verwechseln, wenn man die API-Referenz nicht genau gelesen hat.

Ein Material-Asset ist ein einzelnes Referenzobjekt – ein Avatar-Bild, ein liveness-verifiziertes Gesicht, ein Referenzvideoclip. Wenn Sie es erstellen, gibt die API eine id zurück. Diese id übergeben Sie schließlich an die Videogenerierungsaufrufe, sobald das Asset den Status ACTIVE erreicht hat.

Eine Material-Asset-Gruppe ist ein Container, der durch eine group_id identifiziert wird. Gruppen organisieren zusammengehörige Assets. Sie sind strukturell für Workflows mit echten Personen (liveness_face) erforderlich, bei denen die Verifizierung auf Gruppenebene erfolgt, bevor einzelne Assets hochgeladen werden können.

Kurz gesagt: group_id organisiert; material_asset_id generiert. Sie werden beide Felder in verschiedenen Teilen der API sehen. Die falsche Verwendung an der falschen Stelle ist der häufigste Integrationsfehler, den Teams bei diesem System machen.

Feld	Was es identifiziert	Wo Sie es verwenden
group_id	Eine Material-Asset-Gruppe (Container)	Erstellen oder Referenzieren einer Gruppe, insbesondere für Verifizierungs-Flows bei echten Personen
id (bei einem Material-Asset)	Eine einzelne wiederverwendbare Referenz	Wird zu material_asset_id, sobald ACTIVE
material_asset_id	Eine einzelne Asset-Referenz, singular	Wird an create-video für einen Referenz-Slot übergeben
material_asset_ids	Ein Array von Asset-Referenzen	Wird an create-video übergeben, wenn mehrere wiederverwendbare Referenzen benötigt werden

Vollständige Felddefinitionen und erforderliche Parameter sind in den API-Referenzen zu create material asset und create material asset group dokumentiert. Lesen Sie diese, bevor Sie dies in Produktionscode integrieren. Die Dokumentation behandelt die Workflow-Struktur, nicht jeden einzelnen Anfrageparameter.

Workflows für virtuelle Avatare und echte Personen

Seedance-Materialien unterstützen zwei Bibliothekstypen. Die Unterscheidung ist nicht kosmetisch – sie spiegelt zwei unterschiedliche Sicherheits- und Einwilligungsanforderungen wider.

aigc_avatar: Virtuelle Avatare und nicht reale Referenzen

Der Typ aigc_avatar umfasst wiederverwendbare Referenzen, die nicht an eine verifizierte echte Person gebunden sind: illustrierte Charaktere, synthetische Avatare, stilisierte Figuren, Produktmaskottchen und ähnliche Assets. Sie können diese direkt über den Erstellungs-Flow für Material-Assets ohne Verifizierungsschritt erstellen.

Wenn Ihr Produkt Videos mit fiktiven Charakteren oder Marken-Avataren generiert, ist dies mit ziemlicher Sicherheit der Bibliothekstyp, den Sie benötigen. Er hat einen einfacheren Erstellungspfad, da keine Identitätsverifizierung erforderlich ist.

liveness_face: Materialgruppen für echte Personen

Der Typ liveness_face ist für Materialgruppen gedacht, die auf dem Abbild einer echten Person basieren. Dies ist die Art von Referenz, die für gesichtskonsistente Videogenerierungen mit einer tatsächlichen Person verwendet wird. Da dies Identität und Einwilligung betrifft, erfordert TokenLab einen Verifizierungs-Flow, bevor Assets in die Gruppe hochgeladen werden können.

Die Verifizierungssequenz umfasst mehrere Schritte:

1. Sitzungserstellung – Ihr Backend fordert eine Verifizierungssitzung für die Gruppe an.
2. H5-Flow – die zu verifizierende Person führt eine Liveness-Prüfung über einen gehosteten Web-Flow durch. H5 bezieht sich auf eine mobile Web-Verifizierungsschnittstelle.
3. Callback – TokenLab benachrichtigt Ihr System, wenn die Verifizierungssitzung abgeschlossen ist.
4. Bind-Ergebnis – die verifizierte Identität wird an die Materialgruppe gebunden.
5. Gruppenbezogene Uploads – erst nach erfolgreicher Bindung können Material-Assets in diese spezifische Gruppe hochgeladen werden.

Das bedeutet, dass Materialien für echte Personen von Natur aus gruppenorientiert sind. Sie können nicht direkt zur Erstellung eines Assets springen, wie Sie es bei aigc_avatar tun können. Die Gruppe muss existieren und die Verifizierung bestehen, bevor ein Asset-Upload in sie gültig ist.

Checkliste: Auswahl des richtigen Bibliothekstyps

• Ist die Referenz das Gesicht oder Abbild einer echten, identifizierbaren Person? → Verwenden Sie liveness_face und planen Sie den Verifizierungs-Flow ein.
• Ist die Referenz synthetisch, illustriert oder ein nicht realer Avatar? → Verwenden Sie aigc_avatar und überspringen Sie die Verifizierung.
• Benötigt Ihr Produkt eine konsistente Identität über mehrere Generierungen hinweg für dieselbe echte Person? → Erstellen Sie die Gruppe einmal, verifizieren Sie einmal, verwenden Sie die Gruppe für zukünftige Assets wieder.
• Sind Sie unsicher, in welchen Typ eine vom Kunden bereitgestellte Referenz fällt? → Behandeln Sie sie als liveness_face, bis das Gegenteil bestätigt ist; prüfen Sie die Dokumentation, stellen Sie keine Vermutungen an.

Gehen Sie nicht davon aus, dass jedes Generierungsmodell oder jeder Anfragetyp beide Bibliothekstypen identisch unterstützt. Bestätigen Sie die aktuelle Unterstützung im Seedance Video Models guide, bevor Sie sich auf eine Architektur festlegen.

Funktionsweise der automatischen Materialvorbereitung

Nicht jede Referenz benötigt einen manuellen Upload-Schritt. TokenLab kann kompatible Bildeingaben als Teil einer Generierungsanfrage automatisch in Material-Assets umwandeln. Das spart einen Roundtrip bei einfachen Fällen.

Die Felder, die für die automatische Vorbereitung erkannt werden, sind:

• image
• image_url
• image_urls
• reference_images
• start_image
• end_image

Wenn Sie eines dieser Felder direkt in einen Generierungsaufruf übergeben, übernimmt TokenLab den Import und die Vorbereitung im Hintergrund. Sie müssen den Material-Asset-Endpunkt nicht zuerst separat aufrufen.

Was passiert, wenn die Vorbereitung länger als 60 Sekunden dauert?

Die Vorbereitung ist normalerweise schnell. Größere oder komplexere Referenzbilder können länger benötigen, um in ein generierungsbereites Asset verarbeitet zu werden. Wenn die Vorbereitung 60 Sekunden überschreitet, antwortet die API mit:

409 seedance_material_preparing

zusammen mit einem Feld auto_material_asset_ids, das die IDs der Assets enthält, die noch vorbereitet werden.

Dies ist kein Fehler im herkömmlichen Sinne. Es ist ein Signal zum erneuten Versuch. Ihre Integration sollte 409 seedance_material_preparing als eine "bitte später erneut prüfen"-Antwort behandeln, nicht als einen Fehler, der dem Endbenutzer angezeigt werden muss. Fragen Sie die zurückgegebenen Asset-IDs ab, warten Sie auf den Status ACTIVE und fahren Sie dann mit der Generierung unter Verwendung dieser IDs fort.

In unserer Pipeline behandeln wir diesen Status wie ein Rate-Limit-Backoff: erwartet, vorübergehend und im Code behandelt, anstatt als benutzerseitiger Fehler gemeldet zu werden. Wir empfehlen eine kleine Retry-Schleife, nicht nur einen einfachen Try/Catch-Block.

Verwendung der Seedance-Materialbibliothek bei der Generierung

Sobald ein Material-Asset – ob manuell hochgeladen oder automatisch vorbereitet – den Status ACTIVE erreicht, wird seine id als material_asset_id oder als Eintrag in material_asset_ids in einem create video-Aufruf verwendbar.

Der Kern-Workflow sieht wie folgt aus:

1. Entscheiden Sie, ob die Referenz eine echte Person ist oder nicht. Wählen Sie entsprechend liveness_face (mit Verifizierung) oder aigc_avatar.
2. Bei echten Personen: Erstellen Sie die Materialgruppe, führen Sie die Verifizierungssitzung und den H5-Flow durch, empfangen Sie den Callback und binden Sie das Ergebnis.
3. Erstellen oder importieren Sie das Material-Asset – entweder über einen direkten Upload-Aufruf oder indem Sie die automatische Vorbereitung ein kompatibles Bildfeld innerhalb einer Generierungsanfrage verarbeiten lassen.
4. Status prüfen. Übergeben Sie die Asset-ID erst dann an die Generierung, wenn sie ACTIVE meldet.
5. Wenn Sie 409 seedance_material_preparing erhalten, fragen Sie die zurückgegebenen auto_material_asset_ids ab und versuchen Sie es erneut, sobald sie ACTIVE sind.
6. Verwenden Sie die id als material_asset_id oder innerhalb von material_asset_ids in Ihrem create-video-Aufruf und zielen Sie auf ein aktuelles Seedance-Modell ab, je nach Ihren Latenz- und Qualitätsanforderungen.
7. Verwenden Sie dieselbe Asset-ID für zukünftige Generierungsaufrufe wieder, anstatt die Referenz erneut hochzuladen.

Hier spielt auch das Aufgabenmanagement eine Rolle. Ein Generierungsaufruf, der auf einem wiederverwendeten Material-Asset basiert, muss möglicherweise mitten im Prozess gestoppt werden. Dies kann aufgrund von Kostenkontrolle, einem geänderten kreativen Briefing oder einem schlechten Prompt geschehen. Lesen Sie unseren Begleitartikel zu Seedance-Aufgabenstornierung, um zu erfahren, wie sich Stornierungen auf laufende Video-Jobs auswirken.

Für einen breiteren Vergleich dessen, was derzeit bei Videogenerierungsmodellen auf TokenLab verfügbar ist, listet die Videomodell-Kategorieseite die aktuellen Optionen nebeneinander auf.

Praktische nächste Schritte

• Wenn Sie Prototypen erstellen, beginnen Sie mit aigc_avatar-Materialien. Der Erstellungspfad ist einfacher und es gibt keine Verifizierungsabhängigkeit, um die man sich zuerst kümmern muss.
• Wenn Ihr Produkt Konsistenz bei echten Personen erfordert, bauen Sie den Verifizierungs-Flow (Sitzung → H5 → Callback → Binden) als erstklassigen Teil Ihres Onboardings auf, nicht als Zusatz.
• Fügen Sie eine Retry-Schleife für 409 seedance_material_preparing hinzu, bevor Sie irgendetwas in die Produktion bringen. Behandeln Sie dies als erwartetes Verhalten, nicht als Randfall.
• Speichern Sie Material-Asset-IDs zusammen mit Ihren eigenen internen Referenzdatensätzen. Auf diese Weise müssen Sie nicht jedes Mal neu ableiten, welches Asset welchem Charakter oder Produkt zugeordnet ist.
• Überprüfen Sie die API-Referenzen für Material-Asset und Material-Asset-Gruppe direkt. Die Dokumentation beschreibt die Workflow-Struktur, und die genauen Anfrage-/Antwortfelder sollten anhand der aktuellen Dokumentation bestätigt werden, bevor Sie Integrationscode schreiben.

Das Seedance-Assets-Dashboard zeigt Status, Bibliothekstyp und Gruppenbeziehungen für Assets an, die Sie bereits erstellt haben.

Aktuelle Preise in unserer Übersicht zu KI-Video-API-Preisen 2026 helfen Ihnen zu verstehen, wie die Kosten mit der Nutzung skalieren. Sie können Ihre eigenen Nutzungsdaten auch verfolgen und exportieren, indem Sie die Anleitung in TokenLab-Dashboard-Nutzungsexporte verwenden.

FAQ

Wie unterscheiden sich Material-Assets und Materialgruppen?

Ein Material-Asset ist ein einzelnes wiederverwendbares Referenzobjekt – ein Avatar-Bild, ein liveness-verifiziertes Gesicht, ein Referenzvideoclip. Seine id wird zu material_asset_id, sobald ACTIVE. Eine Materialgruppe ist ein Container, der durch eine group_id identifiziert wird. Gruppen organisieren zusammengehörige Assets und sind für liveness_face-Workflows erforderlich. Kurz gesagt: group_id organisiert; material_asset_id generiert.

Warum gibt ein Generierungsaufruf 409 seedance_material_preparing zurück?

Die automatische Materialvorbereitung, die durch kompatible Bildfelder wie image_url oder start_image ausgelöst wird, kann länger als 60 Sekunden dauern. Wenn dies geschieht, gibt die API 409 seedance_material_preparing mit auto_material_asset_ids zurück. Fragen Sie diese IDs ab, warten Sie auf ACTIVE und versuchen Sie die Generierung erneut. Dies signalisiert einen vorübergehenden Status, keinen Fehler.

Benötigen Referenzen von echten Personen immer eine Verifizierung?

Ja. Verwenden Sie den Typ liveness_face und den zugehörigen Verifizierungs-Flow, wann immer die Referenz das Gesicht oder Abbild einer tatsächlich identifizierbaren Person betrifft. Der Flow erfordert eine Sitzungserstellung, eine H5-Liveness-Prüfung, einen Callback und einen Bindungsschritt, bevor Assets in diese Gruppe hochgeladen werden können. Nicht reale Referenzen, wie illustrierte oder synthetische Avatare, verwenden aigc_avatar und erfordern diesen Pfad nicht.

Kann ich ein Material-Asset für mehrere Seedance-Video-Jobs wiederverwenden?

Ja, sobald das Asset den Status ACTIVE erreicht hat. Verwenden Sie seine id als material_asset_id oder innerhalb von material_asset_ids in einem create-video-Aufruf. Verwenden Sie dieselbe Asset-ID für zukünftige Generierungsaufrufe wieder, anstatt die Referenz erneut hochzuladen. Wenn Sie einen laufenden Job stoppen müssen, lesen Sie Seedance-Aufgabenstornierung.

Quellen und Aktualität

• Seedance Video Models guide — https://docs.tokenlab.sh/guides/seedance-2-video — beobachtet am 09.07.2026
• Create Seedance material asset (API reference) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — beobachtet am 09.07.2026
• Create Seedance material asset group (API reference) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — beobachtet am 09.07.2026
• Create video (API reference) — https://docs.tokenlab.sh/api-reference/video/create-video — beobachtet am 09.07.2026
• TokenLab Seedance assets dashboard — /dashboard/seedance-assets — beobachtet am 09.07.2026

Das hier beschriebene API-Verhalten, die Feldnamen und die Statussemantik spiegeln die öffentliche Dokumentation und die Dashboard-Kopien zum Zeitpunkt des Beobachtungsdatums wider. Das Seedance-Materialsystem von TokenLab befindet sich in aktiver Entwicklung – bestätigen Sie aktuelle Parameternamen, Statuswerte und modellspezifische Unterstützung in den verlinkten Dokumenten, bevor Sie den Produktions-Integrationscode fertigstellen.

Wenn Sie eine Videopipeline aufbauen, die auf stabilen, wiederverwendbaren Referenzen basiert, beginnen Sie mit dem Seedance Video Models guide. Dies ist der schnellste Weg, um aktuelle Parameternamen zu sehen und zu bestätigen, was Ihre Zielmodellstufe tatsächlich unterstützt.