Checklist de production Seedance API pour les équipes texte-vers-vidéo

Un prototype Seedance API peut sembler terminé après une seule vidéo réussie. Une intégration de production n’est terminée que lorsque votre système peut survivre à des tâches lentes, des événements en double, des chemins de modèle changeants, des échecs partiels et des coûts incertains.

Cette différence compte, car la génération vidéo n’est pas une fonctionnalité classique de type requête-réponse. L’application soumet un travail, attend, reçoit des changements d’état, stocke une sortie volumineuse et décide si un échec doit être retenté. L’appel au modèle n’est qu’une étape d’un flux de travail plus long.

Cette checklist transforme ce flux de travail en contrat de production que vos équipes produit, plateforme et finance peuvent examiner ensemble.

Note sur le chemin actuel : Le catalogue public de modèles de Flatkey répertoriait seedance-2.5 pour le texte-vers-vidéo et l’image-vers-vidéo, ainsi que seedance-2.0-i2v pour l’image-vers-vidéo, lorsque ce guide a été vérifié le lundi 27 juillet 2026. Considérez ces noms comme l’état du catalogue, et non comme des constantes permanentes. Vérifiez le répertoire des modèles Flatkey actuel avant la mise en production ou la modification d’une liste d’autorisation.

La réponse courte

Ne connectez pas directement votre requête orientée utilisateur à un appel au fournisseur vidéo. Placez entre les deux une couche de tâches durable.

Votre chemin de production minimal devrait être :

1. accepter et valider la requête de génération de l’utilisateur
2. attribuer votre propre clé d’idempotence et votre propre ID de tâche
3. stocker la requête avant d’appeler le chemin du modèle
4. soumettre la tâche via un adaptateur côté serveur
5. traiter les mises à jour de webhook et de polling de manière idempotente
6. copier les médias terminés vers un stockage que vous contrôlez
7. enregistrer la latence, la raison de l’échec, le chemin du modèle et le coût estimé
8. exposer un statut produit stable, indépendant du libellé du fournisseur

Si l’une de ces étapes manque, l’intégration peut encore très bien fonctionner en démonstration, mais elle est plus difficile à exploiter en toute sécurité.

Pourquoi le travail de production Seedance API est différent

La génération de texte renvoie souvent une réponse utile en un seul échange HTTP. La génération vidéo se comporte généralement comme un lot distribué. Une action utilisateur peut durer plus longtemps qu’une requête d’application, un déploiement, une session de navigateur, voire même l’URL temporaire qui finit par héberger le résultat.

Les conséquences pratiques sont faciles à sous-estimer :

L’objectif n’est pas de masquer le fournisseur. Il s’agit d’éviter que le comportement spécifique au fournisseur devienne le contrat permanent de votre produit.

1. Geler le contrat produit avant la charge utile

Commencez par l’expérience que vous promettez aux utilisateurs, et non par les champs du fournisseur disponibles aujourd’hui.

Définissez :

• les types d’entrée acceptés : texte uniquement, image plus texte, ou les deux
• les formats d’image pris en charge et les plages de durée
• la taille maximale de téléversement et les formats de média acceptés
• les contrôles de modération et de droits avant l’envoi
• les mises à jour d’état attendues et le comportement d’annulation
• la période de conservation de la sortie
• si une tâche en échec consomme un crédit utilisateur
• ce que signifie « réessayer » dans le produit

Traduisez ensuite ce contrat en route Seedance actuelle dans un adaptateur.

Cette séparation vous protège de deux modes de défaillance courants. Premièrement, une mise à jour de route peut ajouter ou renommer des paramètres sans obliger à réécrire le frontend. Deuxièmement, votre application peut rejeter les combinaisons non prises en charge avant de dépenser de l’argent pour une tâche vouée à l’échec.

2. Utilisez votre propre identifiant de tâche et votre clé d’idempotence

Chaque requête a besoin de deux identifiants :

• identifiant de tâche produit : l’identifiant stable affiché dans l’ensemble de votre système
• clé d’idempotence : l’identifiant utilisé pour empêcher une soumission en double accidentelle

N’utilisez pas un identifiant de tâche du fournisseur comme clé primaire. Il n’existe qu’après la soumission et peut changer si vous soumettez volontairement à nouveau via une autre route.

Un enregistrement de requête simple peut ressembler à ceci :

