Matériaux Seedance de TokenLab : références vidéo réutilisables pour les workflows de production

Les références vidéo réutilisables sont plus faciles à gérer lorsqu'il s'agit d'actifs dotés d'un statut de cycle de vie, plutôt que d'URL uniques copiées dans chaque requête de génération. Si vous avez déjà dû maintenir une feuille de calcul de liens d'images, retéléverser cinq fois la même vidéo de référence ou retaper une URL de face-swap dans trois appels API différents, vous comprenez déjà le problème que les matériaux Seedance sont conçus pour résoudre.

La bibliothèque de matériaux Seedance de TokenLab offre aux équipes vidéo un moyen, à l'échelle de l'organisation, de stocker, vérifier et réutiliser des références à travers les appels de génération. Cet article explique ce qu'est réellement un actif matériel, comment les groupes de matériaux sont liés aux actifs individuels, comment fonctionne la préparation automatique et où s'intègre la vérification des personnes réelles dans le flux de travail.

Points clés à retenir

• Un actif matériel (material asset) est l'objet de référence prêt pour la génération ; un groupe de matériaux (material group) est le conteneur qui organise les actifs associés, particulièrement pour les flux de travail impliquant des personnes réelles.
• N'utilisez l'id d'un actif matériel comme material_asset_id (ou à l'intérieur de material_asset_ids) qu'une fois que son statut atteint ACTIVE.
• Il existe deux types de bibliothèques : aigc_avatar pour les avatars virtuels et autres références réutilisables ne concernant pas des personnes réelles, et liveness_face pour les groupes de matériaux de personnes réelles nécessitant une vérification.
• TokenLab peut préparer automatiquement des entrées d'image compatibles (image, image_url, image_urls, reference_images, start_image, end_image) en actifs matériels sans étape de téléversement distincte.
• Si la préparation dépasse 60 secondes, l'API renvoie 409 seedance_material_preparing avec les auto_material_asset_ids que vous pouvez interroger et réessayer.
• Seedance 2.0, Seedance 2.0 Fast et Seedance 2.0 Mini sont les modèles publics actuels pris en charge par ce système de matériaux. Vérifiez les détails précis des capacités par modèle dans la documentation avant de créer une dépendance sur un niveau spécifique.

Qu'est-ce qu'un matériau Seedance ?

Un matériau Seedance est une référence réutilisable — image, vidéo ou audio — que TokenLab stocke en tant qu'actif à l'échelle de l'organisation plutôt qu'en tant qu'URL limitée à une requête. Au lieu de transmettre un lien de fichier brut dans chaque appel create-video, vous téléversez ou importez la référence une fois, attendez qu'elle soit prête pour la génération, puis vous la référencez par son ID dans autant d'appels ultérieurs que nécessaire.

Ceci est important pour trois raisons pratiques.

Premièrement, les téléversements répétés gaspillent de la bande passante et ajoutent de la latence à chaque requête, surtout pour les grandes vidéos de référence.

Deuxièmement, les URL brutes expirent, sont modifiées ou révoquées par le système de stockage qui les hébergeait initialement. Un actif matériel géré par TokenLab ne présente pas cette fragilité.

Troisièmement, et c'est le plus pertinent pour les équipes construisant des pipelines vidéo cohérents en termes de personnages ou de marque, les matériaux vous donnent un identifiant stable que vous pouvez versionner, auditer et remplacer sans toucher à votre logique de génération à chaque fois.

Actifs matériels vs Groupes de matériaux

Les deux objets principaux de ce système sont l'actif matériel et le groupe d'actifs matériels, et il est facile de les confondre si vous n'avez pas lu attentivement la référence de l'API.

Un actif matériel est un objet de référence unique — une image d'avatar, un visage vérifié, un clip vidéo de référence. Lorsque vous le créez, l'API renvoie un id. C'est cet id que vous passerez finalement dans les appels de génération vidéo une fois que l'actif aura atteint le statut ACTIVE.

Un groupe d'actifs matériels est un conteneur identifié par un group_id. Les groupes organisent les actifs associés, et ils sont structurellement requis pour les flux de travail impliquant des personnes réelles (liveness_face), où la vérification se fait au niveau du groupe avant que des actifs individuels puissent y être téléversés.

