TokenLab

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éutiliserQue faire
Une image utilisée une seule foisEnvoyez 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 styleCré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éelleEffectuez 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 existantConservez la structure de la requête Action et utilisez la référence de matériel compatible Volc

Groupes et matériels

ÉlémentChamp RESTChamp ActionSignification
Groupe de matérielgroup_idGroupIdRegroupe les matériels associés
MatérielidIdUn fichier image, vidéo ou audio importé ; utilisez cet ID une fois qu'il est actif
Groupe d'avatar virtuellibrary_type: "aigc_avatar"GroupType: "AIGC"Ne nécessite pas de vérification de personne réelle
Groupe de personne réellelibrary_type: "liveness_face"GroupType: "LivenessFace"Créé uniquement via un flux de validation visuelle réussi
Nom du projetproject_nameProjectNameSé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 :

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.

  1. Appelez Créer une session de validation visuelle avec CallbackURL ; enregistrez Result.BytedToken et ouvrez Result.H5Link pour la personne en cours de vérification.
  2. Une fois que le flux H5 redirige vers le callback, interrogez Obtenir le résultat de la validation visuelle avec le même BytedToken et ProjectName.
  3. Stockez le Result.GroupId renvoyé. TokenLab crée et lie le groupe LivenessFace au cours de cette étape.
  4. 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.

TypeEntrée prise en charge
Imagejpeg, png, webp, bmp, tiff, gif, heic, heif ; ≤ 30 Mo ; largeur et hauteur [300, 6000] px ; rapport hauteur/largeur [0.4, 2.5]
Vidéomp4, mov ; ≤ 200 Mo
Audioaac, 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_id pour une référence de matériel générique
  • material_asset_ids pour plusieurs références génériques
  • asset://<asset-id> dans image_url, start_image, end_image ou reference_images lorsque 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).

Sur cette page