> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Documentation de l'API de génération de vidéos SeeDance
> ByteDance Seedance Video Generation API guide - Ace Data Cloud
Cet article présente une documentation sur l'intégration de l'API de génération de vidéos SeeDance, qui permet de générer des vidéos officielles de SeeDance en entrant des paramètres personnalisés.
## Processus de demande
Pour utiliser l'API de génération de vidéos SeeDance, commencez par obtenir votre jeton API sur le [tableau de bord Ace Data Cloud](https://platform.acedata.cloud/console/applications) et conservez-le pour référence.
Si vous n'êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inscrire et vous connecter, après quoi vous serez automatiquement renvoyé à la page actuelle.
**Un jeton API suffit pour appeler tous les services de la plateforme, sans avoir besoin de demander un pour chaque service.** La première demande vous donnera un quota gratuit pour une expérience sans frais ; si le quota est insuffisant, vous pouvez recharger le solde général sur le [tableau de bord](https://platform.acedata.cloud/console/coin).
> 📘 Documentation complète : [API de génération de vidéos SeeDance →](https://platform.acedata.cloud/documents/seedance-videos)
## Utilisation de base
Tout d'abord, comprenez la méthode d'utilisation de base, qui consiste à entrer le mot-clé `content.text`, le type `content.type=text` et le modèle `model`, pour obtenir le résultat traité, les détails sont les suivants :
Ici, nous avons configuré les en-têtes de requête, y compris :
* `accept` : le format de réponse souhaité, ici rempli avec `application/json`, c'est-à-dire au format JSON.
* `authorization` : la clé pour appeler l'API, que vous pouvez sélectionner directement après la demande.
Nous avons également configuré le corps de la requête, y compris :
* `model` : le modèle pour générer la vidéo.
* **Série Seedance 1.x** : `doubao-seedance-1-0-pro-250528`, `doubao-seedance-1-0-pro-fast-251015`, `doubao-seedance-1-5-pro-251215`, `doubao-seedance-1-0-lite-t2v-250428`, `doubao-seedance-1-0-lite-i2v-250428`.
* **Série Seedance 2.0** (supporte les entrées multimodales comme les références faciales / personnages) : `doubao-seedance-2-0-260128` (standard), `doubao-seedance-2-0-fast-260128` (rapide), `doubao-seedance-2-0-mini-260615` (léger). Voir la section « Références faciales et personnages (Seedance 2.0) » ci-dessous.
* `content` : tableau de contenu d'entrée, `type` peut être `text` (mot-clé), `image_url` (image de référence), `audio_url` (audio de référence, 2.0), `video_url` (vidéo de référence, 2.0). Les images peuvent être spécifiées par `role` : `first_frame` (première image) / `last_frame` (dernière image) / `reference_image` (référence faciale / personnage / sujet).
* `resolution` : résolution de sortie, options `480p` / `720p` / `1080p` (le modèle standard 2.0 supporte également `4k` ; 2.0 `fast` / `mini` maximum `720p`).
* `ratio` : rapport d'aspect, options `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`.
* `duration` : durée de la vidéo (secondes), plage 1.x 2–12, 2.0 2–15.
* `seed` : graine aléatoire, entier, -1 à 4294967295.
* `camerafixed` : si la caméra est fixe, `true` / `false`.
* `watermark` : si un filigrane doit être ajouté, `true` / `false`.
* `generate_audio` : si une vidéo audio doit être générée, `true` / `false`, **seulement `doubao-seedance-1-5-pro-251215` supporté**.
* `return_last_frame` : si l'URL de la dernière image de la vidéo doit être renvoyée dans le résultat.
* `execution_expires_after` : temps d'expiration de la tâche (secondes), plage 3600–259200.
* `callback_url` : adresse de rappel asynchrone, une fois définie, l'API renvoie immédiatement `task_id`, et lorsque la tâche est terminée, le résultat est POSTé à cette adresse.
* `async` : optionnel, si défini sur `true`, l'interface renvoie immédiatement `task_id`, sans avoir besoin de fournir `callback_url`, puis vous pouvez interroger le résultat via l'interface de requête de tâche correspondante.
Après avoir fait votre sélection, vous pouvez voir que le code correspondant a également été généré à droite, comme illustré ci-dessous :
Cliquez sur le bouton « Essayer » pour effectuer un test, comme montré ci-dessus, nous avons obtenu le résultat suivant :
```json theme={null}
{
"success": true,
"task_id": "9777f36b-4f44-47ff-962d-45cd2f7aeaa8",
"trace_id": "ce5da2ca-6695-4459-9d2c-2ef9f86db752",
"data": {
"task_id": "7e4e1773-510a-4a73-9ab4-98dd1a0b2a7f",
"status": "succeeded",
"model": "doubao-seedance-2-0-fast-260128",
"duration": 5,
"resolution": "720p",
"ratio": "16:9",
"video_url": "https://platform2.cdn.acedata.cloud/seedance/036f24ed-a9b1-49b3-92c4-30049a3bc152.mp4"
}
}
```
Le résultat de retour contient plusieurs champs, décrits comme suit :
* `success`, l'état de la tâche de génération de vidéo à ce moment.
* `task_id`, l'ID de la tâche de génération de vidéo à ce moment.
* `trace_id`, l'ID de suivi de la génération de vidéo à ce moment.
* `data`, la liste des résultats de la tâche de génération de vidéo à ce moment.
* `task_id`, l'ID côté serveur de la tâche de génération de vidéo à ce moment.
* `video_url`, le lien vers la vidéo générée à ce moment.
* `status`, l'état de la tâche de génération de vidéo à ce moment.
* `model`, le modèle utilisé pour générer la vidéo.
Nous avons obtenu des informations vidéo satisfaisantes, il nous suffit de récupérer la vidéo SeeDance générée à partir de l'URL de la vidéo dans `data`.
De plus, si vous souhaitez générer le code d'intégration correspondant, vous pouvez le copier directement, par exemple, le code CURL est le suivant :
```shell theme={null}
curl -X POST 'https://api.acedata.cloud/seedance/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
"content": [{"type":"text","text":"Une tasse à café en céramique blanche sur un comptoir en marbre brillant avec une douce lumière matinale provenant de la fenêtre. La caméra orbite lentement à 360 degrés autour de la tasse, de la vapeur s'élevant doucement."}],
"model": "doubao-seedance-2-0-fast-260128",
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}'
```
## Explication des paramètres en ligne
À la fin du mot-clé `content[].text`, vous pouvez passer des paramètres de génération en ajoutant `--parameter value` (ancienne méthode, faible validation, en cas d'erreur, les valeurs par défaut seront automatiquement utilisées). La liste complète des paramètres est la suivante :
| Paramètre en ligne | Champ correspondant | Description | Plage de valeurs |
| ------------------ | ------------------- | ---------------------------- | ------------------------------------------------------------- |
| `--rs` | `resolution` | Résolution de sortie | `480p` / `720p` / `1080p` |
| `--rt` | `ratio` | Rapport d'aspect | `16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive` |
| `--dur` | `duration` | Durée de la vidéo (secondes) | 2–12 |
| `--frames` | `frames` | Nombre de frames vidéo | Entiers satisfaisant 25+4n dans \[29, 289] |
| `--fps` | `framespersecond` | Taux de frames | Supporte uniquement `24` |
| `--seed` | `seed` | Graine aléatoire | -1 à 4294967295 |
| `--cf` | `camerafixed` | Caméra fixe ou non | `true` / `false` |
| `--wm` | `watermark` | Ajouter un filigrane ou non | `true` / `false` |
> **Pratique recommandée** : Utilisez directement les champs de niveau supérieur correspondants (comme `resolution`, `ratio`, etc.) dans le corps de la requête pour un mode de validation stricte. En cas d'erreur dans les paramètres, un message d'erreur clair sera renvoyé, facilitant le diagnostic des problèmes.
## Génération de vidéo avec audio
`doubao-seedance-1-5-pro-251215` prend en charge la génération de vidéos avec audio via le paramètre `generate_audio` :
```json theme={null}
{
"model": "doubao-seedance-1-5-pro-251215",
"content": [
{
"type": "text",
"text": "Une fille tient un renard, le vent souffle dans ses cheveux, on peut entendre le bruit du vent"
}
],
"generate_audio": true,
"ratio": "16:9",
"duration": 5
}
```
D'autres modèles ne prennent pas en charge ce paramètre, il sera ignoré s'il est transmis.
## Génération de la première image de vidéo
Pour générer une vidéo à partir d'une image, le paramètre `content` doit d'abord contenir un élément de type `image_url`, le champ `image_url` doit être au format objet : `{"url": "https://..."}` ou au format Base64 `{"url": "data:image/png;base64,..."}`.
> **Remarque** : `image_url` ne prend pas en charge la transmission directe au format chaîne (comme `"image_url": "https://..."`), il doit être au format objet `"image_url": {"url": "https://..."}`, sinon une erreur 400 sera renvoyée.
Code correspondant :
```python theme={null}
import requests
url = "https://api.acedata.cloud/seedance/videos"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/i2v_foxrgirl.png"
}
},
{
"type": "text",
"text": "Une fille tient un renard dans ses bras. Elle ouvre les yeux et regarde tendrement la caméra, tandis que le renard la tient affectueusement. Alors que la caméra s'éloigne lentement, ses cheveux sont doucement soufflés par le vent. --ratio adaptive --dur 5"
}
],
"model": "doubao-seedance-1-0-pro-250528"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
En cliquant sur exécuter, vous pouvez voir qu'un résultat est immédiatement obtenu, comme suit :
```
{
"success": true,
"task_id": "dc7cceb5-3c12-4de7-a5f4-abcbba3e8e39",
"trace_id": "b3b09de3-b7fa-4bb0-88b5-aad4b4a96fd4",
"data": {
"task_id": "cgt-20251222072003-x2259",
"status": "succeeded",
"video_url": "https://platform.cdn.acedata.cloud/seedance/6afb78b8-5ba8-424f-adcd-69423a700b50.mp4",
"model": "doubao-seedance-1-0-pro-250528"
}
}
```
On peut voir que l'effet généré est une vidéo à partir d'une image, le résultat est similaire à celui mentionné ci-dessus.
## Génération de la première et de la dernière image de vidéo
Pour générer la première et la dernière image d'une vidéo, le paramètre `content` doit d'abord inclure un type `image_url`, et les rôles doivent être respectivement définis comme `first_frame` et `last_frame`, permettant de spécifier le contenu suivant :
* role : spécifie la première ou la dernière image.
* image\_url
* url lien de l'image
De plus, `content` doit également inclure un type `text` comme mot-clé d'invite.
Code correspondant :
```python theme={null}
import requests
url = "https://api.acedata.cloud/seedance/videos"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "doubao-seedance-1-0-pro-250528",
"content": [
{
"type": "text",
"text": "Prise de vue à 360 degrés"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg"
},
"role": "first_frame"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
},
"role": "last_frame"
}
]
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
En cliquant sur exécuter, vous pouvez voir qu'un résultat est immédiatement obtenu, comme suit :
```
{
"success": true,
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
"trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
"data": {
"task_id": "cgt-20251222073134-54qcw",
"status": "succeeded",
"video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
"model": "doubao-seedance-1-0-pro-250528"
}
}
```
On peut voir que l'effet généré est une vidéo générée par des personnages, le résultat est similaire à celui mentionné ci-dessus.
## Références de visage et de personnage (Seedance 2.0)
**Série Seedance 2.0** (`doubao-seedance-2-0-260128`, `doubao-seedance-2-0-fast-260128`, `doubao-seedance-2-0-mini-260615`) prend en charge l'entrée de matériaux de référence « \*\*réel / personnage \*\* » : en ajoutant dans `content` un élément de type `image_url` et de rôle `reference_image`, en utilisant une photo de personne comme référence, le modèle conservera les caractéristiques d'apparence de cette personne dans la vidéo générée, permettant ainsi de « placer » la même personne dans de nouveaux décors, actions ou angles.
> 📌 Les photos de personnes réelles seront automatiquement enregistrées par la plateforme comme matériaux de base avant d'être utilisées pour la génération, tout le processus est totalement transparent pour l'appelant : **le format de demande et de réponse reste inchangé**, aucun paramètre supplémentaire n'est nécessaire, seule la première génération prendra quelques secondes de plus pour le traitement des matériaux.
Points d'utilisation :
* Seul le modèle **Seedance 2.0** prend en charge `reference_image` ; pour les modèles 1.x, veuillez utiliser `first_frame` / `last_frame` (première et dernière image du vidéo généré).
* `reference_image` **ne peut pas** être utilisé avec `first_frame` / `last_frame`, l'un ou l'autre doit être choisi.
* Limite du nombre de références multimodales : `image_url` au maximum **9** images ; 2.0 prend également en charge `audio_url` (rôle `reference_audio`, maximum 3) et `video_url` (rôle `reference_video`, maximum 3).
* Il est recommandé d'utiliser des photos de référence **d'une seule personne, de face, claires et sans obstruction** ; plus le visage est clair, plus la similarité est élevée.
### Exemple 1 : Gros plan sur le visage d'une personne
Transmettez une photo de visage pour que cette personne sourie et fasse un signe de la main vers la caméra. Le code correspondant :
```python theme={null}
import requests
url = "https://api.acedata.cloud/seedance/videos"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"model": "doubao-seedance-2-0-fast-260128",
"content": [
{
"type": "text",
"text": "La femme regarde la caméra, donne un sourire chaleureux et naturel et agite la main, éclairage doux en studio, léger zoom de la caméra."
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
}
}
],
"resolution": "480p",
"ratio": "9:16",
"duration": 5
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
Le résultat est le suivant, la personne dans la vidéo générée reste conforme à la photo de référence :
```json theme={null}
{
"success": true,
"task_id": "895eb5ea-bbe1-41a3-a9e9-48608e03f93a",
"trace_id": "83544791-7a84-44de-b8d2-afe171a1c0e4",
"data": {
"task_id": "458abf29-cc39-4fd0-bcea-24f89a70d8de",
"status": "succeeded",
"video_url": "https://platform2.cdn.acedata.cloud/seedance/e71d3cc5-27e7-4719-be34-1f0e254eccaf.mp4",
"model": "doubao-seedance-2-0-fast-260128",
"resolution": "480p",
"ratio": "9:16",
"duration": 5
}
}
```
### Exemple 2 : Placer la même personne dans un tout nouveau décor
La puissance de `reference_image` réside dans le fait de ne conserver que **l'identité de la personne**, tandis que le décor, les vêtements et les actions sont entièrement déterminés par les mots-clés. Voici comment, avec la même photo de visage, faire marcher cette personne en manteau beige dans un parc d'automne :
```json theme={null}
{
"model": "doubao-seedance-2-0-fast-260128",
"content": [
{
"type": "text",
"text": "La même femme portant un manteau beige marche dans un parc d'automne ensoleillé, des feuilles dorées tombent autour d'elle, elle sourit doucement à la caméra, prise de vue cinématographique."
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "https://platform2.cdn.acedata.cloud/nanobanana/8e075897-0f50-4443-8500-666751791c6c.jpg"
}
}
],
"resolution": "720p",
"ratio": "9:16",
"duration": 5
}
```
Le résultat est le suivant, l'apparence de la personne est conservée, tandis que le décor a été changé pour un parc d'automne :
```json theme={null}
{
"success": true,
"task_id": "00872de7-16b7-431f-b4f7-6bf38ae86157",
"trace_id": "577a07c3-4f5f-4cc7-86fe-535bb8332614",
"data": {
"task_id": "32fe1537-ba3e-452a-8749-3ef8890d37fd",
"status": "succeeded",
"video_url": "https://platform2.cdn.acedata.cloud/seedance/44f47593-556b-4fda-afa5-7a71eefcd228.mp4",
"model": "doubao-seedance-2-0-fast-260128",
"resolution": "720p",
"ratio": "9:16",
"duration": 5
}
}
```
> 💡 Si vous souhaitez que la personne reproduise précisément la composition de la photo (et non « un autre décor avec la même personne »), vous pouvez utiliser `first_frame` (première image du vidéo généré) pour que la vidéo commence à partir de cette photo.
## Callback asynchrone
Étant donné que l'API de génération de vidéos SeeDance prend un certain temps (environ 1 à 2 minutes), vous pouvez utiliser le champ `callback_url` pour activer le mode asynchrone, évitant ainsi une occupation prolongée de la connexion HTTP.
Processus global : lorsque le client initie une demande en spécifiant `callback_url`, l'API renvoie immédiatement une réponse contenant `task_id` ; une fois la tâche terminée, la plateforme envoie les résultats générés au format JSON POST à `callback_url`, les résultats contenant également `task_id` pour permettre l'association.
```json theme={null}
{
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd"
}
```
Lorsque la tâche est terminée, le contenu envoyé à `callback_url` par la plateforme est le suivant :
```json theme={null}
{
"success": true,
"task_id": "f7096c6c-9430-4392-8201-d259632d7afd",
"trace_id": "4a4a3721-00fb-43d2-aff2-3b516ac01a8a",
"data": {
"task_id": "cgt-20251222073134-54qcw",
"status": "succeeded",
"video_url": "https://platform.cdn.acedata.cloud/seedance/95f9f5f0-fc50-4c71-bc6f-e154582c141e.mp4",
"model": "doubao-seedance-1-0-pro-250528"
}
}
```
Le champ `task_id` dans le résultat est identique à celui renvoyé lors de la demande, permettant ainsi d'associer les tâches.
## Gestion des erreurs
Lors de l'appel de l'API, si une erreur se produit, l'API renverra le code d'erreur et les informations correspondantes. Par exemple :
* `400 token_mismatched` : Mauvaise requête, probablement en raison de paramètres manquants ou invalides.
* `400 api_not_implemented` : Mauvaise requête, probablement en raison de paramètres manquants ou invalides.
* `401 invalid_token` : Non autorisé, jeton d'autorisation invalide ou manquant.
* `429 too_many_requests` : Trop de demandes, vous avez dépassé la limite de taux.
* `500 api_error` : Erreur interne du serveur, quelque chose s'est mal passé sur le serveur.
### Exemple de réponse d'erreur
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "échec de la récupération"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Conclusion
Grâce à ce document, vous avez compris comment utiliser l'API de génération de vidéos SeeDance pour générer des vidéos à l'aide de mots-clés, d'images de référence, ainsi que des références de visage / personnage de Seedance 2.0. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, n'hésitez pas à contacter notre équipe de support technique.