type VideoJob = {
  id: string;
  idempotencyKey: string;
  accountId: string;
  requestedModel: string;
  resolvedModel: string | null;
  providerTaskId: string | null;
  status: "accepted" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
  attempt: number;
  outputUrl: string | null;
  failureCode: string | null;
  createdAt: string;
  updatedAt: string;
};

Créez cet enregistrement avant l’appel API sortant. Si l’application plante après la soumission mais avant l’enregistrement de la réponse, la clé d’idempotence vous donne un moyen de rapprocher les éléments au lieu de facturer aveuglément une autre génération.

3. Placez Seedance derrière un seul adaptateur côté serveur

Conservez la construction des requêtes spécifique au fournisseur dans un seul module. Le reste de votre produit doit envoyer une commande normalisée telle que :

type GenerateVideoCommand = {
  prompt: string;
  sourceImageUrl?: string;
  aspectRatio: "16:9" | "9:16" | "1:1";
  durationSeconds: number;
  qualityProfile: "draft" | "standard" | "high";
};

L’adaptateur est responsable de :

• faire correspondre qualityProfile à un modèle et à des paramètres actuellement disponibles
• joindre l’authentification côté serveur
• traduire vos choix de format et de durée vers le schéma API actif
• soumettre la tâche
• normaliser les erreurs du fournisseur
• stocker l’ID de tâche du fournisseur
• fournir suffisamment de métadonnées pour l’analyse des coûts et de la fiabilité

Flatkey fournit aux équipes une clé API, un endpoint routeur stable, un solde partagé et une visibilité centralisée de l’utilisation sur l’ensemble des familles de modèles. Pour les équipes qui utilisent déjà cette couche d’accès, conservez la logique asynchrone spécifique à Seedance dans l’adaptateur plutôt que de disperser des hypothèses de routage dans toute la base de code. Le guide précédent sur une URL de base stable compatible OpenAI pour les équipes Seedance API explique cette frontière plus en détail.

4. Modélisez le flux de travail comme une machine à états

Ne laissez pas des chaînes d’état arbitraires pénétrer la logique produit. Normalisez-les.

stateDiagram-v2
    [*] --> accepted
    accepted --> queued: submit accepted
    accepted --> failed: validation or submit error
    queued --> running: provider starts work
    queued --> failed: terminal provider error
    running --> succeeded: output verified
    running --> failed: terminal provider error
    accepted --> cancelled: cancelled before submit
    queued --> cancelled: cancellation confirmed
    succeeded --> [*]
    failed --> [*]
    cancelled --> [*]

N’autorisez que les transitions vers l’avant, sauf si vous exécutez un processus de récupération explicite. Un événement running tardif ne doit pas écraser une tâche déjà marquée succeeded. Un webhook succeeded dupliqué ne doit pas déclencher deux copies de stockage ni deux notifications client.

Stockez l’événement brut du fournisseur séparément pour le débogage, mais prenez les décisions produit à partir de l’état normalisé.

5. Utilisez ensemble les webhooks et le polling

Les webhooks sont efficaces, mais ils ne garantissent pas que votre application traitera chaque événement une seule fois et dans l’ordre. Le polling est plus lent, mais il est utile pour la réconciliation.

Utilisez les deux :

• chemin webhook : mises à jour d’état à faible latence
• chemin polling : récupération planifiée pour les tâches qui n’ont pas changé récemment

Votre gestionnaire de webhook devrait :

1. authentifier l’appel retour lorsque l’API active prend en charge la vérification
2. analyser l’événement sans effectuer de travail lourd en ligne
3. écrire une empreinte d’événement dans une table de déduplication
4. mettre le traitement en file d’attente
5. renvoyer rapidement une réponse de succès

Votre worker de réconciliation devrait interroger uniquement les tâches qui sont encore non terminales après un délai raisonnable. Ajoutez du jitter afin qu’un déploiement ne provoque pas des milliers de vérifications d’état au même instant.

Les champs spécifiques au fournisseur pour les webhooks et les requêtes peuvent changer. Vérifiez-les par rapport à la référence API officielle actuelle pendant l’implémentation, plutôt que de copier un ancien payload à partir d’un article de blog.

6. Prendre les décisions de nouvelle tentative par classe d’échec

« Relancer les tâches échouées » n’est pas une politique. C’est un risque de coût.

Normalisez les erreurs en classes :

La dernière distinction est particulièrement importante. Si la vidéo a été générée avec succès mais que votre copie de stockage a échoué, régénérer la vidéo crée un coût inutile et peut produire un résultat différent.

