Ressources Seedance et vérification des personnes

Les ressources Seedance sont des références d’image, de vidéo ou d’audio réutilisables dans une organisation. Choisissez d’abord le workflow : une ressource d’avatar classique et une ressource de personne vérifiée ne suivent pas le même parcours de création.

Choisir un workflow de ressourcesCopy Anchor Link

Concepts de matérielCopy Anchor Link

Les matériels Seedance sont des références réutilisables, limitées à l'organisation, qui peuvent être sélectionnées ultérieurement lors de la génération vidéo.

Gardez group_id et l' id de l'actif matériel séparés. group_id sert à organiser les téléchargements ; l' id de l'actif matériel sert à la génération vidéo. Si une requête vidéo renvoie Seedance material asset not found or not accessible, confirmez que vous avez transmis un id d'actif matériel et non un group_id, et que l'actif appartient à la même organisation, n'est pas supprimé et a le statut status: "ACTIVE".

Conservation des ressourcesCopy Anchor Link

TokenLab conserve chaque ressource matérielle jusqu’à ce que vous supprimiez la ressource ou son groupe. Elle n’est pas nettoyée pour inactivité côté TokenLab.

Le fournisseur amont Seedance peut supprimer sa propre copie de travail d’une ressource après 30 jours sans utilisation. Cela ne supprime pas votre ressource et ne change pas son ID : la prochaine fois que vous l’utilisez dans une requête de génération, TokenLab prépare automatiquement une nouvelle copie amont à partir de l’original stocké.

• La première génération après un nettoyage peut être un peu plus longue le temps de préparer la nouvelle copie. Si elle n’est pas encore prête, la requête renvoie seedance_material_preparing ; réessayez peu après.
• La suppression d’une ressource ou d’un groupe est définitive et irréversible.

URL d’images et ressources réutilisablesCopy Anchor Link

Envoyez des URL HTTP(S) publiques ou des data URL prises en charge dans les champs image du modèle choisi. Ces entrées suivent le traitement média habituel et ne créent pas automatiquement d’ID de ressource réutilisable.

Pour réutiliser une ressource, créez-la via l’API de ressources, attendez ACTIVE, puis utilisez material_asset_id, material_asset_ids ou asset://<id> dans un champ média pris en charge. Conservez son rôle de première image, dernière image ou référence.

Si une ressource explicitement indiquée est encore en préparation, POST /v1/videos/generations renvoie 409 seedance_material_preparing avec inactive_asset_ids. Consultez ces ressources jusqu’à ACTIVE, puis réessayez avec les mêmes ID. En cas de FAILED, consultez error_message et corrigez ou réimportez la ressource avant de réessayer.

Vérification du matériel de personne réelleCopy Anchor Link

Utilisez la vérification du matériel de personne réelle lorsque votre produit nécessite un consentement et une vérification faciale avant qu'une personne réelle puisse être utilisée comme référence Seedance réutilisable.

1. Appelez Créer une session de validation visuelle avec CallbackURL et enregistrez le Result.BytedToken renvoyé.
2. Ouvrez Result.H5Link pour la personne à vérifier. Ajoutez lng au lien H5 si vous souhaitez une langue précise.
3. À la fin du parcours H5, le navigateur ouvre Result.CallbackURL avec des noms de requête officiels tels que bytedToken et resultCode.
4. Interrogez Obtenir le résultat de validation visuelle avec BytedToken jusqu’au retour de Result.GroupId.
5. Enregistrez GroupId et utilisez-le comme group_id lors de la création de ressources liveness_face.

BytedToken est valide 30 minutes. Utilisez le même ProjectName dans les deux requêtes Action. L’authentification utilise Authorization: Bearer <TOKENLAB_API_KEY> ; les signatures AK/SK Volc ne sont pas acceptées.

Ouvrez le H5Link renvoyé immédiatement après sa création. La validité du token ne garantit pas une première ouverture de la page de vérification à tout moment pendant cette période.

Optionnel : utilisez la console de test pour vérifier votre flux de requête et de rappel, inspecter les groupes de matériel et consulter l'historique de vérification. Votre intégration en production doit appeler les API directement.

Création de groupes de matérielCopy Anchor Link

