Seedance est un modèle de génération vidéo de ByteDance. Pour appeler son API, le premier obstacle n'est pas la rédaction du prompt, mais l'obtention d'une clé API utilisable et son placement au bon endroit. Beaucoup d'erreurs 401 ne viennent pas de la clé elle-même : elles proviennent de l'en-tête de requête, de l'URL de base ou de l'état d'activation du modèle.

Cet article suit l'ordre « inscription — création — configuration — diagnostic — rotation » et explique également la différence entre une clé officielle et une clé de passerelle.

Note : Seedance, ByteDance, Doubao, Volcengine et Volcengine Ark sont des noms et marques appartenant à leurs titulaires. Cet article est purement technique et n'implique aucun partenariat, aucune représentation ni aucune autorisation ; les interfaces et les prix sont ceux des documents officiels ou du site.

1. Distinguer d'abord le compte, le modèle et la clé

L'appel à Seedance implique trois couches : le compte plateforme, le service de modèle et le justificatif d'accès. Le compte sert à l'identification et à la facturation, le modèle doit être activé séparément sur la plateforme, et la clé API n'est qu'un justificatif d'identité au moment de la requête. Les trois sont indispensables et ne se substituent pas l'un à l'autre.

Une clé n'est pas un mot de passe de compte : elle ne permet pas de se connecter à la console, encore moins de servir de justificatif d'abonnement web. Si elle fuit, un tiers peut consommer le quota de votre compte pour soumettre des tâches. Il faut donc la traiter comme une donnée sensible dès sa création.

L'interface officielle côté données utilise généralement Authorization: Bearer <API_KEY> ; l'interface d'administration (création et gestion des clés, des Endpoints, etc.) demande en général une signature AK/SK. Les deux jeux d'identifiants ont des usages différents : ne mettez pas directement un AK/SK d'administration dans une requête côté données.

2. Voie A : obtenir une clé officielle Volcengine Ark

La voie officielle convient aux équipes qui veulent une connexion directe et gérer elles-mêmes leurs ressources cloud et leur facturation. Les étapes courantes sont les suivantes :

  1. Créer un compte Volcengine et suivre les indications de la console pour la vérification d'identité et les informations d'entité nécessaires.
  2. Ouvrir la console Volcengine Ark et activer le modèle Seedance prévu ; tant qu'il n'est pas activé, les appels renvoient souvent une erreur du type ModelNotOpen.
  3. Ouvrir la page de gestion des clés API et créer une clé, de préférence nommée selon l'usage et l'environnement, par exemple seedance-prod-server.
  4. Copier et enregistrer immédiatement le secret. La plupart des plateformes ne l'affichent en entier qu'à la création ; après fermeture de la page, il n'est plus consultable.
  5. Soumettre une tâche courte avec la configuration minimale pour vérifier l'authentification, l'activation du modèle, le quota et la facturation.
  6. Placer la clé dans une variable d'environnement côté serveur ou dans un service de gestion des secrets, jamais dans le code, la documentation ou un historique de conversation.

Les noms de menus de la console peuvent changer selon les versions ; l'entrée exacte est celle du guide de démarrage du site. Si plusieurs personnes partagent le compte, créez une clé par système pour faciliter l'audit et la révocation.

3. Voie B : obtenir une clé via une passerelle compatible

Si l'équipe utilise déjà une passerelle API unifiée, elle n'a généralement pas besoin de maintenir un compte cloud séparé. Après inscription sur ZSQH AI Gateway, vous pouvez créer une clé dans la console, puis vérifier dans la liste des modèles si le canal vidéo Seedance est activé et quels modèles et paramètres sont pris en charge.

À souligner : une clé de passerelle et une clé officielle ne sont pas interchangeables. L'URL de base, l'en-tête d'authentification, les champs de tâche, le mode de rappel et la base de facturation peuvent différer. Passer de l'officiel à la passerelle, ou l'inverse, impose de remplacer toute la configuration ; ne changer que la clé échoue souvent au moment de soumettre la tâche.

L'inscription se fait sur ZSQH AI Gateway ; les modèles disponibles et la facturation figurent sur la page tarifs des modèles. Les prix évoluent : la page affichée fait foi avant toute commande.

4. Clé officielle ou clé de passerelle : comment choisir

Critère Clé officielle Volcengine Ark Clé de passerelle compatible
Compte et vérification Compte Volcengine avec vérification d'identité Inscription selon les règles de la passerelle
URL de base Adresse officielle côté données Adresse fournie par la passerelle
Portée des droits Limitée par le compte, l'activation et les quotas Limitée par la configuration modèles et crédits de la passerelle
Facturation Facture officielle Facture de la passerelle, prix sur la page tarifs
Cas adapté Connexion directe et gestion autonome du cloud Point d'entrée unique multi-modèles, moins de comptes à maintenir
Points d'attention Les opérations d'administration exigent un AK/SK Vérifier d'abord le canal vidéo et la prise en charge des rappels

Le critère de choix n'est pas le tarif, mais la capacité de l'équipe à assumer la maintenance du compte, la revue de conformité et le diagnostic des incidents. Le prix n'est qu'un élément ; la stabilité et la réversibilité comptent autant.

5. Placer la clé dans une variable d'environnement

Qu'il s'agisse d'une clé officielle ou d'une clé de passerelle, elle ne doit jamais être codée en dur. Voici la forme minimale d'un appel avec des variables d'environnement :

# .env uniquement en local, à ajouter impérativement au .gitignore
export ARK_API_KEY="your-volcengine-ark-key"
export SEEDANCE_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

