Relais et proxy de l'API Seedance : fiabilité, facturation, migration (2026)

Pour intégrer Seedance à une activité, beaucoup d'équipes choisissent d'abord un relais ou un proxy : changer l'URL de base et la clé semble plus simple que la connexion directe. Mais la génération vidéo est une tâche asynchrone, et la chaîne du relais ajoute au textuel la persistance des tâches, la correspondance d'états, le transfert des résultats et les callbacks. Si un maillon est faible, le symptôme est « la tâche a été soumise, mais la vidéo est introuvable ».

Cet article part de la chaîne réelle d'un service relais pour traiter la fiabilité des tâches, la conservation des résultats, la transparence de facturation, les risques liés aux clés et la recette d'une migration depuis la connexion directe.

Remarque : Seedance est le nom d'un modèle de génération vidéo de Volcengine, filiale de ByteDance ; les marques associées appartiennent à leurs détenteurs. Cet article est purement technique et n'implique aucune affiliation ni coopération avec ByteDance ; interfaces, modèles et prix suivent la documentation officielle et la page Tarifs des modèles du site.

1. Distinguer quatre types de « relais »

Type	Rôle	Risque principal	Cas d'usage
Proxy inverse	Transférer la requête vers l'interface officielle	Point unique, bande de sortie, configuration d'authentification	Équipe avec capacité d'exploitation
Passerelle agrégatrice	Entrée unifiée, plusieurs modèles agrégés	Correspondance d'états, écarts de paramètres	Activité multimodèle
Distribution ou recharge déléguée	Revendre du quota amont ou payer à votre place	Stabilité amont, conditions de service	Essai à faible volume, besoin ponctuel
Passerelle auto-hébergée	Déployer et maintenir sa propre couche de transfert	Toute la responsabilité vous incombe	Équipe technique voulant maîtriser les données

Ce que vous achetez — « service technique » ou « quota de modèle » — détermine qui répond en cas d'incident. Posez les questions sur le contrat, la facture et les conditions de traitement des données en fonction de cette distinction.

2. Ce que la chaîne de relais ajoute aux tâches asynchrones

Votre service
  → entrée du relais (authentification, limitation, facturation)
  → création de la tâche en amont, obtention du task_id
  → le relais conserve la correspondance task_id / numéro métier
  → le relais interroge l'amont ou reçoit les callbacks
  → correspondance d'états exposée via polling ou webhook
  → vous téléchargez le résultat et le transférez

Chaque saut supplémentaire est une occasion de perdre l'état :

Le relais redémarre ou change d'instance : la correspondance en mémoire est perdue.
L'amont expire mais la tâche est créée ; le relais renvoie un échec, l'appelant réessaie et génère deux vidéos.
L'état amont est expired, mais le relais ne mappe que succès et échec : le métier attend indéfiniment.
Le relais met en cache l'URL de résultat sous sa propre adresse, puis le cache expire sans retour à la source.
La reprise de webhook n'a pas de clé d'idempotence : le métier insère deux fois.

Pour évaluer un relais, ne demandez pas seulement « Seedance est-il pris en charge ? », mais comment l'ID de tâche est persisté, comment les états sont mappés et comment les échecs sont compensés.

3. États de tâche et conservation des résultats

Selon la documentation de Volcano Ark, les états Seedance comprennent généralement queued, running, succeeded, failed, cancelled et expired ; l'interrogation couvre environ les 7 derniers jours, et l'URL vidéo d'un succès est généralement nettoyée après 24 heures.

Un service relais doit ajouter une couche au-dessus de ces deux limites :

Conserve-t-il les enregistrements de tâches ? Combien de temps ? Sont-ils consultables au-delà de 7 jours ?
Télécharge-t-il la vidéo à votre place ? Si oui, combien de jours, avec un coût supplémentaire ?
Renvoie-t-il l'URL temporaire amont ou sa propre adresse durable ?
Comment sont mappés annulation, timeout et refus de modération ?

Si le relais ne fait que transmettre, l'appelant garde la responsabilité du transfert sous 24 heures ; s'il héberge, vérifiez l'emplacement de stockage, les droits d'accès et la suppression. Les deux modèles sont acceptables ; le flou ne l'est pas.

4. Comment vérifier la transparence de la facturation

La facturation vidéo prête plus facilement à discussion que le texte, car échecs, reprises et annulations surviennent pendant la phase asynchrone. Avant de signer, confirmez :

L'unité de facturation : durée, résolution, tâche ou conversion en tokens.
La facturation des échecs, timeouts, annulations et refus de modération.
La double facturation des soumissions et reprises, et l'existence d'une déduplication idempotente.
Le minimum de consommation, le seuil de prépaiement, les règles de remboursement et le type de facture.
Le détail d'usage : ID de tâche, modèle, durée, résolution, état et montant débité.

Ne regardez pas que la remise affichée. Faites tourner 20 à 50 tâches sur une semaine et alignez une par une tâches réussies, tâches échouées et facture : c'est plus fiable que n'importe quelle déclaration orale. Les prix exacts figurent sur la page Tarifs des modèles.

