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

Si votre équipe a déjà collé la même URL de face-swap dans trois appels API différents, vous savez déjà pourquoi la bibliothèque de matériaux Seedance existe. Les références vidéo réutilisables fonctionnent mieux en tant qu'actifs avec un statut de cycle de vie qu'en tant qu'URL uniques copiées depuis une feuille de calcul dans chaque requête de génération. TokenLab limite ces actifs à votre organisation, afin que vous puissiez stocker, vérifier et réutiliser les références entre les appels. Nous avons testé la structure du flux : les groupes organisent le matériel lié à des personnes réelles, les actifs contiennent la référence réelle, et les appels de génération ne consomment les identifiants qu'une fois le statut ACTIVE atteint. Par exemple, une équipe qui conservait autrefois une feuille de calcul de liens d'images et téléversait cinq fois la même vidéo de référence peut remplacer cette habitude par un seul identifiant d'actif matériel.

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.
• Utilisez l'id d'un actif matériel en tant que material_asset_id (ou à l'intérieur de material_asset_ids) uniquement après que son statut a 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 concernant des personnes réelles qui nécessitent une vérification.
• TokenLab peut automatiquement préparer 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 séparée.
• Si la préparation dépasse 60 secondes, l'API renvoie 409 seedance_material_preparing accompagné des auto_material_asset_ids que vous pouvez interroger et réessayer.
• Seedance est la famille de modèles publics actuelle prise en charge par ce système de matériaux. Vérifiez les détails des capacités spécifiques à chaque modèle dans la documentation avant de créer une dépendance envers un niveau spécifique.

Bibliothèque de matériaux Seedance : Actifs et groupes

Un matériau Seedance est une référence réutilisable — image, vidéo ou audio — que TokenLab stocke en tant qu'actif lié à l'organisation plutôt qu'en tant qu'URL lié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 seule fois, attendez qu'elle soit prête pour la génération, puis vous la référencez par son identifiant 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 offrent un identifiant stable que vous pouvez versionner, auditer et remplacer sans modifier 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. 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 finirez par transmettre 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. Ils sont structurellement requis pour les flux de travail impliquant des personnes réelles (liveness_face), où la vérification s'effectue 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. 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ù l'utiliser
group_id	Un groupe d'actifs matériels (conteneur)	Créer ou référencer 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	Transmis dans create-video pour un emplacement de référence
material_asset_ids	Un tableau de références d'actifs	Transmis 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. La documentation couvre la structure du flux, 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. 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. Vous pouvez les créer 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 qu'il vous faut. 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. C'est le type de référence utilisé pour la génération de vidéos cohérentes avec le visage d'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é. H5 fait référence à une interface de vérification mobile-web.
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 limités au 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 concernant des personnes réelles sont intrinsèquement basés sur les groupes. Vous ne pouvez pas passer directement à la création d'un actif comme vous pouvez le faire avec aigc_avatar. Le groupe doit exister et réussir la vérification avant que tout téléversement d'actif y soit valide.

Check-list : 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 sur 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 présumez rien.

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

Comment fonctionne la préparation automatique des matériaux

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

Les champs reconnus pour la préparation automatique sont :

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

Si vous transmettez l'un de ces champs directement dans un appel de génération, TokenLab gère l'importation et la préparation en arrière-plan. Vous n'avez pas besoin d'appeler le point de terminaison de l'actif matériel séparément au préalable.

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

La préparation est généralement rapide. 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

accompagné d'un champ auto_material_asset_ids contenant les identifiants des actifs en cours de préparation.

Ce n'est pas 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 plus tard", et non comme un échec à présenter à l'utilisateur final. Interrogez les identifiants d'actifs renvoyés, attendez le statut ACTIVE, puis procédez à la génération en utilisant ces identifiants.

Dans notre pipeline, nous traitons ce statut comme un backoff de limite de débit : attendu, transitoire, et géré dans le code plutôt que rapporté comme une erreur utilisateur. Nous recommandons une petite boucle de réessai, et non juste un simple try/catch.

Utilisation de la bibliothèque de matériaux Seedance 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 lors d'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 transmettez pas l'identifiant de l'actif à 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 en tant que material_asset_id ou dans material_asset_ids lors de votre appel create-video, en ciblant un modèle Seedance actuel selon vos besoins en latence et en qualité.
7. Réutilisez le même identifiant 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. Un appel de génération basé sur un actif matériel réutilisé peut avoir besoin d'être arrêté en cours d'exécution. Cela peut arriver pour des raisons de contrôle des coûts, un brief créatif modifié ou un mauvais prompt. Consultez notre article compagnon 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 des 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 au préalable.
• Si votre produit nécessite une cohérence pour les personnes réelles, construisez le flux de vérification (session → H5 → callback → liaison) comme une partie intégrante de votre onboarding, et non comme un ajout externe.
• 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 identifiants d'actifs matériels avec vos propres enregistrements de référence internes. De cette façon, vous ne redérivez pas quel actif correspond à quel personnage ou produit.
• Consultez directement les références API material asset et material asset group. La documentation décrit la structure du flux, et les champs exacts de requête/réponse doivent être confirmés par rapport à la documentation actuelle avant d'écrire le code d'intégration.

Le tableau de bord des actifs Seedance affiche le statut, le type de bibliothèque et les relations de groupe pour les actifs que vous avez déjà créés.

Les tarifs actuels dans notre aperçu tarification de l'API vidéo IA 2026 vous aident à 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 exportations d'utilisation du tableau de bord TokenLab.

FAQ

En quoi les actifs matériels et les groupes de matériaux diffèrent-ils ?

Un actif matériel est un objet de référence réutilisable unique — une image d'avatar, un visage vérifié, un clip vidéo de référence. Son id devient material_asset_id une fois ACTIVE. Un groupe de matériaux est un conteneur identifié par un group_id. Les groupes organisent les actifs associés et sont requis pour les flux de travail liveness_face. En résumé : le group_id organise ; le material_asset_id génère.

Pourquoi un appel de génération renvoie-t-il 409 seedance_material_preparing ?

La préparation automatique des matériaux, déclenchée par des champs d'image compatibles comme image_url ou start_image, peut prendre plus de 60 secondes. Lorsque cela se produit, l'API renvoie 409 seedance_material_preparing avec les auto_material_asset_ids. Interrogez ces identifiants, attendez ACTIVE, et réessayez la génération. Cela signale un état transitoire en cours, pas un échec.

Les références concernant des personnes réelles nécessitent-elles toujours une vérification ?

Oui. Utilisez le type liveness_face et son flux de vérification chaque fois que la 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.

Puis-je réutiliser un actif matériel sur plusieurs travaux vidéo Seedance ?

Oui, une fois que l'actif atteint ACTIVE. Utilisez son id en tant que material_asset_id ou dans material_asset_ids lors d'un appel create-video. Réutilisez le même identifiant d'actif pour les futurs appels de génération au lieu de retéléverser la référence. Si vous devez arrêter un travail en cours, consultez l'annulation de tâche Seedance.

Sources et fraîcheur

• Guide des modèles vidéo Seedance — 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 — /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 les copies du tableau de bord à la date observée. Le système de matériaux Seedance de TokenLab est en cours de 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 la documentation liée 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. 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.