Utilisez Créer un groupe d'actifs matériels pour les groupes aigc_avatar. Les nouveaux groupes de personnes réelles sont créés via le flux de vérification afin que la personne vérifiée et le groupe de matériel restent liés.

Utilisez Lister les groupes d'actifs matériels, Obtenir un groupe d'actifs matériels, Mettre à jour un groupe d'actifs matériels et Supprimer un groupe d'assets matériels pour gérer les groupes une fois qu'ils existent.

La suppression d'un groupe de matériel supprime également les matériels TokenLab qu'il contient et ne peut pas être annulée. Si la bibliothèque de matériel TokenLab ne peut pas effectuer la suppression car l'état d'autorisation actuel ne le permet pas, TokenLab renvoie une erreur neutre de bibliothèque de matériel.

Téléchargement de matérielsCopy Anchor Link

Utilisez Créer un actif matériel pour importer une URL source accessible publiquement à la fois.

Pour aigc_avatar, group_id est optionnel ; TokenLab utilise ou crée le groupe d'avatars virtuels par défaut de l'organisation. Pour liveness_face, group_id est requis et doit être le groupe renvoyé par Obtenir le résultat de validation visuelle.

Le tableau indique les limites d’importation. Une requête acceptée ne garantit pas la validation du média ou de la personne. Attendez ACTIVE ; en cas de FAILED, corrigez la source selon error_message avant de réimporter.

L'ingestion de matériel est asynchrone. Interrogez Obtenir un actif matériel jusqu'à ce que le status devienne ACTIVE. Une réponse HTTP réussie signifie seulement que la requête a été acceptée ; lisez toujours le statut métier. Si le statut est FAILED, inspectez error_message, corrigez le matériel source et créez un nouvel actif.

Dans les requêtes de création de matériel, asset_url est uniquement la source d’import. TokenLab renvoie un id de ressource matérielle ; utilisez cet id pour générer la vidéo au lieu de réutiliser l’URL d’origine.

TokenLab conserve les ressources matérielles dans la bibliothèque de votre organisation jusqu’à ce que vous supprimiez la ressource ou son groupe de matériel. La copie amont est recréée automatiquement si elle est nettoyée ; voir la section sur la conservation ci-dessus.

Pour les groupes de matériel de personne réelle, un groupe correspond à une personne réelle. Les téléchargements sont vérifiés par rapport au visage vérifié. Les actifs avec plusieurs visages ou un visage qui ne correspond pas à la personne vérifiée peuvent échouer. Pour de meilleurs résultats, téléchargez à la fois une image de référence du corps entier de face et un gros plan de face où le visage est clair.

Utilisation des matériels dans la génération vidéoCopy Anchor Link

Une fois qu'un actif est ACTIVE, transmettez l' id de l'actif TokenLab renvoyé en tant que material_asset_id, ou incluez-le dans material_asset_ids, lors de l'appel à Créer une vidéo. Les actifs matériels comptent dans les limites de référence Seedance.

REST ou Action VolcengineCopy Anchor Link

Une intégration native TokenLab peut continuer à utiliser l’API REST snake_case /v1/videos/assets*. Un client Volcengine existant peut conserver ses corps PascalCase avec les Actions de ressources compatibles Volcengine. Les deux interfaces manipulent les mêmes données limitées à l’organisation et au projet.

Exemples d'APICopy Anchor Link

Créez un groupe d'avatars virtuels, téléchargez une image, interrogez jusqu'à ce qu'elle soit active, puis utilisez l'ID de l'actif matériel dans une requête vidéo.

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"}'

curl https://api.tokenlab.sh/v1/videos/assets \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_type":"Image"}'

curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

Pour un groupe de ressources de personne réelle, créez une session de validation visuelle et obtenez son résultat avant de téléverser les ressources.

curl 'https://api.tokenlab.sh/api/v3?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/api/v3?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"ZXhhbXBsZS10b2tlbg","ProjectName":"default"}'

Parcours Action complet pour une personne réelleCopy Anchor Link

Transmettez à CreateAsset le GroupId renvoyé par le résultat de vérification.

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 GetAsset jusqu’à l’état Active, puis utilisez l’ID de ressource renvoyé dans la génération vidéo.