Définissez un budget de nouvelles tentatives par tâche. Une politique raisonnable pourrait autoriser davantage de vérifications de statut et de tentatives de copie de stockage que de soumissions de génération.

7. Copier les sorties vers un stockage que vous contrôlez

Traitez toute URL de résultat hébergée par le fournisseur comme un emplacement de transfert, et non comme votre actif produit permanent.

Après la réussite d’une tâche :

1. vérifiez que la réponse contient le type de média attendu
2. téléchargez avec une limite de taille et de temps
3. validez que le fichier n’est pas vide ou manifestement tronqué
4. calculez une somme de contrôle
5. copiez-le dans votre stockage d’objets
6. enregistrez la durée, les dimensions, le codec et la taille
7. ne basculez la tâche produit vers succeeded qu’une fois la copie durable disponible

Si votre produit permet aux utilisateurs de télécharger l’actif original du fournisseur avant la fin de la copie, représentez cela comme un état transitoire séparé. Ne promettez pas la permanence en silence.

8. Ajouter des contrôles de coût avant d’ouvrir la fonctionnalité

Les tâches vidéo sont suffisamment coûteuses pour que des limites produit existent avant le lancement public.

Au minimum, définissez :

• un plafond de dépenses par clé ou par équipe
• une liste d’autorisation de modèles pour la clé d’application
• un maximum de tâches simultanées par compte
• une durée maximale et un profil de qualité par offre
• une limite quotidienne de soumission pour les comptes nouveaux ou non dignes de confiance
• un coupe-circuit lorsque le taux d’échec ou le coût par succès augmente

La documentation publique de Flatkey décrit des plafonds par clé, des listes d’autorisation de modèles facultatives et la visibilité de l’utilisation via Usage & Logs ou l’API ledger. Utilisez ces contrôles comme garde-fou de la couche d’accès, puis ajoutez des quotas au niveau du produit en fonction de vos propres offres et du risque d’abus.

Avant d’activer une nouvelle route, comparez le catalogue actuel et les tarifs Flatkey. N’intégrez pas dans la logique applicative un prix numérique issu de cet article ; les tarifs et la disponibilité des routes sont des données actualisables.

9. Mesurez le travail complet, pas seulement la latence de l’API

Dans un flux de travail Seedance API asynchrone, une soumission réussie peut tout de même offrir une mauvaise expérience client.

Suivez au minimum :

• taux d’acceptation des soumissions
• temps d’attente en file
• temps de génération
• temps total jusqu’à une sortie durable
• taux de réussite par modèle résolu
• taux d’échec par classe d’échec normalisée
• latence de livraison des webhooks
• taux de récupération via polling
• taux d’échec de la copie vers le stockage
• coût par tâche soumise
• coût par sortie durable réussie
• nombre de préventions de soumissions en double

Utilisez des percentiles, pas seulement des moyennes. Un temps de génération médian peut sembler sain tandis que les dix pour cent de tâches les plus lentes génèrent la majorité des tickets de support.

Enregistrez aussi séparément requestedModel et resolvedModel. Cela rend les changements de route visibles et vous donne des preuves pour les décisions de rollback.

10. Déployez les changements de modèle comme des migrations

Un changement de catalogue n’est pas qu’un simple remplacement de chaîne. Traitez-le comme une mise à niveau de dépendance.

Avant de transférer le trafic de production vers une nouvelle route Seedance :

1. confirmez la route actuelle dans le répertoire des modèles en production
2. comparez les entrées prises en charge et les contraintes de sortie
3. exécutez un jeu d’évaluation fixe sur vos types de prompts courants
4. comparez le taux de réussite, la latence, l’acceptation des sorties et le coût
5. testez le webhook, le polling et la normalisation des erreurs
6. dirigez un petit pourcentage du trafic en canary
7. conservez une route de rollback jusqu’à ce que le canary soit stable
8. mettez à jour la allowlist des modèles et le runbook opérationnel

Si votre application expose un réglage « quality », associez-le à un profil de capacités plutôt qu’à un identifiant de modèle permanent. Cela vous permet de changer la route sous-jacente sans casser l’API du produit.

Checklist de préparation à la production

Utilisez cette liste comme point de validation avant lancement.

Requête et accès

• [ ] les clés API restent côté serveur
• [ ] la clé d’application a un plafond de dépenses et une allowlist de modèles
• [ ] chaque requête dispose d’un identifiant de tâche interne et d’une clé d’idempotence
• [ ] les entrées sont validées avant soumission
• [ ] la route actuelle du modèle Seedance est vérifiée dans le catalogue en direct

