Si vous créez des workflows vidéo sur Seedance 2.0 ou 2.0-Fast, l'Asset Library (bibliothèque d'actifs) est le moyen d'intégrer proprement vos médias de référence — images, vidéo et audio — dans vos générations. Au lieu de transmettre les médias bruts à chaque appel, vous enregistrez un fichier une seule fois, Atlas le valide et le prétraite, et vous le référencez via un identifiant stable pour autant de générations que vous le souhaitez.
Ce guide vous permet de passer de zéro à une référence fonctionnelle en trois appels cURL.
Ce qu'est (et ce que n'est pas) l'Asset Library
Il s'agit d'un espace de stockage de médias géré, dédié à la génération vidéo Seedance 2.0 / 2.0-Fast. Vous enregistrez un actif, il est prétraité, et une fois qu'il est à l'état Active, vous le référencez sous la forme asset://<asset_id> dans votre requête de génération.
Deux points à connaître dès le départ, car ils vous feront gagner du temps lors du débogage :
- Les fichiers vidéo et audio doivent être enregistrés ici en priorité. Ils ne peuvent pas être transmis en ligne (inline) sous forme d'URL dans une requête de génération. Seules les images peuvent être transmises directement. Pour tout workflow nécessitant une référence vidéo ou audio, l'Asset Library est donc le point d'entrée obligatoire, et non une simple option de confort.
- Le téléchargement se fait uniquement via une URL publique. Le format Base64 / les data URLs ne sont pas pris en charge. Le fichier doit être disponible à une URL accessible publiquement au moment de l'enregistrement.
Avant de commencer
Vous aurez besoin d'une clé API Atlas Cloud disponible dans le tableau de bord.
Un détail qui piège souvent les utilisateurs : l'Asset Library et l'API de génération se trouvent sur des hôtes différents.
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Fonction | Hôte | URL de base |
|---|---|---|
| Asset Library (enregistrer, interroger, gérer) | console | https://console.atlascloud.ai/api/v1 |
| Génération vidéo | api | https://api.atlascloud.ai/api/v1 |
Les deux utilisent le même en-tête d'authentification :
plaintext1export ATLASCLOUD_API_KEY="votre-cle-api-ici"
plaintext1Authorization: Bearer $ATLASCLOUD_API_KEY
Le processus en trois étapes
Enregistrer → interroger jusqu'à ce qu'il soit « Active » → référencer dans une génération.
Étape 1 — Enregistrer un actif
Pointez Atlas vers une URL publique. Définissez le type sur Image, Video ou Audio (par défaut : Image).
plaintext1curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 3 -H "Content-Type: application/json" \ 4 -d '{ 5 "type": "Video", 6 "url": "https://votre-hote-public.com/clip-de-reference.mp4" 7 }'
La réponse renvoie l'id de l'actif et un statut Processing.
Cela ressemblera à ceci :
Gardez précieusement l'id (surligné ci-dessus) — c'est ce que vous utiliserez pour interroger et référencer l'actif.
Note rapide : Qu'est-ce qu'une "URL publique" ?
C'est l'étape où les utilisateurs se trompent le plus souvent, soyez donc précis. Atlas récupère votre fichier en effectuant un simple HTTP GET sur l'URL. Cette URL doit renvoyer directement les octets du fichier brut — pas de connexion, pas de cookies, pas de page « cliquer pour voir », et aucun JavaScript requis pour le rendu.
Le test rapide : ouvrez l'URL dans un onglet de navigation privée. Si l'image s'affiche ou que la vidéo se télécharge sans authentification, Atlas pourra la récupérer. Si vous voyez une page de visionneuse, une invite de connexion ou une interface de prévisualisation, cela ne fonctionnera pas.
Cela signifie qu'un lien de partage Google Photos ou Google Drive ne fonctionnera pas. Ces liens pointent vers une page web qui affiche vos médias derrière le système d'authentification et de redirection de Google — et non vers le fichier lui-même. Atlas récupérerait la page d'habillage, pas le média.
Ce qui fonctionne :
- Stockage objet avec accès public-read ou URL pré-signée — Amazon S3, Google Cloud Storage, Cloudflare R2, Azure Blob. Les URLs pré-signées sont idéales : publiques mais limitées dans le temps.
- Un CDN ou votre propre serveur web servant le fichier directement.
- Le point de terminaison de téléchargement d'Atlas — si vous n'avez qu'un fichier local (ou un fichier exporté de Google Photos), téléchargez-le d'abord sur Atlas pour obtenir une URL de stockage publique, puis enregistrez cette URL :
plaintext1# Télécharger un fichier local → renvoie une URL public storage.atlascloud.ai 2curl -X POST "https://api.atlascloud.ai/api/v1/model/uploadMedia" \ 3 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 4 -F "file=@./clip-de-reference.mp4"
Récupérez le download_url de cette réponse et utilisez-le comme url lors de l'enregistrement de l'actif à l'étape 1.
Étape 2 — Interroger jusqu'à « Active »
Atlas valide et prétraite le fichier. Interrogez l'actif jusqu'à ce que son statut passe à Active. (Ce point de terminaison vérifie automatiquement le travail en amont tant qu'il est en cours de traitement).
plaintext1curl "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
Le cycle de vie est le suivant :
plaintext1Create → Processing → Active → (prêt à l'emploi) 2 ↓ 3 Failed → vérifiez error_code / error_message
Si le statut est Failed, les champs error_code et error_message vous indiqueront pourquoi — il s'agit presque toujours d'une limite de format, de taille, de durée ou de dimension. Consultez les tableaux de spécifications ci-dessous avant de procéder à un nouvel enregistrement.
Parfois, vous rencontrerez des erreurs de violation de politique comme ci-dessous — cela signifie que l'actif contrevient probablement aux garde-fous. Si vous êtes certain que l'actif ne viole aucune règle ou si vous en êtes le détenteur des droits d'auteur, veuillez nous contacter pour résoudre ce problème !
Étape 3 — Référencer dans une génération
Une fois l'actif à l'état Active, passez asset://<asset_id> dans le champ correspondant de votre requête Seedance — image, last_image, reference_images, reference_video ou reference_audio, selon le point de terminaison utilisé.
Notez le changement d'hôte ici : la génération s'effectue sur api.atlascloud.ai.
plaintext1curl -X POST "https://api.atlascloud.ai/api/v1/model/generateVideo" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 3 -H "Content-Type: application/json" \ 4 -d '{ 5 "model": "bytedance/seedance-2.0/image-to-video", 6 "input": { 7 "prompt": "Un plan travelling cinématique, lumière chaude de coucher de soleil", 8 "image": "asset://<asset_id>" 9 } 10 }'
Cela renvoie un identifiant de prédiction. Interrogez-le pour récupérer la vidéo finale :
plaintext1curl "https://api.atlascloud.ai/api/v1/model/prediction/<prediction_id>" \ 2 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
Lorsque le statut est completed (ou succeeded), l'URL du résultat se trouve dans outputs.
Voilà le cycle complet. L'intérêt de l'actif est la réutilisation : enregistrez une fois, référencez le même asset://<asset_id> dans autant de générations que nécessaire.
Gestion des actifs
La bibliothèque vous donne un contrôle total sur le cycle de vie.
plaintext1# Lister vos actifs (paginé, supporte les filtres) 2curl "https://console.atlascloud.ai/api/v1/sd/assets" \ 3 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 4 5# Renommer un actif 6curl -X PUT "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \ 7 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \ 8 -H "Content-Type: application/json" \ 9 -d '{ "name": "reference-coucher-de-soleil-v2" }' 10 11# Déplacer vers la corbeille (récupérable — il s'agit d'une suppression logique, pas physique) 12curl -X DELETE "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>" \ 13 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 14 15# Lister les actifs mis à la corbeille 16curl "https://console.atlascloud.ai/api/v1/sd/assets/trash" \ 17 -H "Authorization: Bearer $ATLASCLOUD_API_KEY" 18 19# Restaurer depuis la corbeille 20curl -X POST "https://console.atlascloud.ai/api/v1/sd/assets/<asset_id>/restore" \ 21 -H "Authorization: Bearer $ATLASCLOUD_API_KEY"
La suppression est réversible par conception — les actifs sont déplacés dans la corbeille et peuvent être restaurés, afin qu'une erreur de commande ne vous fasse pas perdre votre actif.
Exigences d'entrée
La validation s'effectue lors de l'enregistrement. Un fichier mal formé échouera donc à cette étape, avant que vous ne gaspilliez un appel de génération. Respectez ces limites pour éviter un statut Failed.
Image
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Propriété | Limite |
|---|---|
| Formats | jpeg, png, webp, bmp, tiff, gif, heic/heif |
| Ratio d'aspect (L/H) | 0.4 – 2.5 |
| Largeur / hauteur | 300 – 6000 px |
| Taille | < 30 Mo |
Vidéo
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Propriété | Limite |
|---|---|
| Formats | mp4, mov |
| Résolution | 480p, 720p |
| Durée | 2 – 15 s |
| Ratio d'aspect (L/H) | 0.4 – 2.5 |
| Largeur / hauteur | 300 – 6000 px |
| Total pixels (L×H) | 409 600 – 927 408 (ex: 640×640 à 834×1112) |
| Taille | ≤ 50 Mo |
| FPS | 24 – 60 |
Audio
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Propriété | Limite |
|---|---|
| Formats | wav, mp3 |
| Durée | 2 – 15 s |
| Taille | ≤ 15 Mo |
Codes d'erreur
td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}
| Code | Signification |
|---|---|
| 200 | Succès |
| 400 | Requête invalide |
| 401 | Clé API manquante ou invalide |
| 404 | Actif introuvable |
| 500 | Erreur serveur |
Points importants à retenir
- La vidéo et l'audio doivent être pré-enregistrés. Seules les images peuvent être transmises en ligne. Si vous ignorez l'enregistrement pour la vidéo/audio, la génération n'aura aucune référence à utiliser.
- URL uniquement, pas de base64. Le fichier source doit se trouver à une URL publique au moment de l'enregistrement.
- Deux hôtes. Actifs sur console.atlascloud.ai ; génération sur api.atlascloud.ai. Les confondre est la cause la plus courante d'erreurs 404 / 401.
- Validez puis générez. Les entrées incorrectes échouent à l'enregistrement, pas en cours de génération — c'est tout l'intérêt du processus. Vérifiez d'abord les tableaux d'exigences.
