Seedance est un modèle de génération vidéo de ByteDance, couramment utilisé pour les créations publicitaires, les vidéos courtes e-commerce et le prévisualisation de storyboards. Son API est très différente de celle des modèles texte : une requête ne renvoie pas directement une vidéo, elle crée d'abord une tâche, puis il faut interroger son état et enfin télécharger le résultat. Un intégrateur qui écrit son code sur le modèle de Chat Completions se bloque généralement dès la première étape.

Cet article suit l'ordre de mise en œuvre technique : authentification, soumission, interrogation, paramètres, tests, coûts et conformité. Les adresses d'interface, noms de modèles et modes de facturation évoluent rapidement ; la documentation officielle et celle du site font foi.

Remarque : Seedance, Doubao et Volcengine sont des marques de leurs détenteurs respectifs ; cet article ne fournit qu'une explication technique. Les chemins d'interface et noms de modèles des exemples sont illustratifs ; vérifiez-les dans la documentation officielle ou celle du site avant tout appel réel. Les prix sont ceux de la page de tarifs du site.

1. À quoi sert l'API Seedance

  • Vidéos de présentation de produits e-commerce, vidéos de visuel principal ;
  • Brouillons de créations pour publicités in-feed et vidéos courtes ;
  • Storyboards, films conceptuels, tests de style ;
  • Contenus verticaux pour les réseaux sociaux ;
  • Séquences de prévisualisation pour jeux et animation.

Elle ne convient pas à : l'actualité exigeant une exactitude factuelle stricte, les portraits de personnes réelles sans autorisation, les contenus juridiques ou médicaux soumis à des règles de marque précises. La contrôlabilité de la génération vidéo reste inférieure à celle d'un tournage réel ; pour une commande importante, prévoyez une relecture humaine avant diffusion.

2. Le flux de base d'une tâche asynchrone

Lire la configuration → Authentifier → Soumettre la tâche → Obtenir task_id
        → Interroger l'état (en file / en cours / succès / échec)
        → Succès : télécharger la vidéo ou obtenir une URL temporaire
        → Échec : lire le code d'erreur, décider d'un retry ou d'un abandon

Par rapport aux interfaces texte, une tâche vidéo ajoute trois coûts : le temps d'attente en file, les retries en cas d'échec et le stockage du résultat. Ces trois éléments doivent entrer dans la conception, sinon vous verrez apparaître en production des « requêtes expirées alors que la tâche tourne encore » et des « soumissions en double facturées deux fois ».

3. Authentification et préparation

  1. Vérifiez le canal : consultez la documentation du site pour savoir si la capacité vidéo Seedance est ouverte, quels modèles, durées et résolutions sont pris en charge.
  2. Créez une clé : dans la console, créez une clé dédiée nommée seedance-test ou seedance-prod.
  3. Confirmez le nom du modèle : copiez-le depuis la page de tarifs ou la documentation, sans reconstituer le suffixe de version de mémoire.
  4. Confirmez le mode de rappel : certains canaux prennent en charge le webhook, d'autres seulement l'interrogation.
  5. Préparez les ressources : convertissez l'image de première frame ou de référence en URL accessible publiquement, ou téléversez-la selon la documentation.
  6. Fixez un budget : plafonnez la clé de test pour éviter une grosse facture pendant le débogage.

L'authentification est généralement Authorization: Bearer <API_KEY>, mais certaines plateformes utilisent une signature AK/SK ou un jeton temporaire. La documentation réelle fait foi ; n'appliquez pas le mode d'authentification d'une plateforme à une autre.

4. Exemple de soumission de tâche

Voici une forme de requête courante ; chemins et champs sont illustratifs :

export SEEDANCE_API_KEY="votre-clé"
export BASE_URL="https://votre-passerelle-ou-adresse-officielle"

