La clé API Qwen est le justificatif d'appel des modèles Tongyi Qianwen. Ce n'est pas qu'une chaîne de caractères : la réussite de l'authentification, le compte facturé et la capacité à diagnostiquer rapidement un incident dépendent du type et du propriétaire de la clé. Une clé Qwen est en outre liée à deux éléments, la région et l'espace métier, ce qui explique de nombreux « 401 alors que la clé semble correcte ».
Cet article suit l'ordre « comprendre l'appartenance — créer — configurer les droits — stocker — diagnostiquer — renouveler », et couvre les deux voies : Alibaba Cloud Bailian et la passerelle IA ZSQH.
Note : Qwen, Tongyi Qianwen, Alibaba Cloud, Bailian (Model Studio) et DashScope sont des marques ou noms de produits du groupe Alibaba et de ses sociétés affiliées. Cet article est une présentation technique, sans lien de filiale, d'agence ou d'autorisation avec le groupe Alibaba. Les points d'entrée, règles de permission et bases de facturation font foi dans la documentation officielle et la console Alibaba Cloud Bailian.
I. Comprendre les trois niveaux d'appartenance d'une clé
Dans Bailian, une clé appartient simultanément à trois dimensions :
- Compte : compte principal Alibaba Cloud ou utilisateur RAM.
- Région : Pékin, Singapour, Virginie aux États-Unis, Hong Kong, etc., chacune indépendante.
- Espace métier : espace par défaut ou sous-espace, qui détermine les modèles accessibles.
Si l'une de ces dimensions ne correspond pas, l'appel échoue en authentification ou en permissions. La région est particulièrement sensible : chaque région possède son propre domaine d'accès, ses clés et sa liste de modèles ; une clé ne traverse pas les régions. Une clé créée à Pékin et utilisée sur l'adresse de Singapour renvoie généralement 401 et invalid_api_key, sans que la clé soit pour autant invalide.
II. Créer une clé API dans Alibaba Cloud Bailian
La voie officielle convient aux équipes qui n'utilisent que Qwen et veulent accéder immédiatement aux nouveaux modèles et fonctionnalités. Les étapes sont les suivantes :
- Connectez-vous à la console Alibaba Cloud Bailian et sélectionnez la bonne région en haut à droite.
- Ouvrez la page des clés API et cliquez sur « Créer une clé API ».
- Choisissez le compte de rattachement : compte principal Alibaba Cloud par défaut, ou utilisateur RAM.
- Choisissez l'espace métier : l'espace par défaut convient pour démarrer ; un sous-espace est préférable pour isoler modèles ou coûts.
- Définissez les permissions : « Toutes » pour commencer, ou « Personnalisées » pour restreindre avec une liste blanche d'IP et un périmètre de modèles.
- Une fois la clé créée, copiez immédiatement la valeur complète et l'API Host indiqué, puis stockez-les dans un gestionnaire de mots de passe ou un coffre-fort de secrets.
- Validez avec une requête minimale que l'authentification, la région et le nom de modèle sont corrects, avant d'écrire la configuration de production.
Deux détails sont souvent oubliés. D'abord, la création d'une clé exige les droits de super-administrateur ou d'administrateur d'espace métier ; un membre ordinaire peut ne pas voir le bouton. Ensuite, la valeur en clair n'est généralement affichée qu'une fois, à la création ; après fermeture de la fenêtre, elle n'est plus consultable. Si vous ne l'avez pas enregistrée, il faut la réinitialiser ou en créer une autre. Une clé de longue durée n'expire pas automatiquement, mais « sans expiration » ne signifie pas « sans rotation ».
III. Espaces métier, RAM et limites de permissions
L'espace métier est au cœur du modèle de permissions de Bailian. Une clé de l'espace par défaut peut appeler les modèles standard de cet espace ; une clé d'un sous-espace ne peut appeler que les modèles autorisés dans ce sous-espace. Si vous avez déployé un modèle affiné, utilisez la clé de l'espace métier où il réside, sinon vous obtiendrez « le modèle existe mais l'accès est refusé ».
Les règles liées aux utilisateurs RAM méritent attention :
- Une clé peut appartenir à un utilisateur RAM, dont le format de compte est généralement
username@<AccountAlias>.onaliyun.com. - Supprimer cet utilisateur ou ce rôle dans la console RAM invalide immédiatement ses clés, sans possibilité de restauration.
- Retirer l'utilisateur RAM de l'espace métier invalide la clé ; la réintégration la rétablit.
Les permissions personnalisées conviennent à la production : liste blanche d'IP pour restreindre la source, périmètre de modèles pour limiter les appels. La liste blanche accepte IPv4 et IPv6, mais l'IPv6 n'est prise en charge qu'à Pékin et la région américaine n'accepte que l'IPv4 ; le nombre maximal d'entrées dépend de la console. Les clés de forfait (par exemple celles commençant par sk-sp-) relèvent d'un autre système que les clés API générales : n'utilisez pas une clé de forfait avec une URL de base générale.
IV. Placer la clé dans une variable d'environnement
La pratique la plus risquée consiste à inscrire la clé dans le code source, un bundle front-end, une sortie de notebook ou un historique de chat. La variable d'environnement conventionnelle de Bailian est DASHSCOPE_API_KEY ; le code ne référence que le nom de la variable :
# Fichier .env local, à ajouter à .gitignore
DASHSCOPE_API_KEY=your_key_here
# Activation temporaire dans le terminal courant
export DASHSCOPE_API_KEY="your_key_here"
# Vérification minimale : clé, région et nom de modèle cohérents
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"qwen3.8-max","messages":[{"role":"user","content":"ping"}]}'
En production, appliquez au minimum : ne pas versionner le fichier .env ; utiliser le Secret Manager du fournisseur cloud, KMS ou un secret de conteneur ; des variables distinctes en CI/CD ; masquer l'en-tête Authorization dans les journaux ; ne jamais exposer une clé serveur côté front-end. Les noms de modèles et les tarifs de l'exemple évoluent avec les versions : les noms réels et la facturation font foi dans la liste de modèles de la console et sur la page Tarifs et modèles.
V. Clé officielle ou clé de passerelle
Si l'équipe n'utilise que Qwen, la clé officielle est la voie la plus directe. Si elle utilise aussi DeepSeek, GLM, Kimi et d'autres modèles, ou souhaite unifier quotas, factures et facturation, elle peut créer une clé sur la passerelle IA ZSQH. Les deux ne s'excluent pas : ce sont deux modes de gestion.
| Critère | Clé officielle Alibaba Cloud Bailian | Clé de la passerelle IA ZSQH |
|---|---|---|
| Point de création | Console Bailian | Console de la passerelle |
| Périmètre | Qwen et modèles tiers dans la région Bailian | Modèles activés sur la passerelle |
| Compte de facturation | Compte Alibaba Cloud | Compte de la passerelle |
| URL de base | dashscope.aliyuncs.com et autres adresses Bailian |
https://ai.zhongshangqihang.com/v1 |
| Cas d'usage | Qwen uniquement, accès aux derniers modèles | Accès et facturation multi-modèles unifiés |
Les deux systèmes d'authentification sont distincts et ne se mélangent pas : clé officielle avec URL officielle, clé de passerelle avec URL de passerelle. Le mélange se traduit le plus souvent par un 401, ou par une requête envoyée à la mauvaise région ou au mauvais service.
VI. Diagnostiquer un 401 : la région d'abord, puis les en-têtes
Face à un 401, ne réinstallez pas le SDK immédiatement ; suivez cet ordre :
- L'en-tête est-il
Authorization: Bearer <key>, avec un seul espace aprèsBearer? - La clé a-t-elle été copiée en entier, sans saut de ligne, guillemets ni espaces ?
- La région de création de la clé correspond-elle à celle de l'URL de base ?
- L'espace métier correspond-il ? Un domaine dédié à un espace n'accepte que ses propres clés.
- La clé a-t-elle été désactivée, supprimée ou réinitialisée ? L'utilisateur RAM créateur a-t-il été retiré de l'espace ou supprimé ?
- Une clé de forfait
sk-sp-a-t-elle été utilisée sur une interface générale ? - Le compte est-il en découvert ? Un impayé renvoie généralement 400 et
Arrearage, pas 401, mais se manifeste aussi par « l'appel ne fonctionne pas ».
Si tout est normal, notez l'identifiant de requête de la réponse et consultez les journaux d'appel ou la supervision de modèles dans la console. Cet identifiant est l'information la plus utile pour un ticket, bien plus que « ça renvoie une erreur ».
VII. Rotation, révocation et audit
Une seule clé pour tout faire simplifie à court terme mais complique le diagnostic sur la durée. Découpez au minimum par environnement et par service : test, production et CI distincts, une clé par service backend, un nom explicite incluant environnement et service, par exemple prod-customer-service. Ajoutez des plafonds et des alertes de consommation pour détecter les appels anormaux avant qu'ils n'épuisent le quota.
Lors d'une rotation, ne supprimez pas directement l'ancienne clé. L'ordre correct est : créer la nouvelle clé, basculer un faible volume en progressif, vérifier permissions, quotas et facturation, puis révoquer l'ancienne. En cas de problème, le retour arrière reste possible. En cas de départ d'un membre, de fin de prestation ou d'apparition de la clé dans des journaux ou un dépôt public, révoquez immédiatement et recréez, puis vérifiez la facturation et les journaux d'appel.
VIII. Questions fréquentes
1. Où créer une clé API Qwen ?
Connectez-vous à la console Alibaba Cloud Bailian, choisissez la région, puis ouvrez la page des clés API. Avec la passerelle IA ZSQH, la création se fait dans la console de la passerelle ; les deux clés ne sont pas interchangeables.
2. Pourquoi une clé valide renvoie-t-elle 401 ?
La cause la plus fréquente est une région incompatible, puis une copie incomplète, un en-tête mal formé, un espace métier différent ou un utilisateur RAM créateur supprimé. Vérifiez d'abord que la clé et l'URL de base appartiennent à la même région, puis les en-têtes.
3. Une clé peut-elle servir à plusieurs projets ?
Techniquement oui, mais ce n'est pas recommandé. Une clé partagée ne permet pas d'identifier la source des appels, une fuite affecte toute l'activité et les coûts sont difficiles à ventiler. Découpez au minimum par environnement et service critique.
4. Que faire si une clé est compromise ?
Désactivez ou supprimez immédiatement la clé dans la console, créez-en une nouvelle et mettez à jour la configuration serveur ; vérifiez la facturation et les journaux pour détecter une consommation anormale ; contactez le support si nécessaire. Ne vous contentez pas de modifier le code en laissant l'ancienne clé active.
5. Peut-on mélanger clé officielle et clé de passerelle ?
Non. Les systèmes d'authentification, les URL de base et les comptes de facturation diffèrent. Le mélange renvoie généralement 401 et peut envoyer la requête à une mauvaise adresse de service.
