Comment utiliser les Seedance Private Assets avec la Seedance API

PiAPI prend désormais en charge Seedance Private Asset Library, un workflow Seedance API qui permet d'importer des références réutilisables et de les rappeler ensuite avec asset://<asset_id>.

Cette bibliothèque permet d'importer une référence de visage, de personnage, de produit, de scène, de vidéo ou d'audio, puis de l'utiliser dans de futures tâches Seedance API. Elle convient surtout aux workflows de référence réutilisable et de cohérence de personnage, pas au face swap classique, à l'inpainting ou à la retouche image pixel-perfect.

Points clés

• Utilisez des private assets lorsqu'un visage, personnage, produit ou sujet doit apparaître dans plusieurs générations vidéo.
• Utilisez des URL brutes pour les décors, arrière-plans, accessoires ou références qui ne servent qu'une fois.
• Utilisez auto_upload_assets: true lorsqu'une référence fournie par l'utilisateur doit être importée temporairement pour une seule tâche.
• Un private asset doit atteindre l'état Active avant d'être utilisé dans une tâche Seedance.
• Les références asset:// fonctionnent avec seedance-2-less-restriction et seedance-2-fast-less-restriction, pas avec les task types stricts.

Réponse rapide

Les Seedance private assets sont faits pour les références réutilisables dans la Seedance API. Importez la référence une fois, attendez Active, puis utilisez-la dans de futures tâches vidéo avec asset://<asset_id>.

Que sont les Seedance Private Assets ?

Ce sont des fichiers réutilisables que votre application importe dans PiAPI avant la génération vidéo. Après l'import, PiAPI renvoie un asset_id. Une fois l'asset Active, vos requêtes Seedance API peuvent l'utiliser avec ce format. Les détails d'endpoint, quotas et cycle de vie sont dans la documentation Private Asset Library.

asset://<asset_id>

Au lieu d'envoyer encore et encore la même photo de visage, image de personnage, photo produit, vidéo ou référence audio, vous l'importez une seule fois et réutilisez son ID.

Un private asset est une référence réutilisable pour la génération vidéo Seedance.

Quel problème cela résout-il ?

La génération vidéo AI devient difficile lorsqu'un même sujet doit rester cohérent à travers plusieurs prompts, scènes ou variantes créatives. Une URL d'image brute peut suffire pour une tâche, mais elle n'est pas idéale pour des usages répétés.

Les cas d'usage courants incluent la cohérence d'une personne ou d'un personnage, des produits vidéo de type avatar ou influenceur, la réutilisation d'un produit dans plusieurs publicités, un casting stable pour des courts métrages, ou encore la réduction des uploads répétés côté backend.

Pour un aperçu du modèle, commencez par le guide Seedance 2.0 API.

Ce que les Private Assets ne sont pas

Seedance Private Asset Library ne doit pas être présenté comme du face swap, de l'inpainting ou du compositing exact. Si vous importez la photo d'une personne et une image de paysage, Seedance les utilise comme références de génération. Le résultat est une vidéo générée guidée par ces références, pas une insertion pixel par pixel.

Les Seedance private assets permettent une génération vidéo guidée par référence avec des sujets réutilisables.

Private Assets vs URL brutes vs Auto-Upload

Règle simple : si la référence sera réutilisée, créez un private asset. Si elle sert une seule fois, gardez une URL brute ou utilisez l'auto-upload.

Fonctionnement du workflow

1. Importer la référence réutilisable.
2. Attendre que le statut devienne Active.
3. Envoyer une tâche Seedance avec asset://<asset_id> dans image_urls, video_urls ou audio_urls.
4. Faire référence aux entrées dans le prompt comme Image 1, Image 2, Video 1 ou Audio 1.
5. Interroger la tâche jusqu'à ce que la vidéo soit terminée.

L'ordre est important. Si le private asset est le premier élément de image_urls et le paysage le second, Image 1 désigne le private asset et Image 2 le paysage.

