Clé API Chatbox : multi-modèles, sécurité et synchronisation (2026)

Connecter Chatbox à une API personnalisée prend cinq minutes à certains, tandis que d'autres rencontrent des 401 à répétition. La différence vient rarement du client : elle est dans la création, le stockage et le périmètre d'usage de la clé. Cet article traite quatre questions autour de la clé API : comment la créer, comment configurer plusieurs modèles, où elle est stockée, comment la faire tourner et dépanner.

Remarque : Chatbox est une marque de son détenteur. Cet article est purement technique et n'implique aucune affiliation avec l'équipe Chatbox ; modèles et prix figurent sur la page tarifs des modèles, l'interface dépend de la version installée.

1. Distinguer deux « sources de clé »

Deux jeux d'identifiants peuvent coexister dans Chatbox : le compte de connexion au service Chatbox AI, et la clé API saisie pour un fournisseur personnalisé. Les entités de facturation diffèrent, tout comme le diagnostic.

Source	Facturation	Cas adapté	Attention
Compte Chatbox AI	Selon l'offre client	Ne pas gérer de clé soi-même	Sans rapport avec la clé personnalisée
Clé API personnelle	Facturée par le fournisseur d'API	Passerelle ou compte de modèles existant	À conserver et faire tourner soi-même
Modèle local	Selon le matériel local	Données qui ne sortent pas	Aucune clé distante nécessaire

Face à un « je suis connecté mais j'obtiens 401 », vérifiez d'abord quel fournisseur est sélectionné dans la session. Une connexion au compte réussie ne prouve pas que la clé du fournisseur personnalisé est correcte.

2. Créer une clé : nom, rattachement et permissions

Après inscription sur ZSQH AI Gateway, créez la clé dans la console. Trois bonnes pratiques dès la création :

Nom traçable : au format « appareil-usage-utilisateur », par exemple chatbox-mac-alice.
Une clé par usage : bureau, mobile et scripts d'automatisation séparés, pour localiser vite un incident.
Rattachement documenté : date de création, responsable et usage dans le registre interne.

La clé complète n'est généralement affichée qu'une fois, à la création ; après fermeture de la page, elle n'est plus consultable. Enregistrez-la immédiatement dans un gestionnaire de mots de passe, sans capture d'écran envoyée dans un groupe. Si la console propose quota, périmètre de modèles ou restriction IP, appliquez le moindre privilège ; en cas de doute, la règle minimale reste « une clé distincte ».

3. Configurer plusieurs fournisseurs et modèles dans Chatbox

Plusieurs modèles ne signifient pas plusieurs clés. En général, un fournisseur porte une clé et plusieurs identifiants de modèles :

Ouvrez les paramètres, puis « Fournisseurs de modèles ».
Ajoutez un fournisseur compatible OpenAI, avec un préfixe d'environnement dans le nom.
Saisissez l'URL de base, généralement https://ai.zhongshangqihang.com/v1.
Saisissez la clé API en vérifiant l'absence d'espaces avant et après.
Ajoutez les identifiants de modèles à la main, ou tentez de récupérer la liste.
Choisissez le type de chaque modèle : dialogue, vision, raisonnement ou appel d'outils.
Cliquez sur « Vérifier », puis revenez au chat pour changer de modèle.

L'identifiant de modèle suit la page tarifs des modèles. Le nom affiché peut être personnalisé, mais l'identifiant API doit être identique caractère par caractère. Nommez séparément les modèles de dialogue et de vision, par exemple « dialogue-principal » et « vision-capture », pour éviter les mauvaises sélections.

Si l'équipe utilise aussi Cherry Studio, LobeChat ou un autre client, harmonisez les noms de fournisseurs et les alias de modèles, afin d'éviter qu'une même personne utilise des modèles différents selon le client.

4. Où est stockée la clé : local, synchronisation et sauvegarde

La version de bureau conserve généralement la configuration dans le répertoire de données applicatives local ; la version mobile, dans le bac à sable de l'application. Le chemin dépend du système et de la version ; évitez de modifier les fichiers de configuration à la main.

Pour la synchronisation, distinguez trois choses :

Synchronisation des conversations : disponibilité et périmètre dépendent de la version du client et de l'offre de compte.
Synchronisation des paramètres : la configuration des fournisseurs peut suivre le compte ou rester locale.
Synchronisation des clés : ne confondez pas « paramètres synchronisés » et « clé synchronisée en sécurité ». Beaucoup de clients écrivent la clé dans la configuration ou les fichiers de sauvegarde.

Les exports de sauvegarde, répertoires de configuration migrés et captures partagées doivent donc être traités comme des fichiers sensibles. Lors d'un changement d'appareil, ressaisissez la clé plutôt que de copier tout le répertoire ; après confirmation que l'ancien appareil ne sert plus, révoquez son ancienne clé.

5. Moindre privilège : limiter chaque clé à son rôle

Une clé API n'est pas meilleure parce qu'elle est rare, mais parce que son périmètre est clair. Pratiques applicables :

