La génération vidéo Seedance fonctionne en tâches asynchrones : la requête de création ne renvoie qu'un identifiant de tâche, la vidéo n'apparaît pas dans la réponse. L'intégrateur doit interroger l'état, gérer les échecs et transférer le résultat avant l'expiration du lien.

Si vous écrivez le code selon la logique synchrone de Chat Completions, vous expirerez probablement dès la première étape. Cet article suit l'ordre réel de mise en œuvre : URL de base, authentification, soumission, polling, téléchargement, webhook et idempotence.

Remarque : Seedance, ByteDance, Doubao, Volcengine et Volcano Ark sont des noms et marques de leurs détenteurs. Cet article est purement technique et ne représente aucun partenariat, agence ou autorisation ; chemins d'interface, noms de modèles et prix suivent la documentation officielle ou celle du site.

1. Paramètres d'accès : URL de base, modèle et authentification

L'URL de base officielle du plan de données de Volcano Ark est https://ark.cn-beijing.volces.com/api/v3, et le chemin de création d'une tâche vidéo est /contents/generations/tasks. L'authentification utilise Authorization: Bearer $ARK_API_KEY, avec un corps JSON.

Le champ model accepte un Model ID ou un Endpoint ID. La différence tient à l'authentification : avec une clé API, les deux fonctionnent généralement ; avec une signature AK/SK, il faut en principe renseigner l'Endpoint ID et non le Model ID. C'est l'un des pièges les plus fréquents en migration et en diagnostic.

Avant l'intégration, confirmez trois points : le modèle est-il activé, le quota du compte est-il suffisant, le canal courant prend-il en charge la durée et la résolution voulues. Les utilisateurs d'une passerelle doivent consulter la documentation du site pour vérifier que le canal vidéo et les champs de tâche correspondent à l'officiel.

Opération Méthode et chemin Remarque
Créer une tâche POST /contents/generations/tasks Renvoie l'ID de tâche, pas la vidéo
Interroger une tâche GET /contents/generations/tasks/{id} État et résultat
Lister les tâches GET /contents/generations/tasks Rapprochement et compensation par lots
Annuler une tâche Interface d'annulation ou de suppression selon la documentation Souvent valable seulement pour les tâches en file

Le support de l'annulation, de la suppression et du listing varie selon les plateformes ; consultez la documentation avant l'intégration. N'ajoutez pas /api/v3 en double à la fin de l'URL de base, sous peine d'erreur de chemin.

2. Soumettre une tâche : ce que contient un POST

Voici une requête de création courante, à titre d'exemple :

export ARK_API_KEY="your-api-key"
export BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

curl -sS -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {"type": "text", "text": "Port au petit matin, chargement de conteneurs, survol lent en drone, style réaliste"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}, "role": "first_frame"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false,
    "callback_url": "https://api.example.com/callbacks/seedance"
  }'

Quelques champs méritent attention :

  • content est un tableau ; texte, image de première frame, image de référence et vidéo de référence utilisent des type et role différents.
  • Les plages de duration, ratio et resolution varient selon la version du modèle ; ne recopiez pas la documentation d'un autre fournisseur.
  • watermark détermine la présence d'un filigrane ; vérifiez les règles de la plateforme avant un usage commercial.
  • callback_url reçoit la notification de fin de tâche ; sa prise en charge dépend de la plateforme réelle.
  • seed, camera_fixed, return_last_frame ne sont pas pris en charge par tous les modèles.

Après une soumission réussie, enregistrez immédiatement l'ID de tâche en base et associez-le au numéro métier. Le polling, les reprises, le rapprochement et l'imputation des coûts dépendent tous de cet ID.

3. Polling : machine à états et stratégie de backoff

L'interrogation ne nécessite que l'ID de tâche :

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

États courants et traitement :

status Signification Traitement conseillé
queued En file Attendre, annuler si nécessaire
running Génération en cours Continuer le polling, ne pas resoumettre
succeeded Succès Lire le résultat et le transférer immédiatement
failed Échec Consigner le code, décider si une reprise est possible
expired Délai dépassé Ajuster timeout ou paramètres puis resoumettre
cancelled Annulée Vérifier s'il s'agit d'une annulation métier volontaire

N'interrogez pas à intervalle fixe d'une seconde. Commencez à 5 secondes, puis 10, 20, avec un plafond d'environ 30 secondes et un peu de jitter pour éviter que plusieurs instances frappent l'amont simultanément. Fixez un timeout global selon le métier, par exemple 10 minutes ; au-delà, marquez « à vérifier » plutôt que d'attendre indéfiniment.

Les enregistrements de tâche ne sont consultables qu'un temps limité, environ 7 jours selon la documentation officielle. Passé ce délai, seul votre propre tableau de tâches fait foi : enregistrez les changements d'état sans attendre.

4. Télécharger et transférer le résultat

Après succès, la réponse contient l'adresse de la vidéo. Cette adresse est généralement temporaire — environ 24 heures selon la documentation — et certains modèles limitent le nombre de téléchargements. Ne la transmettez pas telle quelle au frontend ou au client comme une URL CDN permanente.

La bonne pratique : télécharger dès l'état succeeded, transférer vers votre stockage objet et enregistrer ID de tâche, numéro métier, chemin objet, taille et empreinte. Inscrivez ensuite l'adresse interne en base. Ainsi, même si le lien amont expire, les commandes historiques restent rejouables et livrables.

Le téléchargement doit aussi gérer gros fichiers, reprise interrompue, plafond de concurrence et reprises après échec. Si la réponse contient aussi une image de première frame ou un audio, transférez chaque champ séparément : ne conservez pas seulement la vidéo.