En résumé : le group_id organise ; le material_asset_id génère. Vous verrez les deux champs dans différentes parties de l'API, et utiliser le mauvais au mauvais endroit est l'erreur d'intégration la plus courante que font les équipes avec ce système.

Champ	Ce qu'il identifie	Où vous l'utilisez
group_id	Un groupe d'actifs matériels (conteneur)	Création ou référence d'un groupe, surtout pour les flux de vérification de personnes réelles
id (sur un actif matériel)	Une référence réutilisable unique	Devient material_asset_id une fois ACTIVE
material_asset_id	Une référence d'actif unique, singulier	Passé dans create-video pour un emplacement de référence
material_asset_ids	Un tableau de références d'actifs	Passé dans create-video lorsque plusieurs références réutilisables sont nécessaires

Les définitions complètes des champs et les paramètres requis sont documentés dans les références API create material asset et create material asset group. Lisez-les avant d'intégrer cela dans votre code de production — cet article couvre la forme du flux de travail, pas chaque paramètre de requête.

Flux de travail pour avatars virtuels et personnes réelles

Les matériaux Seedance prennent en charge deux types de bibliothèques, et la distinction n'est pas cosmétique — elle reflète deux postures différentes en matière de sécurité et de consentement.

aigc_avatar : Avatars virtuels et références ne concernant pas des personnes réelles

Le type aigc_avatar couvre les références réutilisables qui ne sont pas liées à une personne réelle vérifiée : personnages illustrés, avatars synthétiques, figures stylisées, mascottes de marque et actifs similaires. Ceux-ci peuvent être créés directement via le flux de création d'actif matériel sans étape de vérification.

Si votre produit génère des vidéos autour de personnages fictifs ou d'avatars de marque, c'est presque certainement le type de bibliothèque que vous souhaitez. Il possède un chemin de création plus simple car aucune exigence de vérification d'identité n'y est attachée.

liveness_face : Groupes de matériaux pour personnes réelles

Le type liveness_face est destiné aux groupes de matériaux construits autour de l'apparence d'une personne réelle — le type de référence utilisé pour la génération vidéo cohérente de visages mettant en scène un individu réel. Comme cela touche à l'identité et au consentement, TokenLab exige un flux de vérification avant que les actifs puissent être téléversés dans le groupe.

La séquence de vérification comporte plusieurs étapes distinctes :

