Guides médias
Matériels Seedance et vérification de personne réelle
Réutilisez des images, vidéos, audios ou une personne vérifiée dans Seedance
Les matériels Seedance vous permettent de réutiliser un fichier image, vidéo ou audio sans avoir à l'importer pour chaque génération. Les références à une personne réelle nécessitent un consentement et une vérification visuelle ; ce n'est pas le cas pour les personnes virtuelles, les produits et les styles.
Choisir un type de matériel
| Ce que vous souhaitez réutiliser | Que faire |
|---|---|
| Une image utilisée une seule fois | Envoyez son URL dans un champ d'image pris en charge ; cela ne crée pas d'ID de matériel réutilisable |
| Réutiliser une personne virtuelle, un produit ou un style | Créez un groupe aigc_avatar, créez un asset, attendez le statut ACTIVE, puis utilisez l'ID de l'asset |
| Réutiliser une personne réelle | Effectuez la validation visuelle, recevez son GroupId, créez un asset dans ce groupe, attendez le statut ACTIVE, puis utilisez l'ID de l'asset |
| Migrer un client de matériel Volcengine existant | Conservez la structure de la requête Action et utilisez la référence de matériel compatible Volc |
Groupes et matériels
| Élément | Champ REST | Champ Action | Signification |
|---|---|---|---|
| Groupe de matériel | group_id | GroupId | Regroupe les matériels associés |
| Matériel | id | Id | Un fichier image, vidéo ou audio importé ; utilisez cet ID une fois qu'il est actif |
| Groupe d'avatar virtuel | library_type: "aigc_avatar" | GroupType: "AIGC" | Ne nécessite pas de vérification de personne réelle |
| Groupe de personne réelle | library_type: "liveness_face" | GroupType: "LivenessFace" | Créé uniquement via un flux de validation visuelle réussi |
| Nom du projet | project_name | ProjectName | Sépare les matériels de différents projets ; par défaut default |
Gardez les ID de groupe et les ID d'asset séparés. Un groupe organise les téléchargements ; un ID d'asset est la référence utilisée par la génération vidéo. Les ID publics ressemblent à group-20260720123456-vrt01 et asset-20260720123457-def45.
Rétention du matériel
TokenLab conserve chaque asset matériel jusqu'à ce que vous supprimiez l'asset ou son groupe. Il n'est pas supprimé pour inactivité.
- Si un asset doit être préparé à nouveau lors de son utilisation, la première génération peut prendre un peu plus de temps. S'il n'est pas encore prêt, la requête renvoie
409 seedance_material_preparing; réessayez peu après. - La suppression d'un asset ou d'un groupe est permanente et irréversible.
URL d'image et matériels réutilisables
Envoyez des URL HTTP(S) publiques ou des URL de données prises en charge dans les champs d'image acceptés par le modèle sélectionné. Ces entrées suivent le chemin média normal et ne créent pas automatiquement d'ID de matériel réutilisables.
Pour les matériels réutilisables, créez un asset via l'API de matériel, attendez le statut ACTIVE, puis utilisez material_asset_id, material_asset_ids ou asset://<id> dans un champ média pris en charge. Conservez le rôle prévu de première image, dernière image ou image de référence.
Lorsqu'un matériel explicite est en cours de préparation, POST /v1/videos/generations renvoie 409 seedance_material_preparing avec inactive_asset_ids. Interrogez ces assets jusqu'à ce qu'ils soient ACTIVE, puis réessayez avec les mêmes ID de matériel. Si un asset est FAILED, inspectez error_message et corrigez-le ou réimportez-le avant de réessayer. Une requête de génération utilisant un asset ayant échoué renvoie 422 seedance_material_failed avec failed_asset_ids.
Matériels d'avatar virtuel
Utilisez Créer un groupe d'assets matériels pour créer un groupe aigc_avatar. Pour la création d'asset REST, group_id est facultatif uniquement lorsque project_name est default ; TokenLab utilise ou crée alors le groupe d'avatar virtuel par défaut de l'organisation. Un project_name non défini par défaut, ainsi que tout asset de personne réelle, nécessite un group_id.
Une fois qu'un groupe existe, gérez-le avec :
- Lister les groupes d'assets matériels
- Obtenir un groupe d'assets matériels
- Mettre à jour un groupe d'assets matériels
- Supprimer un groupe d'assets matériels
La suppression d'un groupe supprime également les matériels TokenLab qu'il contient et est irréversible.
Vérification de personne réelle
Utilisez ce flux lorsque votre produit doit recueillir un consentement et vérifier un visage avant de réutiliser une personne réelle comme référence Seedance.
- Appelez Créer une session de validation visuelle avec
CallbackURL; enregistrezResult.BytedTokenet ouvrezResult.H5Linkpour la personne en cours de vérification. - Une fois que le flux H5 redirige vers le callback, interrogez Obtenir le résultat de la validation visuelle avec le même
BytedTokenetProjectName. - Stockez le
Result.GroupIdrenvoyé. TokenLab crée et lie le groupeLivenessFaceau cours de cette étape. - Créez un asset avec cet ID de groupe, puis interrogez l'asset jusqu'à ce qu'il devienne
ACTIVE.
BytedToken est valide pendant 30 minutes. Un client ne peut pas créer un groupe LivenessFace avec CreateAssetGroup ; cela empêche un groupe non vérifié d'être présenté comme vérifié.
Ouvrez le H5Link renvoyé immédiatement après la création. La validité du jeton ne signifie pas que la page de vérification peut être ouverte pour la première fois à tout moment dans cette fenêtre.
Pour un groupe de personne réelle, les téléchargements sont vérifiés par rapport au visage validé. Un asset peut échouer s'il contient plusieurs visages ou si le visage ne correspond pas. Pour de meilleurs résultats, téléchargez une référence de face avant en pied et un gros plan clair de face.
Créer et préparer un asset
Utilisez Créer un asset matériel pour importer une URL accessible publiquement à la fois.
| Type | Entrée prise en charge |
|---|---|
| Image | jpeg, png, webp, bmp, tiff, gif, heic, heif ; ≤ 30 Mo ; largeur et hauteur [300, 6000] px ; rapport hauteur/largeur [0.4, 2.5] |
| Vidéo | mp4, mov ; ≤ 200 Mo |
| Audio | aac, wav, mp3 ; ≤ 15 Mo |
Ce sont des limites d'importation de fichiers. Une requête d'importation réussie ne garantit pas que la validation du média ou de la personne réelle passera. Attendez le statut ACTIVE ; si l'asset devient FAILED, utilisez error_message pour corriger la source avant d'importer à nouveau.
L'ingestion de matériel est asynchrone. Interrogez Obtenir un asset matériel jusqu'à ce que le status devienne ACTIVE. Le succès HTTP signifie que l'importation a été acceptée, pas que l'asset est prêt. Si l'asset devient FAILED, inspectez error_message, corrigez la source et créez un nouvel asset.
L'URL source est uniquement utilisée pour l'importation. TokenLab renvoie son propre ID d'asset et conserve l'asset dans la bibliothèque de matériel de votre organisation jusqu'à ce que vous supprimiez l'asset ou son groupe.
Utiliser un asset dans la génération vidéo
Une fois qu'un asset est ACTIVE, choisissez l'une de ces formes lors de l'appel à Créer une vidéo :
material_asset_idpour une référence de matériel génériquematerial_asset_idspour plusieurs références génériquesasset://<asset-id>dansimage_url,start_image,end_imageoureference_imageslorsque le rôle du média doit être explicite
Les références de matériel comptent dans les limites de référence Seedance du modèle sélectionné. Si l'API renvoie Seedance material asset not found or not accessible, confirmez que la valeur est un ID d'asset plutôt qu'un ID de groupe, qu'elle appartient à la même organisation et au même projet, qu'elle n'est pas supprimée et qu'elle est ACTIVE.
REST ou Action Volcengine
Les intégrations natives TokenLab peuvent continuer à utiliser les points de terminaison REST /v1/videos/assets* en snake_case. Les clients Volcengine existants peuvent conserver les corps en PascalCase avec Actions matérielles (compatibles Volc). Les deux interfaces fonctionnent sur les mêmes données matérielles limitées à l'organisation et au projet.
Exemple REST : Asset d'avatar virtuel
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"Exemple Action : Asset de personne réelle vérifiée
Commencez par créer et terminer la validation visuelle :
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"}'Puis passez le GroupId renvoyé à 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"
}'Interrogez avec GetAsset jusqu'à ce que son statut soit Active, puis passez l'ID d'asset renvoyé à la génération vidéo. Pour les 10 opérations Action, les filtres, la pagination, les formes de réponse et les erreurs, consultez Actions matérielles (compatibles Volc).