# Test de fumée : vérifier seulement l'authentification et la création de tâche
curl -sS -X POST "$SEEDANCE_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": "Rue urbaine après la pluie, travelling avant lent, rendu cinématographique"}],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p"
  }'

L'identifiant de modèle et les paramètres de l'exemple ne servent qu'à illustrer la forme de la requête ; copiez les valeurs réelles depuis la console ou la documentation officielle. En Python, lisez avec os.environ ; en Node.js, avec process.env. En CI, utilisez les secrets de la plateforme ; en production, un service de gestion des secrets. Masquez l'en-tête Authorization avant d'écrire dans les logs, pour éviter que la clé ne parte dans la plateforme de journalisation avec les rapports d'erreur.

6. Ordre de diagnostic des erreurs 401

En cas de 401, ne réessayez pas immédiatement ; éliminez les causes dans cet ordre :

  • L'en-tête est-il exactement Authorization: Bearer <key>, avec un espace après Bearer ?
  • La clé contient-elle un saut de ligne, des guillemets ou des espaces avant ou après ? C'est fréquent lors d'un copier-coller depuis la console.
  • L'URL de base correspond-elle à la plateforme de la clé ? Une clé officielle avec l'adresse de la passerelle, ou l'inverse, échoue à l'authentification.
  • La clé a-t-elle été désactivée, supprimée ou expirée ? Après une passation d'équipe, il arrive que l'ancienne clé ne soit plus valide sans que le code ait été mis à jour.
  • Le compte est-il en défaut de paiement, le service est-il activé ? Ces cas renvoient parfois 403 plutôt que 401 ; vérifiez les deux.
  • La région et l'Endpoint sont-ils corrects ? Les adresses de régions différentes ne se mélangent pas ; un appel transfrontalier ajoute aussi des contraintes réseau.

Un 401 signifie seulement que l'identité n'a pas été acceptée ; réessayer à l'aveugle ne résout rien. Affichez d'abord l'en-tête masqué, l'adresse cible et le corps de réponse, puis vérifiez point par point.

7. Liste de sécurisation des clés

  • Une clé par environnement : développement, test et production séparés, pour limiter l'impact d'une fuite.
  • Moindre privilège : n'activez que les modèles nécessaires ; pour un compte entreprise, utilisez des sous-utilisateurs IAM et un AK/SK pour l'administration.
  • Jamais côté frontend : la clé reste sur le serveur ; le web et l'application passent par votre propre backend.
  • Pas de stockage en clair : stockage chiffré dans le centre de configuration, pas de clé complète en base.
  • Surveillance des anomalies : alertes de quota, pics d'appels, IP inhabituelles et taux d'échec.
  • Audit conservé : qui a créé quelle clé et quand, pendant au moins un cycle de rotation.

8. Rotation et réponse à une fuite

Une rotation régulière réduit le risque de fuite durable. Procédez dans cet ordre :

  1. Créer une nouvelle clé avec la date dans le nom, par exemple seedance-prod-202610.
  2. L'écrire dans le centre de configuration, puis la déployer d'abord sur une instance ou un environnement.
  3. Valider la chaîne minimale soumission, polling et téléchargement, et vérifier facturation et quota.
  4. Après bascule complète, observer 24 à 48 heures et confirmer que l'ancienne clé n'a plus d'appels.
  5. Désactiver et supprimer l'ancienne clé, puis contrôler logs et factures à la recherche d'appels anormaux.

En cas de fuite suspectée, inversez l'ordre : désactivez d'abord la clé compromise, examinez l'historique d'appels et la facture, puis recréez et faites un retour d'expérience. Changer seulement la chaîne dans le code sans révoquer l'ancienne clé laisse le risque intact.

Questions fréquentes

La clé API Seedance et le mot de passe du compte Volcengine sont-ils identiques ?

Non. La clé sert uniquement à l'authentification des interfaces et ne permet pas de se connecter à la console ; le mot de passe sert à la console et à la gestion du compte. Conservez-les séparément et ne les notez pas au même endroit.

La clé est correcte, pourquoi un 401 persiste-t-il ?

Les causes courantes sont un format d'en-tête incorrect, des espaces ou sauts de ligne lors du copier-coller, une URL de base qui ne correspond pas à la plateforme de la clé, une clé désactivée, ou un état de compte ou de service anormal. Commencez par une requête curl minimale, puis éliminez les causes une par une.

Une même clé peut-elle appeler des modèles texte et vidéo ?

Cela dépend de l'activation et des permissions sur la plateforme. Même sur un compte unique, les modèles s'activent séparément ; vérifiez leur disponibilité dans la console et fiez-vous à la réponse réelle.

Peut-on placer la clé dans le frontend web ou mobile ?

Ce n'est pas recommandé, et il faut l'éviter. Le code frontend peut être extrait et la clé serait directement exposée. La bonne pratique consiste à garder la clé dans votre backend, qui relaie les requêtes, avec authentification et limitation de débit.

À quelle fréquence faire tourner la clé ?

Il n'existe pas de norme unique. Une pratique courante est une rotation tous les 90 jours, et immédiatement en cas de changement de personnel, de fuite suspectée ou de changement de fournisseur. Avant la rotation, vérifiez que tous les appelants de l'ancienne clé ont migré.

Prochaines étapes

Déterminez d'abord si vous passez par l'officiel ou par une passerelle, puis créez une clé dédiée et faites un test de fumée avec la tâche la plus courte. Pour un point d'entrée unifié, créez un compte sur ZSQH AI Gateway et vérifiez le canal Seedance et sa facturation sur la page tarifs des modèles.

Lectures associées :