1. Création de session — votre backend demande une session de vérification pour le groupe.
2. Flux H5 — la personne vérifiée effectue un contrôle de vivacité via un flux web hébergé (c'est ce à quoi "H5" fait référence : une interface de vérification web mobile).
3. Callback — TokenLab notifie votre système lorsque la session de vérification se termine.
4. Liaison du résultat — l'identité vérifiée est liée au groupe de matériaux.
5. Téléversements au niveau du groupe — ce n'est qu'une fois la liaison réussie que les actifs matériels peuvent être téléversés dans ce groupe spécifique.

Cela signifie que les matériaux pour personnes réelles sont intrinsèquement axés sur le groupe : vous ne pouvez pas passer directement à la création d'un actif comme vous le faites avec aigc_avatar. Le groupe doit exister et réussir la vérification avant que tout téléversement d'actif dans celui-ci soit valide.

Checklist : Choisir le bon type de bibliothèque

• La référence est-elle le visage ou l'apparence d'une personne réelle identifiable ? → Utilisez liveness_face et prévoyez le flux de vérification.
• La référence est-elle synthétique, illustrée ou un avatar ne représentant pas une personne réelle ? → Utilisez aigc_avatar et ignorez la vérification.
• Votre produit a-t-il besoin d'une identité cohérente à travers plusieurs générations pour la même personne réelle ? → Construisez le groupe une fois, vérifiez une fois, réutilisez le groupe pour les futurs actifs.
• Vous n'êtes pas sûr du type de référence fournie par le client ? → Traitez-la comme liveness_face jusqu'à preuve du contraire ; vérifiez dans la documentation, ne supposez rien.

Ne supposez pas que chaque modèle de génération ou chaque type de requête prend en charge les deux types de bibliothèque de manière identique — confirmez la prise en charge actuelle dans le guide des modèles vidéo Seedance 2.0 avant de vous engager dans une architecture.

Comment fonctionne la préparation automatique des matériaux

Toutes les références ne nécessitent pas une étape de téléversement manuel. TokenLab peut préparer automatiquement des entrées d'image compatibles en actifs matériels dans le cadre d'une requête de génération, ce qui supprime un aller-retour pour les cas simples.

Les champs qu'il reconnaît pour la préparation automatique sont :

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

Si vous passez l'un de ces éléments directement dans un appel de génération, TokenLab gère l'importation et la préparation en arrière-plan plutôt que de vous obliger à appeler séparément le point de terminaison de l'actif matériel en premier.

Que se passe-t-il lorsque la préparation prend plus de 60 secondes ?

La préparation est généralement rapide, mais les images de référence plus grandes ou plus complexes peuvent prendre plus de temps à être traitées en un actif prêt pour la génération. Si la préparation dépasse 60 secondes, l'API répond avec :

409 seedance_material_preparing

ainsi qu'un champ auto_material_asset_ids contenant les ID des actifs en cours de préparation.

Il ne s'agit pas d'une erreur au sens conventionnel — c'est un signal pour réessayer. Votre intégration doit traiter 409 seedance_material_preparing comme une réponse de type "vérifiez à nouveau sous peu", et non comme un échec à présenter à l'utilisateur final. Interrogez les ID d'actifs renvoyés, attendez le statut ACTIVE, puis procédez à la génération en utilisant ces ID.

En pratique, cela signifie que votre pipeline de génération a besoin d'une petite boucle de réessai, pas seulement d'un simple try/catch. Les équipes construisant des pipelines vidéo automatisés doivent traiter ce statut de la même manière qu'elles traiteraient un backoff de limitation de débit (rate-limit) — attendu, transitoire et géré dans le code plutôt que rapporté comme une erreur côté utilisateur.

Comment utiliser les matériaux dans la génération

Une fois qu'un actif matériel — qu'il soit téléversé manuellement ou préparé automatiquement — atteint le statut ACTIVE, son id devient utilisable en tant que material_asset_id (ou en tant qu'entrée dans material_asset_ids) dans un appel create video.

Le flux de travail principal ressemble à ceci :

1. Décidez si la référence concerne une personne réelle ou non. Choisissez liveness_face (avec vérification) ou aigc_avatar en conséquence.
2. Si personne réelle : créez le groupe de matériaux, exécutez la session de vérification et le flux H5, recevez le callback et liez le résultat.
3. Créez ou importez l'actif matériel — soit via un appel de téléversement direct, soit en laissant la préparation automatique gérer un champ d'image compatible dans une requête de génération.
4. Vérifiez le statut. Ne passez pas l'ID de l'actif dans la génération tant qu'il n'indique pas ACTIVE.
5. Si vous obtenez 409 seedance_material_preparing, interrogez les auto_material_asset_ids renvoyés et réessayez une fois qu'ils passent à ACTIVE.
6. Utilisez l'id comme material_asset_id ou au sein de material_asset_ids dans votre appel create-video, en ciblant un modèle Seedance actuel tel que seedance-2.0, seedance-2.0-fast ou seedance-2.0-mini selon vos besoins en latence et en qualité.
7. Réutilisez le même ID d'actif pour les futurs appels de génération au lieu de retéléverser la référence.

C'est également là que la gestion des tâches est importante. Si un appel de génération basé sur un actif matériel réutilisé doit être arrêté en cours d'exécution — pour le contrôle des coûts, un changement de brief créatif ou un mauvais prompt — consultez notre article complémentaire sur l'annulation de tâche Seedance pour savoir comment l'annulation interagit avec les travaux vidéo en cours.

Pour une comparaison plus large de ce qui est actuellement disponible parmi les modèles de génération vidéo sur TokenLab, la page de catégorie des modèles vidéo liste les options actuelles côte à côte.

Prochaines étapes pratiques

• Si vous faites du prototypage, commencez avec les matériaux aigc_avatar — le chemin de création est plus simple et il n'y a pas de dépendance de vérification à construire autour en premier.
• Si votre produit nécessite une cohérence de personne réelle, construisez le flux de vérification (session → H5 → callback → liaison) comme une partie intégrante de votre onboarding, et non comme un ajout.
• Ajoutez une boucle de réessai pour 409 seedance_material_preparing avant de mettre quoi que ce soit en production — traitez cela comme un comportement attendu, pas comme un cas limite.
• Stockez les ID d'actifs matériels avec vos propres enregistrements de référence internes afin de ne pas avoir à redériver quel actif correspond à quel personnage ou produit.
• Consultez directement les références API material asset et material asset group — cet article décrit la forme du flux de travail, et les champs exacts de requête/réponse doivent être confirmés par rapport à la documentation actuelle avant d'écrire votre code d'intégration.

Vous pouvez parcourir la bibliothèque de matériaux directement dans le tableau de bord des actifs Seedance pour voir le statut, le type de bibliothèque et les relations de groupe pour les actifs que vous avez déjà créés.

Avant de vous engager dans un flux de travail de production, il est utile de consulter les tarifs actuels dans notre aperçu de la tarification de l'API vidéo IA 2026 pour comprendre comment les coûts évoluent avec l'utilisation. Vous pouvez également suivre et exporter vos propres données d'utilisation en utilisant les conseils dans les exportations d'utilisation du tableau de bord TokenLab.

FAQ

Qu'est-ce qu'un actif matériel Seedance ? Un actif matériel est une référence de génération vidéo réutilisable — image, vidéo ou audio — stockée en tant qu'objet à l'échelle de l'organisation avec son propre statut de cycle de vie. Une fois qu'il atteint ACTIVE, vous pouvez le référencer par ID à travers plusieurs appels de génération au lieu de fournir à nouveau une URL brute à chaque fois.

Quelle est la différence entre group_id et material_asset_id ? group_id identifie un groupe d'actifs matériels, qui est un conteneur utilisé principalement pour organiser les actifs de personnes réelles (liveness_face) et gérer la vérification au niveau du groupe. material_asset_id identifie une référence réutilisable unique — l'id renvoyé lorsqu'un actif matériel est créé — et c'est ce que vous passez dans les appels de génération vidéo.

Quand dois-je utiliser la vérification des personnes réelles ? Utilisez le type liveness_face et son flux de vérification chaque fois que le matériel de référence implique le visage ou l'apparence d'une personne réelle identifiable. Le flux nécessite la création d'une session, un contrôle de vivacité H5, un callback et une étape de liaison avant que tout actif puisse être téléversé dans ce groupe. Les références ne concernant pas des personnes réelles, comme les avatars illustrés ou synthétiques, utilisent aigc_avatar et ne nécessitent pas ce chemin de vérification.

Que signifie seedance_material_preparing ? Il s'agit d'une réponse 409 renvoyée lorsque la préparation automatique des matériaux — déclenchée par des champs d'image compatibles comme image_url ou start_image dans une requête de génération — prend plus de 60 secondes à se terminer. La réponse inclut auto_material_asset_ids afin que vous puissiez interroger ces ID et réessayer la génération une fois qu'ils deviennent ACTIVE. Cela signale un état transitoire en cours, pas un échec.

Sources et fraîcheur

• Guide des modèles vidéo Seedance 2.0 — https://docs.tokenlab.sh/guides/seedance-2-video — observé le 09/07/2026
• Créer un actif matériel Seedance (référence API) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — observé le 09/07/2026
• Créer un groupe d'actifs matériels Seedance (référence API) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — observé le 09/07/2026
• Créer une vidéo (référence API) — https://docs.tokenlab.sh/api-reference/video/create-video — observé le 09/07/2026
• Tableau de bord des actifs Seedance de TokenLab — https://tokenlab.sh/en/dashboard/seedance-assets — observé le 09/07/2026

Le comportement de l'API, les noms des champs et la sémantique des statuts décrits ici reflètent la documentation publique et le contenu du tableau de bord à la date observée. Le système de matériaux Seedance de TokenLab est en développement actif — confirmez les noms des paramètres actuels, les valeurs de statut et la prise en charge spécifique aux modèles dans les documents liés avant de finaliser le code d'intégration de production.

Si vous construisez un pipeline vidéo qui dépend de références stables et réutilisables, commencez par le guide des modèles vidéo Seedance 2.0 — c'est le moyen le plus rapide de voir les noms des paramètres actuels et de confirmer ce que votre niveau de modèle cible prend réellement en charge.