Les erreurs de Seedance se lisent sur deux niveaux : d'un côté les échecs de requête HTTP, comme 401, 403, 400 et 429 ; de l'autre les requêtes acceptées dont la tâche finit en failed ou expired. Considérer qu'un 200 renvoyé par l'interface de soumission signifie un succès est l'erreur la plus fréquente lors de l'intégration d'une API vidéo. L'ordre de diagnostic correct est : lire le code HTTP, puis l'état de la tâche et le champ error, et seulement ensuite modifier le prompt ou changer de modèle.

Cet article détaille chaque type d'erreur, avec les causes, l'ordre de traitement et un exemple de code réutilisable. Les chemins d'interface, les noms d'état et les règles de quota peuvent évoluer ; la documentation du site et la documentation officielle font foi.

Remarque : Seedance, Doubao et Volcengine sont des marques de ByteDance et de ses sociétés affiliées. Cet article est purement technique et n'implique aucune affiliation ni approbation. Les chemins et champs des exemples sont illustratifs ; vérifiez la documentation avant d'appeler.

1. Distinguer échec de requête et échec de tâche

Symptôme Niveau Cause courante Traitement
401 HTTP Clé absente, mal formée, expirée Corriger l'authentification
403 HTTP Droits insuffisants, modèle non activé, restriction de région Vérifier droits et activation
400 HTTP Paramètre hors limites, nom de modèle erroné, média inaccessible Corriger selon la documentation
429 HTTP Concurrence, débit ou quota limité Backoff, réduire la concurrence
5xx HTTP Surcharge amont ou panne temporaire Backoff, changer de canal
failed Tâche Refus de modération, problème de média, anomalie de génération Lire error, corriger le média
expired Tâche Délai dépassé sans achèvement ni récupération Recréer la tâche, vérifier l'échéance
Échec de téléchargement Résultat URL expirée, authentification, réseau Récupérer à nouveau ou transférer

Le journal doit au minimum contenir heure, code HTTP, code d'erreur, nom de modèle, task_id, numéro métier et durée. Ne stockez pas la clé complète et n'imprimez pas brute l'URL signée du résultat.

2. 401 et 403 : vérifier d'abord l'en-tête et la clé

Un 401 signifie que l'identité n'a pas été validée ; cela n'a généralement rien à voir avec la capacité du modèle ou le solde. Vérifiez dans l'ordre :

  • Authorization est-il bien Bearer <clé> ? Volcengine Ark utilise la clé API comme Bearer Token.
  • La clé contient-elle un espace, un saut de ligne ou des guillemets en trop ? La variable d'environnement est-elle réellement chargée ?
  • L'URL de base et la clé appartiennent-elles à la même plateforme et à la même région ?
  • La clé a-t-elle été supprimée, renouvelée, désactivée, ou les droits du projet sont-ils insuffisants ?
  • Le proxy inverse écrase-t-il ou supprime-t-il l'en-tête Authorization ?

Un 403 relève plutôt des droits : modèle non activé, compte sans autorisation sur ce modèle, restriction de région ou de conformité. Pour un 401, une nouvelle clé sur une requête minimale localise vite le problème ; pour un 403, vérifiez l'état d'activation et les droits du compte dans la console, car modifier le code ne sert généralement à rien.

3. 429 : débit, concurrence et quota

Un 429 indique que la requête dépasse une limite de débit, de concurrence ou de quota. Situations fréquentes :

  • Plusieurs services partagent une clé et se disputent le quota.
  • Des tâches batch démarrent toutes à l'heure pile et forment un pic de trafic.
  • Les reprises n'ont pas de backoff et s'amplifient à chaque échec, créant une tempête.
  • Les tâches longues saturent la concurrence, et les tâches courtes ne passent plus.

Le principe : backoff exponentiel avec gigue aléatoire, réduction de la concurrence, clés séparées par projet et soumissions décalées. Ne bouclez pas sur des reprises sans backoff ; continuer à soumettre à haute fréquence pendant un 429 transforme la limitation en panne durable. Si l'activité exige réellement une forte concurrence, confirmez à l'avance le plafond de quota et préparez un canal de secours.

4. 400 : majoritairement des erreurs de paramètres