5. Webhook ou polling

Les deux méthodes donnent le résultat, avec des compromis différents :

Méthode Avantages Inconvénients Cas d'usage
Webhook Latence faible, moins de requêtes inutiles Nécessite une adresse publique, une vérification de signature et une protection contre le rejeu Tâches asynchrones de production
Polling Mise en œuvre simple, pas d'adresse publique Latence, requêtes supplémentaires Outils internes, tests, secours
Mixte Callback principal, polling de secours Déduplication d'état nécessaire La plupart des systèmes de production

Le plus robuste en production est « callback plus rapprochement » : le callback assure la faible latence, une tâche planifiée balaie les enregistrements sans état final depuis trop longtemps. L'interface de callback doit vérifier la signature et traiter l'idempotence : ne réinsérez pas ni ne déclenchez pas deux fois le même événement. La perte de callback n'est pas rare ; n'en faites pas l'unique canal de notification.

6. Idempotence et soumissions en double

Une tâche vidéo coûte cher et dure longtemps ; une double soumission coûte bien plus qu'avec une interface texte. Quatre niveaux de contrôle :

  • Générer une clé d'idempotence métier avant la soumission, par exemple numéro de commande plus version, et consulter la base avant d'envoyer.
  • Créer un index unique entre ID de tâche et numéro métier pour bloquer les doublons au niveau base.
  • Un timeout de requête n'équivaut pas à un échec de tâche. Vérifiez la base par clé d'idempotence, ou listez les tâches, avant de réessayer.
  • Ne réessayer que les 429, 5xx et erreurs réseau ; ne réessayez pas à l'aveugle un 400 de paramètres ni un refus de modération.

Consignez aussi le motif d'annulation et de resoumission. Sinon, une même commande peut produire plusieurs vidéos, ce qui augmente le coût et complique le rapprochement. Lancez chaque jour une tâche de réconciliation entre états, coûts et artefacts.

7. Erreurs fréquentes et diagnostic

  • 401 AuthenticationError : clé absente, invalide ou en-tête mal formé ; parfois URL de base et clé incompatibles.
  • 403 AccessDenied, AccountOverdueError : droits insuffisants, compte en retard de paiement ou service non activé.
  • 404 ModelNotOpen, UnsupportedModel : modèle non activé ou nom mal orthographié.
  • 400 SensitiveContentDetected : prompt ou média déclenchant la modération ; changez le média, ne réessayez pas en boucle.
  • 400 InvalidParameter : nom de champ, durée, ratio ou résolution hors plage admise.
  • 429 RateLimitExceeded : réduisez la concurrence et appliquez un backoff exponentiel ; demandez un quota supérieur si nécessaire.
  • failed ou expired : lisez error.code et error.message pour distinguer paramètres, refus de modération et panne amont.

Les chaînes de codes peuvent évoluer avec la plateforme ; fiez-vous à la réponse réelle et à la documentation des codes. Journalisez code brut, ID de requête et paramètres expurgés pour raccourcir nettement le diagnostic.

8. Liste de vérification pour une migration

Pour passer de l'interface officielle à une passerelle, ou d'une passerelle à une autre plateforme, validez chaque point :

  1. URL de base et authentification remplacées ensemble, pas seulement la clé.
  2. model contient-il un Model ID ou un Endpoint ID, compatible avec le mode d'authentification ?
  3. Noms de champs, durée, ratio et résolution entrent-ils dans le périmètre du nouveau canal ?
  4. L'énumération d'états couvre-t-elle file, exécution, succès, échec, timeout et annulation ?
  5. Validité du lien de résultat, limite de téléchargements et logique de transfert vérifiées.
  6. Adresse de callback accessible publiquement, signature et idempotence en place.
  7. Clé d'idempotence, table de tâches, réconciliation et alertes déjà en production.
  8. Limitation, timeouts, reprises et concurrence testés en charge.

Après migration, lancez un petit lot, comparez taux de réussite, durée moyenne et coût unitaire, puis augmentez progressivement. Ne basculez pas toute la production sans mécanisme de rapprochement.

Questions fréquentes

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

Généralement non. La création ne renvoie qu'un ID de tâche ; il faut interroger l'état ou attendre un callback, puis télécharger la vidéo. Une conception synchrone expire facilement et favorise les doubles soumissions.

Combien de temps conserver ID de tâche et résultat ?

Selon la documentation officielle, les tâches sont consultables environ 7 jours et le lien vidéo vaut environ 24 heures. Pour une conservation longue, transférez vers votre stockage objet.

Quel intervalle de polling choisir ?

Commencez à 5 secondes, puis espacez progressivement jusqu'à 15 à 30 secondes, avec un timeout global. Un polling fixe à haute fréquence gaspille des requêtes et déclenche plus facilement la limitation.

Les webhooks sont-ils pris en charge ?

L'interface officielle de création propose callback_url, mais la livraison dépend du réseau et des règles de la plateforme. La prise en charge par une passerelle suit la documentation du site ; en production, conservez un polling de secours.

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

Les règles varient selon la plateforme et le type d'échec. Avant l'intégration, vérifiez la facturation d'un refus de modération, d'un timeout et d'une annulation, et contrôlez avec un petit lot.

Pour aller plus loin

Faites d'abord tourner une tâche à durée minimale et résolution basse, puis complétez table de tâches, polling, transfert et rapprochement. Pour une entrée unifiée, inscrivez-vous sur ZSQH AI Gateway et vérifiez le canal Seedance et sa facturation sur la page Tarifs des modèles.

Articles liés :