curl -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-video",
    "content": [
      {"type": "text", "text": "Rue de Shanghai après la pluie, travelling avant lent, rendu cinématographique, 16:9"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false
  }'

En cas de succès, la réponse contient un identifiant de tâche. Enregistrez-le en base et associez-le à votre numéro de commande : il servira à l'interrogation, aux retries et au rapprochement.

5. Interrogation et téléchargement

curl "$BASE_URL/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SEEDANCE_API_KEY"

Les états courants sont : en file, en cours, succès, échec. Recommandations :

  • Commencez l'interrogation avec un intervalle de 5 secondes, puis augmentez progressivement jusqu'à 15–30 secondes ;
  • Fixez un délai global, par exemple 10 minutes, puis marquez l'échec au lieu d'attendre indéfiniment ;
  • L'URL vidéo de la réponse de succès a généralement une durée de validité : transférez rapidement le fichier vers votre stockage objet ;
  • Pour les tâches échouées, consignez le code d'erreur et les paramètres de requête pour l'analyse.

6. Paramètres clés

Paramètre Rôle Conseil pratique
prompt / text Décrire la scène, l'action, le cadrage et le style Décrire d'abord le sujet, puis le cadrage et la lumière
Image de première frame Contrôler l'image de départ Utiliser une image nette et sans litige de droits
duration Durée de la vidéo Tester d'abord sur la durée la plus courte
resolution Résolution Tester en basse définition, monter pour le rendu final
ratio Format d'image Choisir 9:16 pour une diffusion verticale
seed Graine aléatoire Fixer la graine pour comparer les paramètres
watermark Filigrane Vérifier les règles de la plateforme avant un usage commercial

Les noms de paramètres varient selon les plateformes : certains utilisent image, d'autres image_url, d'autres encore écrivent la durée en chaîne. La documentation fait foi ; ne copiez pas directement le corps de requête d'un autre service.

7. Liste de contrôle avant mise en ligne

  1. L'authentification passe-t-elle, et un 401 est-il bien capturé ?
  2. Une tâche à durée minimale et résolution minimale réussit-elle ?
  3. L'identifiant de tâche est-il renvoyé de façon stable et consultable par identifiant ?
  4. Le timeout d'interrogation et le nombre maximal de retries sont-ils définis ?
  5. Les causes d'échec sont-elles lisibles et distingue-t-on refus de modération et erreur système ?
  6. La durée de validité de l'URL de résultat et la logique de transfert sont-elles vérifiées ?
  7. La facturation correspond-elle aux prévisions, et les tâches échouées sont-elles facturées ?
  8. La soumission concurrente déclenche-t-elle une limitation de débit ?

8. Comment estimer les coûts

Le coût vidéo est généralement bien supérieur à celui du texte ; ne regardez pas seulement le prix unitaire :

Coût par vidéo =
  prix unitaire × durée × coefficient de résolution
+ coût des retries
+ stockage et bande passante
+ temps de relecture humaine

La facturation peut se faire à la seconde générée, par palier de résolution ou par tokens vidéo convertis. Les prix unitaires exacts sont ceux de la page Tarifs des modèles. Lancez d'abord un petit lot de 20 à 50 vidéos, mesurez le taux de réussite, la durée moyenne et le coût unitaire, puis décidez de l'augmentation de volume.

9. Modération de contenu et risques de droits

  • Droit à l'image : téléverser une photo de personne réelle ou générer un personnage identifiable nécessite une autorisation.
  • Droit d'auteur : images de référence, styles, musique et marques peuvent impliquer des droits de tiers.
  • Politique de contenu : violence, contenu sexuel, illégal ou désinformation sont refusés ou retirés.
  • Publicité trompeuse : ne générez pas d'effets non conformes au produit réel.
  • Sécurité des données : les images et vidéos téléversées peuvent contenir des informations clients ; anonymisez et fixez la durée de conservation.
  • Périmètre commercial : l'usage commercial du contenu généré dépend des conditions de la plateforme et des autorisations sur vos ressources.

Mettez en place trois filtres : vérification des ressources avant soumission, échantillonnage humain après génération, validation par la marque ou le juridique avant diffusion. Un refus de modération n'est pas une panne technique : ne cherchez pas à le contourner en changeant des mots-clés.

10. Recommandations de stabilité

  • Persistez la table des tâches avec date de soumission, état, durée et coût ;
  • Séparez soumission et interrogation pour éviter d'attendre plusieurs minutes dans une même requête ;
  • Appliquez un backoff exponentiel aux 429 et 5xx ; ne réessayez pas aveuglément les erreurs de paramètres 4xx ;
  • Prévoyez un canal ou un modèle de secours, car les canaux vidéo peuvent faire la queue aux heures de pointe ;
  • Surveillez le taux de réussite, le temps P95 et le coût unitaire, avec un rapprochement quotidien.

Questions fréquentes

L'API Seedance renvoie-t-elle la vidéo de façon synchrone ?

Généralement non. La génération vidéo est le plus souvent une tâche asynchrone : il faut soumettre, puis interroger ou attendre un rappel, avant de télécharger le résultat.

Peut-on l'appeler directement depuis la Chine ?

Cela dépend du canal, du compte et des conditions de conformité. Vérifiez les conditions de service, la politique de contenu et la réglementation locale avant usage.

Combien de temps faut-il pour générer une vidéo ?

Cela dépend de la file, de la durée, de la résolution et de la charge amont ; de quelques dizaines de secondes à plusieurs minutes. En production, fixez des timeouts et des retries.

Une tâche échouée est-elle facturée ?

Les règles varient selon les plateformes. Avant intégration, vérifiez la facturation des échecs, des refus de modération et des annulations pour timeout.

Peut-on utiliser sa propre image comme première frame ?

La plupart des modèles vidéo le permettent, à condition que l'image soit accessible à la plateforme et que vous en déteniez les droits. Les champs exacts sont ceux de la documentation.

Pour aller plus loin

Vérifiez d'abord dans la documentation du site si le canal Seedance est ouvert, puis lancez une tâche avec la configuration minimale. Pour un point d'entrée unifié, créez une clé sur ZSQH AI Gateway et vérifiez les modèles disponibles sur la page Tarifs des modèles.

Articles liés :