Un 400 se localise généralement directement dans le message d'erreur. Vérifiez surtout :

  • Nom et version du modèle : copiez-les depuis la documentation, ne reconstruisez pas le suffixe de mémoire.
  • Durée : les plages varient selon le modèle, par exemple 4 à 30 secondes pour 2.5, 4 à 15 secondes pour 2.0 et 2 à 12 secondes pour 1.0.
  • Résolution et ratio : confirmez si le modèle prend en charge la 4K, le 21:9 ou le mode adaptatif.
  • Nombre de médias de référence : 2.5 accepte jusqu'à 30 images, 10 vidéos et 10 audios ; les limites de 2.0 sont plus basses.
  • URL d'image ou de vidéo : elle doit être accessible par la plateforme, pas une adresse interne ni un lien nécessitant une connexion.
  • Tâches d'édition ou de continuation : certains modes n'autorisent que la durée automatique, sans saisie manuelle des secondes.
  • Entrée audio : certaines versions ne prennent pas en charge l'audio seul.

La méthode la plus rapide consiste à reproduire la requête minimale de l'exemple de documentation, puis à rajouter ses paramètres un par un. En testant après chaque ajout, on identifie le champ exact.

5. Tâches failed et expired

Une soumission réussie signifie seulement que la tâche est en file. Les états courants d'une requête de résultat sont queued, running, succeeded, failed et expired. Pour failed, lisez le champ error : refus de modération, média d'entrée non conforme, image de référence illisible ou anomalie de génération appellent des traitements totalement différents.

expired survient souvent lorsqu'une tâche dépasse le délai d'exécution sans être terminée ou lorsque le résultat n'est pas récupéré. La documentation permet de configurer execution_expires_after, avec une valeur par défaut de 48 heures ; l'ID de tâche est conservé sept jours. Au-delà, continuer à interroger ne rétablit rien : il faut recréer la tâche. En cas de callback, attention : un callback non confirmé sous cinq secondes est réessayé trois fois, et l'interface de callback doit être idempotente.

Pour un refus de modération, ne cherchez pas à contourner en changeant quelques mots. Vérifiez d'abord les autorisations sur les médias, les droits à l'image des personnes, les éléments de marque et la politique de contenu, puis décidez si une nouvelle soumission est appropriée.

6. Timeouts et interrogation

Un timeout se lit à trois niveaux : timeout de connexion du client, timeout d'une requête de résultat, et échéance totale de la tâche. L'interface de soumission renvoie généralement vite un task_id ; le temps réel est passé dans la file et le rendu. Un timeout client trop court fait passer une soumission normale pour un échec ; trop long, il immobilise le pool de threads.

Pour l'interrogation, commencez à 5 secondes, puis appliquez un backoff progressif jusqu'à 15 à 30 secondes, avec une échéance totale. Quand les callbacks sont disponibles, privilégiez-les et gardez l'interrogation comme filet. Après un timeout, ne soumettez pas immédiatement une nouvelle tâche : vérifiez d'abord avec le numéro métier ou une clé d'idempotence si une tâche tourne déjà.

7. Échec du téléchargement du résultat

Une tâche réussie ne signifie pas que le fichier est en main. video_url est souvent une adresse temporaire signée, avec une durée de validité ; la stocker directement en base puis la télécharger quelques heures plus tard produit fréquemment un 403 ou un 404. Traitement :

  • Téléchargez immédiatement en streaming vers votre propre stockage objet après le succès.
  • Réessayez séparément le téléchargement, sans recréer la tâche de génération.
  • Vérifiez le Content-Type, la taille du fichier et sa lisibilité.
  • N'imprimez pas l'URL signée complète dans les journaux.

8. Exemple : traitement d'erreur avec backoff et idempotence

Le code ci-dessous sépare soumission, interrogation et téléchargement, et ne réessaie que les erreurs transitoires. Les chemins et champs suivent la documentation du site.

import os, time, random, requests

BASE = os.environ["SEEDANCE_BASE_URL"].rstrip("/")
HEADERS = {
    "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
    "Content-Type": "application/json",
}