5. Clés et risques amont

Un relais implique qu'un tiers voit le contenu des requêtes. Vérifiez au minimum :

Prompts, image de première frame et vidéos générées sont-ils stockés, et combien de temps ?
Les données servent-elles à l'entraînement ou à l'amélioration du service ?
La clé peut-elle être limitée par quota, IP et date d'expiration ?
En cas de fuite ou d'abus, comment êtes-vous notifié et le service bloqué ?
L'amont est-il un canal unique ou multiple, et comment migrer si un modèle est retiré ?
Les conditions permettent-elles la revente ou le relais, et où se situe la responsabilité en cas d'incident ?

Ne placez jamais une clé de production dans le frontend ou un dépôt public. Pour les médias très sensibles, privilégiez un fournisseur sans stockage sur disque ou acceptant un accord de traitement des données ; en cas de doute, n'envoyez pas de média client non expurgé.

6. Étapes d'une migration du direct vers un relais

Inventorier les appels existants : ID de modèle, paramètres, concurrence, durée moyenne et types d'échec.
Confirmer chemins, authentification et différences de champs du relais, et établir la table de correspondance.
Valider en environnement de test les quatre parcours : création, interrogation, annulation et téléchargement.
Exécuter en parallèle sur le même lot, une copie en direct et une via le relais, en comparant sans basculer.
Comparer taux de réussite, durée P95, taux de résultats téléchargeables et coût unitaire.
Basculer progressivement 5 % à 20 % du trafic, avec interrupteur de retour au direct.
Observer 3 à 7 jours et vérifier que facture et détail des tâches concordent.
Après passage complet, conserver un temps un canal de secours double, puis simplifier une fois la stabilité confirmée.

Pendant la migration, ne supprimez pas la clé directe et n'inscrivez pas les deux jeux de tâches sous le même numéro métier : le rapprochement deviendrait impossible.

7. Comment vérifier un service relais

# 1. Soumettre une tâche minimale, noter task_id et heure de soumission
curl -X POST "$RELAY_BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ID de modèle indiqué dans la documentation du relais","content":[{"type":"text","text":"Un chat bâille près de la fenêtre"}]}'

# 2. Interroger toutes les 10 secondes, noter tout le cycle d'états
curl "$RELAY_BASE_URL/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $RELAY_API_KEY"

Provoquez volontairement des anomalies : annuler juste après soumission, envoyer un ID de modèle erroné, soumettre en concurrence, couper le téléchargement en cours. Observez la cohérence des états, messages d'erreur et factures. Revenez sur l'URL de résultat 24 heures plus tard pour vérifier qu'elle est encore téléchargeable, puis reconsultez la tâche après 7 jours pour voir si l'enregistrement existe toujours.

8. Supervision et retour arrière après migration

Compter les tâches par état, en suivant surtout la part de failed, cancelled et expired.
Enregistrer la durée totale entre soumission et succès, ainsi que le temps de file et de génération.
Surveiller le taux de téléchargement des résultats et prévoir une file de compensation pour les échecs.
Suivre 401, 404, 429 et 5xx pour distinguer clé, modèle et limitation.
Calculer « le coût par vidéo réussie », pas seulement le prix unitaire de la requête.
Fixer un seuil de retour arrière : si le taux de réussite reste nettement sous la référence pendant deux heures, repasser au direct.

Questions fréquentes

Le relais offre-t-il les mêmes capacités de modèle que le direct ?

Cela dépend de la fidélité du transfert vers le même modèle et les mêmes paramètres en amont. ID de modèle, durée, résolution et audio peuvent différer ; comparez avec le même prompt avant l'intégration et vérifiez les paramètres pris en charge.

Le relais conserve-t-il mes vidéos ?

Cela varie. Demandez s'il stocke sur disque, combien de temps, où, qui peut accéder, et comment supprimer. Pour des médias clients, privilégiez un fournisseur aux conditions claires.

Que faire si une tâche se perd côté relais ?

Cherchez d'abord par numéro métier dans vos enregistrements locaux, puis dans les journaux du relais et les tâches amont. Si rien ne peut être récupéré, il faut resoumettre ; avant migration, vérifiez donc que le relais persiste la correspondance et permet la recherche par numéro métier.

Pourquoi la facture ne correspond-elle pas au nombre de tâches ?

Causes fréquentes : soumissions en double, reprises d'échec, règles d'annulation différentes, minimum de consommation ou succès depuis le cache. Demandez le détail par ID de tâche et vérifiez ligne par ligne, pas seulement le total.

La migration demande-t-elle de modifier le code ?

Si le relais est compatible OpenAI ou avec l'interface officielle de tâches, seuls l'URL de base, la clé et quelques champs changent souvent ; si le mapping d'états ou le format de callback diffère, il faut adapter polling et persistance. Une exécution en parallèle révèle l'essentiel des écarts.

Pour aller plus loin

Créez d'abord une clé de test sur ZSQH AI Gateway, validez les quatre chaînes — création, polling, téléchargement et facture — avec une tâche minimale, puis migrez progressivement. Modèles et prix figurent sur la page Tarifs des modèles.