Medienleitfäden
Seedance-Materialien und Verifizierung echter Personen
Wiederverwendung von Bildern, Videos, Audio oder einer verifizierten Person in Seedance
Seedance-Materialien ermöglichen es Ihnen, eine Bild-, Video- oder Audiodatei wiederzuverwenden, ohne sie für jede Generierung neu importieren zu müssen. Referenzen auf eine echte Person erfordern eine Zustimmung und eine visuelle Verifizierung; bei virtuellen Personen, Produkten und Stilen ist dies nicht erforderlich.
Materialtyp wählen
| Was Sie wiederverwenden möchten | Vorgehensweise |
|---|---|
| Ein Bild, das einmal verwendet wird | Senden Sie dessen URL in einem unterstützten Bildfeld; dies erstellt keine wiederverwendbare Material-ID |
| Wiederverwendung einer virtuellen Person, eines Produkts oder Stils | Erstellen Sie eine aigc_avatar-Gruppe, erstellen Sie ein Asset, warten Sie auf ACTIVE und verwenden Sie dann die Asset-ID |
| Wiederverwendung einer echten Person | Führen Sie die visuelle Validierung durch, erhalten Sie die GroupId, erstellen Sie ein Asset in dieser Gruppe, warten Sie auf ACTIVE und verwenden Sie dann die Asset-ID |
| Migration eines bestehenden Volcengine-Material-Clients | Behalten Sie die Action-Request-Struktur bei und verwenden Sie die Volc-kompatible Materialreferenz |
Gruppen und Materialien
| Element | REST-Feld | Action-Feld | Bedeutung |
|---|---|---|---|
| Materialgruppe | group_id | GroupId | Hält zusammengehörige Materialien zusammen |
| Material | id | Id | Eine importierte Bild-, Video- oder Audiodatei; verwenden Sie diese ID, nachdem sie aktiv ist |
| Virtuelle-Avatar-Gruppe | library_type: "aigc_avatar" | GroupType: "AIGC" | Erfordert keine Verifizierung echter Personen |
| Gruppe für echte Personen | library_type: "liveness_face" | GroupType: "LivenessFace" | Wird nur durch einen erfolgreichen visuellen Validierungsprozess erstellt |
| Projektname | project_name | ProjectName | Hält Materialien aus verschiedenen Projekten getrennt; Standard ist default |
Halten Sie Gruppen-IDs und Asset-IDs getrennt. Eine Gruppe organisiert Uploads; eine Asset-ID ist die Referenz, die bei der Videogenerierung verwendet wird. Öffentliche IDs sehen aus wie group-20260720123456-vrt01 und asset-20260720123457-def45.
Materialaufbewahrung
TokenLab bewahrt jedes Material-Asset auf, bis Sie das Asset oder dessen Gruppe löschen. Es erfolgt keine automatische Bereinigung bei Inaktivität.
- Wenn ein Asset bei der Verwendung erneut vorbereitet werden muss, kann die erste Generierung etwas länger dauern. Wenn es noch nicht bereit ist, gibt die Anfrage
409 seedance_material_preparingzurück; versuchen Sie es in Kürze erneut. - Das Löschen eines Assets oder einer Gruppe ist permanent und kann nicht rückgängig gemacht werden.
Bild-URLs und wiederverwendbare Materialien
Senden Sie öffentliche HTTP(S)-URLs oder unterstützte Daten-URLs in den Bildfeldern, die von Ihrem gewählten Modell akzeptiert werden. Diese Eingaben folgen dem normalen Medienpfad und erstellen nicht automatisch wiederverwendbare Material-IDs.
Für wiederverwendbare Materialien erstellen Sie ein Asset über die Material-API, warten auf ACTIVE und verwenden dann material_asset_id, material_asset_ids oder asset://<id> in einem unterstützten Medienfeld. Behalten Sie die beabsichtigte Rolle für das erste Bild (First-Frame), letzte Bild (Last-Frame) oder Referenzbild bei.
Wenn ein explizites Material noch vorbereitet wird, gibt POST /v1/videos/generations den Status 409 seedance_material_preparing mit inactive_asset_ids zurück. Pollen Sie diese Assets, bis sie ACTIVE sind, und versuchen Sie es dann mit denselben Material-IDs erneut. Wenn ein Asset den Status FAILED hat, überprüfen Sie die error_message und korrigieren oder reimportieren Sie es, bevor Sie es erneut versuchen. Eine Generierungsanfrage, die ein fehlerhaftes Asset verwendet, gibt 422 seedance_material_failed mit failed_asset_ids zurück.
Virtuelle-Avatar-Materialien
Verwenden Sie Material-Asset-Gruppe erstellen, um eine aigc_avatar-Gruppe zu erstellen. Bei der REST-Asset-Erstellung ist group_id nur optional, wenn project_name auf default gesetzt ist; TokenLab verwendet oder erstellt dann die standardmäßige virtuelle Avatar-Gruppe der Organisation. Ein nicht standardmäßiger project_name sowie jedes Asset für echte Personen erfordern eine group_id.
Nachdem eine Gruppe existiert, verwalten Sie diese mit:
- Material-Asset-Gruppen auflisten
- Material-Asset-Gruppe abrufen
- Material-Asset-Gruppe aktualisieren
- Material-Asset-Gruppe löschen
Das Löschen einer Gruppe löscht auch die darin enthaltenen TokenLab-Materialien und kann nicht rückgängig gemacht werden.
Verifizierung echter Personen
Verwenden Sie diesen Ablauf, wenn Ihr Produkt eine Zustimmung einholen und ein Gesicht verifizieren muss, bevor eine echte Person als Seedance-Referenz wiederverwendet wird.
- Rufen Sie Visuelle Validierungssitzung erstellen mit
CallbackURLauf; speichern SieResult.BytedTokenund öffnen Sie denResult.H5Linkfür die zu verifizierende Person. - Nachdem der H5-Ablauf zum Callback weiterleitet, pollen Sie Ergebnis der visuellen Validierung abrufen mit demselben
BytedTokenundProjectName. - Speichern Sie die zurückgegebene
Result.GroupId. TokenLab erstellt und bindet dieLivenessFace-Gruppe während dieses Schritts. - Erstellen Sie ein Asset mit dieser Gruppen-ID und pollen Sie das Asset, bis es
ACTIVEwird.
BytedToken ist 30 Minuten lang gültig. Ein Client kann keine LivenessFace-Gruppe mit CreateAssetGroup erstellen; dies verhindert, dass eine nicht verifizierte Gruppe als verifiziert dargestellt wird.
Öffnen Sie den zurückgegebenen H5Link unmittelbar nach der Erstellung. Die Token-Gültigkeit bedeutet nicht, dass die Verifizierungsseite zu jedem beliebigen Zeitpunkt innerhalb dieses Zeitfensters zum ersten Mal geöffnet werden kann.
Für eine Gruppe mit echten Personen werden Uploads gegen das verifizierte Gesicht geprüft. Ein Asset kann fehlschlagen, wenn es mehrere Gesichter enthält oder das Gesicht nicht übereinstimmt. Für beste Ergebnisse laden Sie eine Ganzkörper-Frontalreferenz und eine klare Nahaufnahme von vorne hoch.
Erstellen und Vorbereiten eines Assets
Verwenden Sie Material-Asset erstellen, um jeweils eine öffentlich erreichbare URL zu importieren.
| Typ | Unterstützte Eingabe |
|---|---|
| Bild | jpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; Breite und Höhe [300, 6000] px; Seitenverhältnis [0.4, 2.5] |
| Video | mp4, mov; ≤ 200 MiB |
| Audio | aac, wav, mp3; ≤ 15 MiB |
Dies sind Limits für den Dateiimport. Eine erfolgreiche Importanfrage garantiert nicht, dass die Medien- oder Personenverifizierung erfolgreich ist. Warten Sie auf ACTIVE; wenn das Asset den Status FAILED annimmt, verwenden Sie die error_message, um die Quelle zu korrigieren, bevor Sie erneut importieren.
Die Materialaufnahme erfolgt asynchron. Pollen Sie Material-Asset abrufen, bis der status auf ACTIVE wechselt. Ein HTTP-Erfolg bedeutet nur, dass der Import akzeptiert wurde, nicht dass das Asset bereit ist. Wenn das Asset FAILED wird, überprüfen Sie die error_message, korrigieren Sie die Quelle und erstellen Sie ein neues Asset.
Die Quell-URL wird nur für den Import verwendet. TokenLab gibt eine eigene Asset-ID zurück und bewahrt das Asset in der Materialbibliothek Ihrer Organisation auf, bis Sie das Asset oder dessen Gruppe löschen.
Verwendung eines Assets bei der Videogenerierung
Nachdem ein Asset ACTIVE ist, wählen Sie eine dieser Formen beim Aufruf von Video erstellen:
material_asset_idfür eine generische Materialreferenzmaterial_asset_idsfür mehrere generische Referenzenasset://<asset-id>inimage_url,start_image,end_imageoderreference_images, wenn die Medienrolle explizit sein muss
Materialreferenzen zählen zu den Seedance-Referenzlimits des gewählten Modells. Wenn die API Seedance material asset not found or not accessible zurückgibt, bestätigen Sie, dass der Wert eine Asset-ID und keine Gruppen-ID ist, zur selben Organisation und zum selben Projekt gehört, nicht gelöscht wurde und ACTIVE ist.
REST oder Volcengine Action
TokenLab-native Integrationen können weiterhin die snake_case /v1/videos/assets* REST-Endpunkte verwenden. Bestehende Volcengine-Clients können PascalCase-Bodies mit Material Actions (Volc-kompatibel) beibehalten. Beide Schnittstellen arbeiten mit denselben organisations- und projektbezogenen Materialdaten.
REST-Beispiel: Virtuelles Avatar-Asset
curl https://api.tokenlab.sh/v1/videos/assets/groups \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"library_type":"aigc_avatar","group_name":"Product references","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_name":"Front view","asset_type":"Image","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45?project_name=default \
-H "Authorization: Bearer $TOKENLAB_API_KEY"Action-Beispiel: Verifiziertes Asset einer echten Person
Erstellen und schließen Sie zuerst die visuelle Validierung ab:
curl 'https://api.tokenlab.sh/?Action=CreateVisualValidateSession&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'
curl 'https://api.tokenlab.sh/?Action=GetVisualValidateResult&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'Übergeben Sie dann die zurückgegebene GroupId an CreateAsset:
curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"GroupId":"group-20260720123456-real1",
"URL":"https://example.com/person-front.png",
"Name":"Verified front view",
"AssetType":"Image",
"ProjectName":"default"
}'Pollen Sie mit GetAsset, bis der Status Active ist, und übergeben Sie dann die zurückgegebene Asset-ID an die Videogenerierung. Für alle 10 Action-Operationen, Filter, Paginierung, Antwortstrukturen und Fehler siehe Material Actions (Volc-kompatibel).