def submit(payload, max_retries=5):
    # avant l'appel, consulter la table des tâches par numéro métier ; réutiliser un task_id existant
    for attempt in range(max_retries):
        try:
            r = requests.post(
                f"{BASE}/contents/generations/tasks",
                headers=HEADERS, json=payload, timeout=(5, 30),
            )
        except requests.Timeout:
            time.sleep(min(2 ** attempt, 20) + random.random())
            continue
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(min(2 ** attempt, 20) + random.random())
            continue
        if r.status_code >= 400:
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")
        return r.json()["id"]
    raise RuntimeError("submit retries exhausted")

def wait(task_id, deadline_seconds=900):
    deadline = time.time() + deadline_seconds
    delay = 5
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/contents/generations/tasks/{task_id}",
            headers=HEADERS, timeout=(5, 30),
        )
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(delay)
            delay = min(delay * 1.5, 30)
            continue
        r.raise_for_status()
        data = r.json()
        if data["status"] == "succeeded":
            return data["content"]["video_url"]
        if data["status"] in ("failed", "expired"):
            raise RuntimeError(f"{data['status']}: {data.get('error')}")
        time.sleep(delay)
        delay = min(delay * 1.5, 30)
    raise TimeoutError(task_id)

def download(url, path):
    with requests.get(url, stream=True, timeout=(5, 120)) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(1024 * 256):
                f.write(chunk)

Ce code ne réessaie volontairement pas les 400, 401 et 403. Une erreur de paramètre ou d'authentification ne réussira jamais en réessayant : elle ne fait qu'amplifier les journaux et les coûts.

9. Reprises, idempotence et liste pour le support

Les reprises ne conviennent qu'aux erreurs transitoires : 429, 5xx et timeouts de connexion. Les 400, 401, 403 et refus de modération ne doivent pas être réessayés automatiquement. La clé de l'idempotence n'est pas le nombre de tentatives, mais le numéro métier : consultez la table des tâches avant la soumission, enregistrez le task_id après, et réutilisez la tâche existante pour une requête répétée.

Avant de contacter le fournisseur, préparez les informations suivantes :

  1. Heure, code HTTP, code d'erreur et message complet, avec les données sensibles masquées.
  2. Nom du modèle, durée, résolution, ratio et nombre de médias de référence.
  3. task_id, numéro métier, nombre de soumissions et nombre d'interrogations.
  4. Une requête de reproduction minimale, sans données personnelles ni clé.
  5. La distinction entre échec de requête et tâche failed ou expired.
  6. La vérification que les URL de médias sont publiques et que la réponse n'est pas trop lente.
  7. La confirmation des quotas, de la concurrence et des droits du compte, pour écarter 429 et 403.
  8. Le request ID et l'heure de reproduction avant de transmettre le dossier.

Questions fréquentes

L'interface de soumission renvoie 200, pourquoi la tâche échoue-t-elle ?

200 signifie seulement que la tâche a été créée. La génération vidéo est asynchrone : l'état final se lit dans status et error du résultat.

Un 429 signifie-t-il un solde insuffisant ?

Pas nécessairement. Un 429 indique généralement une limite de débit, de concurrence ou de quota ; un problème de solde peut renvoyer une autre erreur. Vérifiez d'abord la concurrence, le partage de clé et la stratégie de reprise.

Peut-on réessayer directement après un failed ?

Lisez d'abord error. Un refus de modération ou un média non conforme échouera généralement à l'identique ; une panne réseau ou amont peut être réessayée avec backoff. Avant de réessayer, faites un contrôle d'idempotence avec le numéro métier.

À quelle fréquence interroger la tâche ?

Commencez à 5 secondes, puis appliquez un backoff jusqu'à 15 à 30 secondes, avec un timeout total. Si les callbacks sont disponibles, privilégiez-les et gardez l'interrogation comme filet.

Que faire si l'URL du résultat ne s'ouvre pas ?

Le plus souvent, la validité ou la signature a expiré. Transférez immédiatement le fichier vers un stockage objet après le succès ; si l'URL est déjà expirée, interrogez à nouveau la tâche ou recréez-la, sans répéter les appels sur l'ancien lien.

Pour aller plus loin

Créez d'abord une clé de test sur ZSQH AI Gateway, entraînez-vous une fois sur 401, 429, erreur de paramètre et échec de tâche, puis confirmez l'effet des alertes et de la stratégie de reprise. La disponibilité des modèles et la facturation font foi sur la page Tarifs des modèles.

Articles liés :