Seedance est un modèle de génération vidéo de ByteDance. Contrairement aux modèles texte, son API fonctionne par tâches asynchrones : après soumission, vous obtenez un ID de tâche, devez interroger l'état, puis télécharger la vidéo en cas de succès. Pour une équipe en Chine, le vrai problème n'est pas seulement « la requête peut-elle partir », mais aussi le paiement et la facturation, la durée d'attente, l'archivage des résultats et la bascule en cas d'incident.

Cet article compare trois voies courantes : la connexion directe à Volcengine Ark, le proxy inverse auto-hébergé et la passerelle IA nationale, avec des méthodes de polling, de livraison et de validation.

Note : Seedance est le nom d'un modèle de génération vidéo de Volcengine, filiale de ByteDance (ByteDance) ; les marques associées appartiennent à leurs titulaires. Cet article est purement technique et n'implique aucune affiliation ni coopération avec ByteDance ; interfaces, modèles et prix sont ceux de la documentation officielle et de la page tarifs des modèles.

1. Les trois voies dans un seul tableau

Critère Connexion directe officielle Proxy auto-hébergé Passerelle IA nationale
Point d'entrée Adresse officielle Volcengine Ark Proxy inverse maintenu par vous Point d'entrée unifié compatible OpenAI
Réseau Dépend de la sortie locale et de la région Dépend du serveur proxy Maintenu par le fournisseur, toujours dépendant du réseau local
Paiement Selon les moyens de recharge officiels Serveur et bande passante à votre charge Recharge sur le site, règles selon la page
Facture Demande selon les règles officielles À gérer vous-même Selon les règles de facturation du fournisseur
Périmètre de modèles Modèles Seedance ouverts par l'officiel Dépend de la configuration du proxy Selon l'activation, peut inclure plusieurs modèles vidéo
Coût d'exploitation Faible Élevé Moyen
Équipe adaptée Modèle unique, capable de suivre le processus officiel Compétence en exploitation réseau Multi-modèles, facturation unifiée

Aucune voie ne convient à tout le monde. L'ordre de décision : l'activité tolère-t-elle une interruption, faut-il plusieurs modèles et des factures, l'équipe peut-elle maintenir un proxy dans la durée ?

2. Connexion directe : commencer par une tâche asynchrone

L'interface de génération vidéo de Volcengine Ark se déroule généralement en deux étapes, « créer la tâche + interroger la tâche », avec une URL de base du type https://ark.cn-beijing.volces.com/api/v3. Les régions disponibles, les ID de modèles et les champs exacts sont ceux de la console et de la documentation.

  1. Activer le modèle de génération vidéo dans la console Volcengine Ark et vérifier les exigences de compte et de conformité.
  2. Créer une clé API dédiée, nommée seedance-test, sans la mélanger avec la clé de production.
  3. Copier l'ID de modèle depuis la console, sans reconstituer le suffixe de version de mémoire.
  4. Soumettre une tâche de test avec la durée et la résolution minimales.
  5. Noter l'ID de tâche renvoyé, puis interroger l'état jusqu'à la fin.
export ARK_API_KEY="votre-clé"
export BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

curl -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ID de modèle copié depuis la console",
    "content": [
      {"type": "text", "text": "Rue urbaine après la pluie, travelling avant lent, rendu cinématographique"}
    ]
  }'

Si la requête expire mais qu'une tâche apparaît dans la console, c'est que la tâche a bien été créée : ne la soumettez pas immédiatement à nouveau, au risque de générer deux vidéos et une double facturation. Recherchez d'abord la tâche par numéro métier, puis décidez s'il faut réessayer.

3. Proxy auto-hébergé : régler la sortie, pas la file d'attente

La pratique courante consiste à déployer un proxy inverse sur un serveur qui accède de façon stable à l'interface officielle. Cela atténue les problèmes de sortie locale, mais crée de nouveaux travaux :

  • le serveur proxy est un point unique : s'il tombe, toutes les tâches échouent ensemble ;
  • il faut gérer TLS, authentification, contrôle d'accès et logs pour éviter les abus ;
  • les requêtes vidéo sont volumineuses et longues ; bande passante et nombre de connexions deviennent vite des goulots d'étranglement ;
  • un saut de plus n'accélère pas la file amont : en heure de pointe, il faut attendre quand même ;
  • la responsabilité réseau et conformité reste à l'équipe.

Sans personne dédiée à la maintenance, le proxy passe souvent de « solution temporaire » à « dette durable ». Il peut servir de transition, mais pas de point d'entrée unique.

4. Passerelle IA : réunir entrée, facturation et bascule

L'intérêt d'une passerelle IA nationale est de centraliser la gestion des clés, la recharge, le détail d'usage, les factures et le changement de modèle. Le code métier ne connaît qu'un point d'entrée ; changer de modèle devient une modification de configuration, pas de code. Pour une équipe qui utilise à la fois des modèles texte, image et vidéo, cela compte plus que quelques millisecondes de latence.

Lors du choix d'une passerelle, vérifiez : la capacité vidéo Seedance est-elle activée, quels modèles et paramètres sont pris en charge, comment les états de tâche sont mappés, comment sont facturés échecs et annulations, combien de temps l'URL de résultat est conservée, comment les incidents sont notifiés. Vous pouvez créer une clé de test sur ZSQH AI Gateway, exécuter une tâche minimale, puis vérifier la page tarifs des modèles et la base de facturation.