Une clé par membre, sans partage.
Séparer production et essais, avec un quota plus bas pour les essais.
Ne conserver la clé que sur les appareils nécessaires ; la supprimer après usage sur un poste public.
Activer budget, liste blanche de modèles et alertes d'usage lorsque la console les propose.
N'écrire que les derniers caractères de la clé dans les journaux et tickets, jamais la clé complète.

Si le client gère plusieurs fournisseurs, séparez aussi « travail » et « personnel ». En cas de fuite d'un côté, une seule clé est révoquée sans affecter les autres appareils.

6. Rotation et révocation : un rythme fixe

Prévoyez une rotation au moins tous les 90 jours, et immédiatement en cas de mouvement de personnel, de perte d'appareil ou de configuration diffusée par erreur. L'ordre ne s'inverse pas :

Créez une nouvelle clé dans la console, avec la date en suffixe.
Remplacez la clé du fournisseur dans Chatbox.
Envoyez un message de test et vérifiez que le modèle répond.
Une fois la nouvelle clé opérationnelle, révoquez l'ancienne.
Contrôlez l'usage de la passerelle pour détecter des appels inconnus.
Mettez à jour le registre interne avec la date de rotation.

Pour vérifier, une commande suffit à lire le code de statut :

export ZSQH_API_KEY="sk-nouvelle-clé"

curl -sS -o /dev/null -w "%{http_code}\n" \
  "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY"

Un 200 confirme l'authentification ; un 401 invite à vérifier que la clé a été copiée en entier. Si la passerelle n'expose pas la liste des modèles, validez avec une requête de dialogue ordinaire. Pendant la rotation, ne changez pas en même temps l'URL de base et l'identifiant de modèle, sinon vous ne saurez pas quelle étape pose problème.

7. Pannes courantes : trier par code de statut

Symptôme	Cause fréquente	Traitement
`401 Unauthorized`	Clé erronée, expirée, révoquée ou avec espace	Recréer et recoller entièrement
`403 Forbidden`	Pas de droit sur le modèle, restriction géographique ou politique	Vérifier droits et périmètre dans la console
`404 Not Found`	Chemin de l'URL de base incorrect	Vérifier la présence ou l'absence de `/v1`
`429 Too Many Requests`	Concurrence ou quota limité	Réduire la concurrence, vérifier usage et plafond
`5xx`	Anomalie du service amont	Réessayer plus tard, conserver l'heure de la requête

Ne modifiez qu'une variable à la fois. Déterminez d'abord s'il s'agit « de cette clé » ou « de ce modèle » : tester une autre clé ou un autre modèle permet de trancher rapidement.

8. Liste de transmission d'équipe

Documentez les éléments suivants pour éviter la plupart des « ça ne marche plus après le changement de personne » :

Responsable de la clé, usage, date de création et prochaine rotation.
Nom du fournisseur, URL de base et liste des identifiants de modèles.
Appareils qui stockent la clé, et appareils partagés.
Procédure de révocation en cas de départ, mutation ou perte d'appareil.
Point de contrôle de l'usage anormal et personne à contacter.

Questions fréquentes

La clé suit-elle les conversations lors d'une synchronisation ?

Pas nécessairement. Synchronisation des conversations et des paramètres sont deux choses distinctes ; la clé suit ou non la configuration selon la version et le mode de connexion. Ne traitez pas la synchronisation comme un coffre-fort à clés : ressaisir la clé sur un nouvel appareil est plus sûr.

Une même clé peut-elle servir au bureau et au mobile ?

Techniquement, souvent oui, mais ce n'est pas conseillé durablement. Séparez les clés par appareil : en cas de perte ou de fuite d'un côté, la révocation est isolée sans impact sur l'autre.

Le « Vérifier » du client passe, mais le chat renvoie 401 ?

Vérifiez que le fournisseur et le modèle sélectionnés dans le chat sont bien ceux que vous venez de configurer. Avec plusieurs fournisseurs, l'erreur la plus fréquente est une requête envoyée à un fournisseur sans clé.

Faut-il rajouter les modèles après une rotation de clé ?

En général non. L'identifiant de modèle appartient à la configuration du fournisseur ; changer la clé ne modifie que l'authentification. Si le client vide la liste après le changement, rajoutez les modèles ; l'identifiant reste celui de la page tarifs.

Peut-on saisir la clé dans un logiciel proxy ou une extension de navigateur ?

Ce n'est pas recommandé. La clé ne devrait apparaître que dans les clients de confiance et la console de la passerelle. Logiciels proxy, outils de capture et extensions de navigateur peuvent lire ou transmettre la configuration : mieux vaut s'abstenir.

Prochaines étapes

La gestion des clés Chatbox se résume ainsi : une clé par usage, configuration et sauvegardes traitées comme des fichiers sensibles, rotation en créant d'abord la nouvelle puis en révoquant l'ancienne. Pour un point d'entrée unifié, l'usage et la gestion des droits, vous pouvez créer un compte ZSQH AI Gateway ; modèles et prix figurent sur la page tarifs des modèles.

Lectures associées :