La clé de l'API Doubao ne se crée pas dans l'application Doubao, mais dans la console Volcano Ark. Beaucoup se trompent dès la première étape : ils cherchent dans les réglages de l'application de chat ou dans le centre de facturation. À retenir : Doubao est une famille de modèles, Volcano Ark est la plateforme qui fournit ces modèles, et la clé appartient à un espace de travail rattaché à un compte Volcano Engine.
Cet article suit l'ordre « ouvrir un compte — créer une clé — restreindre les permissions — vérifier le modèle — diagnostiquer un 401 — renouveler », afin de couvrir un cycle de gestion de clé exploitable en production. Les tarifs et quotas font foi dans la console.
Note : Doubao, Volcano Ark, Volcano Engine et ByteDance sont des marques ou noms de produits de ByteDance et de ses sociétés affiliées. Cet article est une discussion technique sans lien de filiale, d'agence ou de parrainage avec ces sociétés. Les interfaces, permissions et quotas peuvent évoluer : référez-vous à la documentation officielle et à la console.
I. Distinguer compte, clé, espace de travail et modèle
Les problèmes de clé viennent souvent d'un désalignement entre ces quatre objets :
| Objet | Où | Rôle | Erreur courante |
|---|---|---|---|
| Compte Volcano Engine | Inscription, vérification d'identité, facturation | Détermine le solde, le contrat, les factures et le propriétaire de la clé | Utiliser un compte personnel pour une activité d'entreprise, puis ne pas pouvoir facturer ni payer par virement |
| Clé API | Page de gestion des clés API dans la console Ark | Justificatif d'identité lors des appels | Copier avec des espaces ou un saut de ligne, ou l'inscrire dans le code front-end |
| Espace de travail | Sélecteur en bas à gauche de la console | Isole ressources, membres et permissions | La clé et le point d'accès ne sont pas dans le même espace, l'appel est refusé |
| Modèle ou point d'accès | Liste des modèles, page d'inférence en ligne | Détermine le modèle réellement appelé | Confondre l'ID de modèle et l'ID de point d'accès commençant par ep- |
Moyen mnémotechnique : le compte paie, l'espace de travail détermine ce qui est visible, la clé détermine l'identité d'appel, le modèle ou le point d'accès détermine la version appelée. Tout décalage peut se traduire par un 401 ou un 404.
II. Ouvrir Volcano Ark et créer une clé API
Exemple de parcours dans la console Volcano Ark :
- Créez un compte Volcano Engine et effectuez la vérification d'identité. Pour une entreprise, utilisez l'entité juridique afin que contrat, paiement et facture soient cohérents.
- Accédez à la console Volcano Ark, vérifiez que le service est activé et choisissez la région, par exemple Pékin.
- Vérifiez l'espace de travail courant en bas à gauche. Les nouveaux comptes utilisent généralement l'espace par défaut ; pour un projet d'équipe, créez un espace dédié.
- Ouvrez la page de gestion des clés API et choisissez « Créer une clé API ». Nommez-la par usage et environnement, par exemple
doubao-dev-202610etdoubao-prod-202610. - Stockez-la immédiatement dans un gestionnaire de mots de passe ou un coffre-fort de secrets côté serveur ; ne transmettez jamais la clé complète par messagerie ou e-mail.
- Créez une clé distincte pour le test, la préproduction et la production. La documentation officielle indique qu'un compte principal peut créer par défaut jusqu'à 50 clés API.
Un détail : la documentation officielle précise que les clés créées depuis le 17 septembre 2026 utilisent un nouveau format en clair, sans changement du mécanisme d'authentification ; les clés antérieures restent valides. Les deux formats sont normaux : vérifiez surtout à quel espace de travail appartient la clé.
III. Périmètre de la clé : espace de travail, modèles autorisés et IP
Une clé API n'est pas un passe-partout pour tout le compte. La documentation officielle indique qu'une clé ne peut accéder qu'aux services de modèles et applications de l'espace de travail où elle a été créée, sans accès inter-projets ; si un point d'accès migre vers un autre espace, l'ancienne clé devient invalide.
À la création ou ensuite, deux restrictions sont généralement possibles :
- Limiter les modèles : n'autoriser la clé à appeler que certains ID de modèles ou points d'accès personnalisés, pour éviter qu'une clé compromise donne accès à toute la gamme.
- Limiter les IP source : configurer une liste blanche d'IP pour réduire le risque d'utilisation à distance après une fuite.
Pour la gestion d'équipe, découpez les clés par « application + environnement » plutôt que par personne. Au départ d'un collaborateur, désactivez seulement les clés concernées sans impacter les autres services ; conservez les journaux d'appel pour savoir quelle clé a appelé quel modèle et quand. Les espaces de travail isolent les projets ; les permissions des membres et les quotas font foi dans la console.
IV. ID de modèle et ID de point d'accès : ne pas les confondre
Volcano Ark propose deux modes d'appel courants :
- Inférence prédéfinie : aucun point d'accès à créer ; le champ
modelreçoit directement l'ID de modèle, par exempledoubao-seed-2-1-pro-260915. L'ID contient généralement une date de version ; ne l'abrégez pas de mémoire. - Point d'accès d'inférence personnalisé : créé dans la page « Inférence en ligne », le champ
modelreçoit l'ID du point d'accès (souvent préfixéep-). Il convient aux déploiements fixes, à une gestion fine ou aux modèles affinés par LoRA. Le point d'accès doit passer de « en cours de planification » à « sain » avant de pouvoir être appelé de façon stable.
La différence ne se limite pas au format. La documentation officielle précise qu'avec une signature Access Key (AK/SK), le champ model doit contenir l'ID du point d'accès ; avec une clé API, on peut utiliser l'ID de modèle ou celui du point d'accès selon la documentation. Certains modèles ou comptes n'autorisent pas l'appel direct par ID de modèle : le nom du modèle renvoie alors InvalidEndpointOrModel.ModelIDAccessDisabled. Il faut créer un point d'accès personnalisé et utiliser l'ID ep-.
Inutile donc de lier un modèle à la clé dès sa création, mais avant la mise en production, vérifiez : le modèle est disponible dans le compte et la région, la clé y a accès, et le champ model de la requête correspond au mode d'appel. Les correspondances de noms font foi dans la console et sur la page Tarifs et modèles.
V. Placer la clé dans une variable d'environnement
N'inscrivez jamais la clé dans le code, un fichier de configuration ou un bundle front-end. Côté serveur, la pratique courante consiste à utiliser des variables d'environnement :
# .env reste en local ou dans un coffre-fort de secrets, et figure dans .gitignore
export ARK_API_KEY="votre clé API Volcano Ark"
export ARK_MODEL_ID="doubao-seed-2-1-pro-260915"
# Avec un point d'accès personnalisé :
# export ARK_ENDPOINT_ID="ep-votre-id-de-point-acces"
En Python, lisez avec os.environ["ARK_API_KEY"], sans valeur par défaut. En conteneur, montez un secret ; en CI/CD, utilisez des variables chiffrées ; dans les journaux, ne consignez que le préfixe ou l'empreinte de la clé. Les navigateurs, applications mobiles et mini-programmes ne doivent jamais détenir la clé : tout passe par un proxy côté serveur.
VI. Diagnostiquer les erreurs 401, 403, 404 et 429
| Symptôme | Code courant | Cause fréquente | Traitement |
|---|---|---|---|
| 401 | AuthenticationError |
Clé absente, erronée, désactivée, ou en-tête sans Bearer |
Recopier la clé, vérifier l'en-tête Authorization, confirmer que la clé et le point d'accès sont dans le même espace |
| 403 | AccessDenied |
Clé restreinte par modèle ou IP, compte sans droit sur la ressource | Vérifier la liste de modèles, la liste d'IP et les droits de l'espace de travail |
| 404 | InvalidEndpointOrModel.NotFound |
ID de modèle ou de point d'accès erroné, ou ressource absente de l'espace | Recopier l'ID complet depuis la console et vérifier région et espace de travail |
| 404 | ModelNotOpen |
Modèle non activé sur le compte | Activer le modèle correspondant dans la console Ark |
| 404 | InvalidEndpointOrModel.ModelIDAccessDisabled |
Appel direct par ID de modèle non autorisé sur ce compte | Créer un point d'accès personnalisé et utiliser l'ID ep- |
| 429 | RateLimitExceeded.* |
RPM/TPM dépassé pour le compte, le modèle ou le point d'accès | Réduire la concurrence, réessayer avec un retrait exponentiel, demander une hausse de quota si nécessaire |
| 500/503 | InternalServiceError, ServerOverloaded |
Anomalie ou surcharge du service amont | Attendre brièvement et réessayer, prévoir un modèle ou canal de secours |
Ordre de diagnostic : statut HTTP, puis code d'erreur, puis corps de requête. Sur un 401, ne soupçonnez pas d'abord le solde ; un solde insuffisant correspond généralement à un 403 AccountOverdueError. Sur un 404, ne modifiez pas le code tout de suite : recopiez d'abord l'ID de modèle et l'ID de point d'accès depuis la console.
VII. Connexion directe ou passerelle unifiée
La connexion directe convient aux équipes qui n'utilisent que Doubao, peuvent gérer elles-mêmes vérification d'identité et rechargement, et ont besoin d'un contrat et de factures Volcano Engine. La clé et l'URL de base doivent être associées : une clé officielle ne se combine qu'avec https://ark.cn-beijing.volces.com/api/v3, une clé de passerelle uniquement avec l'adresse de la passerelle ; tout mélange renvoie généralement un 401.
Une passerelle unifiée convient aux équipes qui utilisent plusieurs fournisseurs comme Doubao et DeepSeek, ou qui veulent un point d'entrée unique pour la facturation, les quotas et les journaux. Lors du choix, vérifiez : la correspondance des noms de modèles, le support complet du streaming et des appels d'outils, la limitation par projet, la notification des incidents et les clauses sur les données. La passerelle IA ZSQH est un service d'accès tiers indépendant, sans lien de filiale avec ByteDance ; pour tester, créez un compte sur la page d'inscription et consultez la facturation sur Tarifs et modèles.
VIII. Rotation et gestion d'une fuite
Une clé doit avoir un cycle de vie, comme un mot de passe, plutôt que servir jusqu'à provoquer une erreur :
- Créez une nouvelle clé aux mêmes permissions et ne l'utilisez d'abord que pour les tests ou une instance de préproduction.
- Mettez à jour les variables d'environnement ou le coffre-fort de secrets, redémarrez le service et confirmez que les appels fonctionnent.
- Observez pendant 24 à 72 heures le taux d'erreur, la latence et la consommation. Une fois la stabilité confirmée, désactivez l'ancienne clé sans la supprimer tout de suite, afin de pouvoir revenir en arrière.
- En cas de départ, de fuite de code ou d'apparition de la clé dans un dépôt public, désactivez immédiatement et créez-en une nouvelle ; ne vous contentez pas de changer un mot de passe.
- Examinez les relevés de consommation et les journaux récents pour détecter un modèle, une plage horaire ou une IP source anormale.
La documentation officielle rappelle qu'une clé divulguée permet à un tiers de consommer votre quota. En cas de fuite, désactivez d'abord pour limiter les dégâts, puis recherchez la cause.
Questions fréquentes
Peut-on générer une clé API Doubao dans l'application Doubao ?
Non. L'application Doubao s'adresse au grand public ; la clé API se crée dans la page de gestion des clés de la console Volcano Ark.
Faut-il choisir un modèle avant de créer la clé ?
En général, non. La clé est un justificatif d'appel rattaché au compte ou à l'espace de travail ; le modèle est précisé dans le champ model de la requête. Il est aussi possible de restreindre les modèles ou points d'accès autorisés sur la clé.
Pourquoi une clé qui fonctionnait hier renvoie-t-elle 401 aujourd'hui ?
Causes courantes : clé désactivée ou renouvelée, clé et point d'accès dans des espaces différents, migration du point d'accès, en-tête Bearer manquant, état de compte anormal. Vérifiez d'abord le propriétaire de la clé, puis l'en-tête et l'espace de travail.
Faut-il utiliser l'ID de modèle ou l'ID de point d'accès ep- ?
Inférence prédéfinie : ID de modèle. Point d'accès personnalisé : ID ep-. Avec une signature Access Key, l'ID de point d'accès est obligatoire. Si l'erreur ModelIDAccessDisabled apparaît, le compte ne permet pas l'appel direct par ID de modèle : créez un point d'accès.
Que faire en priorité si une clé est compromise ?
Désactivez ou supprimez immédiatement la clé exposée, créez une clé de remplacement et mettez à jour la configuration serveur, puis examinez la consommation et les journaux. Ne cherchez pas d'abord l'origine de la fuite, afin d'éviter une consommation continue du quota.
Lectures associées :