Une passerelle ne change pas la capacité amont. Elle unifie l'entrée et facilite la gestion des incidents, mais ne peut pas promettre l'absence de file d'attente aux heures de pointe.

5. Polling et livraison : la vraie difficulté de l'API vidéo

Selon la documentation Volcengine Ark, les états de tâche incluent généralement queued, running, succeeded, failed, cancelled et expired. L'interrogation ne couvre en général que les 7 derniers jours, et le video_url d'un résultat réussi est généralement nettoyé après 24 heures. Ces deux points déterminent directement la conception du système.

  • Séparer soumission et polling : une requête HTTP ne doit pas attendre plusieurs minutes en synchrone.
  • Commencer le polling à 5 secondes, puis reculer progressivement jusqu'à 15–30 secondes, avec un timeout global.
  • Une réponse de succès peut contenir un objet error ; en cas d'échec, enregistrer error.code et error.message.
  • Dès réception du video_url, télécharger vers votre stockage objet ; ne remettez pas une URL temporaire au métier pour un usage durable.
  • Après téléchargement, vérifier la taille et la lisibilité du fichier, puis générer votre URL signée ou adresse CDN.
  • L'annulation ne s'applique généralement qu'aux tâches en file ; les règles exactes sont dans la documentation.

La livraison du résultat gagne à être une étape indépendante : téléchargement, transcodage, contrôle et mise en base, chacun réessayable. Ainsi, l'expiration d'une URL amont n'emporte pas les données métier.

6. Paiement, facture et contrat

  • Pour les équipes en paiement entre entreprises, confirmez à l'avance le mode de recharge, le délai de crédit, le type de facture et la périodicité.
  • Vérifiez comment sont facturés les échecs, timeouts et annulations, et si un remboursement ou un retour de crédit est possible.
  • Exigez un détail d'usage par tâche ou par clé, au minimum aligné sur l'ID de tâche, le modèle, la durée et le statut.
  • Lisez les clauses de données : images, prompts et résultats sont-ils conservés ou utilisés pour améliorer le service ?
  • La clé de production ne va ni dans le frontend ni dans un dépôt public ; séparez par environnement et fixez des plafonds de quota.

7. Bascule : bien faire les retries

Un retry de tâche vidéo coûte plus cher qu'un retry texte, car chaque tentative est une génération complète. Recommandations :

  1. Générer un identifiant de requête unique par numéro métier et vérifier l'existence d'une tâche avant soumission.
  2. Ne faire de backoff que sur 429, 5xx et timeout de connexion ; ne pas réessayer une erreur de paramètre ou un refus de modération.
  3. Couper le circuit après un seuil d'échecs consécutifs pour éviter une tempête de retries.
  4. Prévoir une entrée ou un modèle de secours, mais revérifier l'état des tâches après bascule pour éviter une double génération sur deux chaînes.
  5. Rapprocher chaque jour nombre de tâches, succès et lignes facturées ; arrêter le trafic en cas d'anomalie.

8. Liste de validation avant mise en production

  1. La tâche minimale est acceptée et l'ID de tâche revient de façon stable.
  2. Les six états de tâche sont correctement identifiés et enregistrés.
  3. Timeout de polling, nombre maximal de retries et seuil de coupure sont configurés.
  4. Le résultat est archivé dans les 24 heures, avec une tâche de compensation en cas d'échec de téléchargement.
  5. Les règles de facturation des échecs, annulations et timeouts sont confirmées.
  6. Le comportement en concurrence est testé et les 429 déclenchent un backoff.
  7. Facture et détail des tâches se rapprochent ligne par ligne.
  8. Taux de succès, P95 et coût unitaire sont suivis pendant 7 jours avant toute montée en charge.

Questions fréquentes

Peut-on appeler l'API Seedance directement depuis la Chine ?

Cela dépend du compte, de la région, du réseau et des conditions de conformité. La connexion directe officielle est une voie possible, mais la production doit prévoir timeouts, retries et point d'entrée de secours ; la documentation officielle et la réglementation locale font foi.

Connexion directe ou passerelle : laquelle est la plus stable ?

Il n'y a pas de réponse universelle. La connexion directe supprime un saut, mais toute la gestion des incidents reste interne ; la passerelle unifie l'entrée et la facturation, au prix d'une dépendance supplémentaire. Testez le taux de succès et le P95 sur le même lot de tâches, puis choisissez selon vos capacités d'exploitation.

Combien de temps prend la génération d'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. La production doit fixer un timeout global et exposer l'état de la tâche au métier.

Combien de temps les résultats sont-ils conservés ?

Selon la documentation Volcengine Ark, l'interrogation couvre généralement les 7 derniers jours et l'URL vidéo est nettoyée après 24 heures environ. Archivez immédiatement dans votre stockage objet, sans dépendre d'un lien temporaire.

Les tâches échouées ou annulées sont-elles facturées ?

Les règles varient selon la plateforme et la cause de l'échec. Avant l'intégration, confirmez la facturation des refus de modération, échecs système, timeouts et annulations volontaires, et fiez-vous au détail de facture.

Prochaines étapes

Créez d'abord une clé de test sur ZSQH AI Gateway, exécutez une tâche Seedance en configuration minimale, vérifiez le cycle des états, l'archivage du résultat et la base de facturation, puis décidez de la voie de production. Modèles et prix sont ceux de la page tarifs des modèles.

Lectures associées :