Exécution asynchrone

• [ ] la logique spécifique au fournisseur se trouve dans un seul adaptateur
• [ ] les statuts produit utilisent une machine à états normalisée
• [ ] les événements webhook sont authentifiés lorsque c’est pris en charge et dédupliqués
• [ ] le polling réconcilie les tâches non terminales obsolètes
• [ ] les événements tardifs ou dupliqués ne peuvent pas inverser des états terminaux

Fiabilité et coût

• [ ] le comportement des retries varie selon la classe d’échec
• [ ] les retries de génération disposent d’un budget strict
• [ ] les retries de copie de sortie ne régénèrent pas les vidéos réussies
• [ ] les limites de concurrence et de tâches quotidiennes sont appliquées
• [ ] un circuit breaker peut mettre en pause une route dégradée

Sortie et observabilité

• [ ] les médias réussis sont copiés vers un stockage contrôlé
• [ ] les métadonnées de sortie et la somme de contrôle sont stockées
• [ ] les ID de modèle demandés et résolus sont consignés
• [ ] le coût par sortie durable réussie est mesuré
• [ ] les opérateurs disposent d’un runbook pour les jobs bloqués, échoués et dupliqués

Où Flatkey s’intègre

Flatkey ne supprime pas le besoin d’une couche asynchrone de jobs vidéo. Il réduit le travail d’accès et de gouvernance autour de cette couche : un seul compte, un seul solde, des contrôles de clé API, une surface de routeur stable, un catalogue de modèles en direct et des enregistrements d’utilisation centralisés.

Pour une première intégration, commencez par le guide de démarrage rapide de l’API Seedance pour les équipes produit texte-vers-vidéo. Lorsque la fonctionnalité se rapproche de la production, appliquez cette checklist aux couches de file d’attente, d’état, de relance, de stockage et d’observabilité autour de l’appel au modèle.

Si votre équipe décide quelle route actuelle et quels contrôles d’utilisation conviennent au déploiement, consultez les modèles en direct et la tarification avant d’approuver la configuration de production.

Questions fréquentes

L’API Seedance est-elle synchrone ou asynchrone ?

Considérez la génération vidéo comme un job asynchrone. Votre produit doit soumettre le travail, renvoyer son propre ID de job et traiter les mises à jour de statut via des webhooks et/ou du polling selon la référence API actuelle.

Dois-je utiliser l’ID de tâche du fournisseur comme clé primaire de ma base de données ?

Non. Créez votre propre ID de job stable avant la soumission. Stockez l’ID de tâche du fournisseur comme référence externe afin de pouvoir faire la réconciliation, renvoyer la soumission ou changer de route sans modifier l’identifiant produit.

Ai-je besoin à la fois de webhooks et de polling ?

Pour un système de production résilient, oui. Les webhooks fournissent des mises à jour rapides ; le polling récupère les jobs dont les événements ont été retardés, manqués ou non traités.

Quand est-il sûr de réessayer un job Seedance échoué ?

Ne réessayez qu’après avoir classé l’échec. Les échecs de capacité et de réseau peuvent être rejoués. Les échecs de validation, d’authentification, de sécurité ou autres échecs terminaux nécessitent généralement une modification de configuration ou de l’utilisateur. Si l’envoi a expiré, faites la réconciliation par clé d’idempotence avant d’envoyer un autre job payant.

Dois-je stocker moi-même la vidéo générée ?

Oui. Copiez la sortie terminée vers un stockage que vous contrôlez, validez le fichier et enregistrez ses métadonnées. Les URL de résultat hébergées par le fournisseur ne doivent pas être considérées comme un stockage produit permanent, sauf si les conditions actuelles garantissent explicitement ce comportement.

Comment dois-je gérer une nouvelle version du modèle Seedance ?

Traitez-la comme une migration : vérifiez le catalogue actuel, exécutez un ensemble d’évaluation fixe, comparez la qualité, la latence, les échecs et le coût, faites du trafic canari et conservez une voie de retour arrière jusqu’à ce que le changement soit stable.

Quel modèle Seedance dois-je coder en dur ?

Évitez de coder en dur de façon permanente un modèle à partir d’un article statique. Résolvez un profil de capacité produit vers un modèle répertorié dans le répertoire des modèles Flatkey actuel, et conservez la route choisie dans la configuration afin que les opérateurs puissent la modifier en toute sécurité.