{
  "image_urls": [
    "asset://asset-20260607154123-aaaa1",
    "https://your-cdn.com/scenic-background.jpg"
  ]
}

Dans le prompt, écrivez par exemple :

Image 1 is the person reference. Image 2 is the scenic background.

Exemple : personne réutilisable + paysage

Vous pouvez importer la photo d'une personne comme private asset, passer le paysage en URL brute et demander à Seedance de générer une vidéo à partir des deux références. Le résultat reste une vidéo générée, pas un compositing exact.

{
  "image_urls": ["asset://asset-person-reference", "https://your-cdn.com/scenic-background.jpg"],
  "prompt": "Image 1 is the person reference. Image 2 is the scenic background. Generate a cinematic 5-second video of the person from Image 1 standing naturally in the location from Image 2."
}

Exemple API

Étape 1 : importer un private asset

L'URL source doit rester publiquement accessible pendant l'ingestion par PiAPI. La garder disponible au moins 24 heures est une bonne pratique.

curl --request POST "https://api.piapi.ai/api/v1/asset/upload"
  --header "X-API-Key: $PIAPI_API_KEY"
  --header "Content-Type: application/json"
  --data '{"url":"https://your-cdn.com/person-reference.jpg","asset_type":"Image","name":"main-character"}'

Étape 2 : vérifier le statut

curl --request GET "https://api.piapi.ai/api/v1/asset/list?status=active,processing,failed"
  --header "X-API-Key: $PIAPI_API_KEY"

Si l'asset est encore Processing, attendez et vérifiez à nouveau. S'il est Failed, consultez l'erreur et importez un fichier corrigé.

Étape 3 : créer une tâche Seedance avec `asset://`

Utilisez seedance-2-less-restriction ou seedance-2-fast-less-restriction. Les variantes strictes seedance-2 et seedance-2-fast ne prennent pas en charge asset://.

Auto-Upload pour références ponctuelles

Si une référence ne sert qu'à une tâche, activez auto_upload_assets: true. PiAPI peut importer temporairement des URL non asset://, les utiliser pour la tâche, puis les nettoyer après la fenêtre de rétention.

Bonnes pratiques

• Réservez les private assets aux visages, personnages, produits ou sujets qui reviennent.
• Gardez les arrière-plans ponctuels en URL brute.
• Utilisez des libellés clairs dans le prompt : Image 1, Image 2, Video 1, Audio 1.
• Attendez Active avant de générer.
• Planifiez quotas, TTL et consentement des références utilisateur.

Erreurs courantes

Utiliser un task type strict

seedance-2 ne fonctionne pas avec asset://. Choisissez une variante less-restriction.

Référencer l'asset trop tôt

Suivez le flux : import -> poll du statut -> attendre Active -> soumettre la tâche Seedance.

Importer chaque arrière-plan comme asset

Gardez les emplacements d'assets pour les références qui doivent rester cohérentes sur plusieurs tâches.

FAQ

Qu'est-ce qu'un Seedance private asset ?

Une référence réutilisable importée dans PiAPI pour la génération vidéo Seedance. Une fois Active, elle peut être utilisée avec asset://<asset_id>.

Puis-je réutiliser une photo de visage ?

Oui, pour une génération guidée par référence. Ce n'est pas une garantie de face swap exact.

Est-ce identique au face swap ?

Non. Le but est la cohérence de sujet ou de personnage dans une vidéo générée.

Conclusion

Seedance Private Asset Library donne aux développeurs un moyen plus propre de construire des workflows de références réutilisables avec la Seedance API. Importez une référence, confirmez qu'elle est Active, puis lancez une tâche seedance-2-less-restriction avec l'asset, votre prompt et les URL ponctuelles nécessaires. Vous pouvez tester Seedance depuis le Seedance workspace.

Sources :

• PiAPI Private Asset Library docs: https://piapi.ai/docs/seedance-api/private-asset
• Seedance 2.0 arXiv page: https://arxiv.org/abs/2604.14148