Chatbox est un client IA multiplateforme, disponible sur ordinateur et mobile, qui peut se connecter à plusieurs fournisseurs de modèles. Deux usages typiques : le service Chatbox AI intégré, ou votre propre clé API pour accéder à vos modèles. Cet article traite uniquement le second cas : connecter Chatbox à une API personnalisée compatible OpenAI.

Remarque : Chatbox est un produit de son détenteur ; cet article est purement technique. Les noms de menus et l'emplacement des champs varient selon les versions ; la version actuelle fait foi. Modèles et prix sont sur la page Tarifs des modèles.

1. Déterminer le mode à utiliser

Mode Facturation Emplacement Pour qui
Chatbox AI Selon l'offre du client Connexion au compte Utilisateurs qui ne veulent pas gérer de clé
Clé API personnelle À l'usage par le fournisseur API Réglages du fournisseur de modèles Équipes disposant déjà d'une passerelle ou d'un compte modèle
Modèle local Selon le matériel Service d'inférence local Situations exigeant que les données restent locales

Les deux modes peuvent coexister. Nommez le fournisseur personnalisé de façon distincte, par exemple « ZSQH », pour éviter la confusion avec le service intégré. Avant de changer de modèle, vérifiez quel fournisseur la conversation utilise.

2. Préparer trois paramètres

  1. Clé API : créée dans ZSQH AI Gateway, nommée selon le projet.
  2. Hôte API : adresse compatible OpenAI, généralement https://ai.zhongshangqihang.com/v1.
  3. ID de modèle : copié depuis la page Tarifs des modèles.

Validez d'abord avec curl, pour écarter un problème côté passerelle :

export ZSQH_API_KEY="sk-votre-cle"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "votre-id-modele",
    "messages": [{"role": "user", "content": "Réponds seulement OK"}]
  }'

Si choices est renvoyé, la clé, l'adresse et le modèle sont valides ; il ne reste que les opérations dans le client.

3. Ajouter un fournisseur de modèles personnalisé

Avec les versions courantes, la procédure est la suivante (les libellés exacts dépendent de votre version) :

  1. Ouvrez Chatbox et cliquez sur « Réglages » en bas à gauche.
  2. Dans la colonne de gauche, choisissez « Fournisseurs de modèles », puis « + Ajouter » en bas.
  3. Donnez au fournisseur un nom facile à identifier.
  4. Choisissez le mode API compatible OpenAI ou l'option OpenAI correspondante.
  5. Saisissez la clé API et l'hôte API.
  6. Cliquez sur « Récupérer » pour charger la liste des modèles, ou ajoutez l'ID manuellement.
  7. Cliquez sur « Vérifier » pour tester la connexion avec le modèle ajouté.

Un échec de « Récupérer » ne signifie pas forcément que la clé est mauvaise : la passerelle peut ne pas exposer d'interface de liste. Saisissez alors l'ID manuellement, puis utilisez « Vérifier ».

4. Hôte API et /v1

L'URL de base est l'endroit où l'on se trompe le plus facilement avec une API personnalisée. Vérifiez avec ce tableau :

Élément Valeur conseillée Attention
Mode API Compatible OpenAI Ne pas choisir Anthropic ou Gemini
Hôte API https://ai.zhongshangqihang.com/v1 Sans barre oblique finale
Clé API sk-... Sans espace avant ou après
ID de modèle Selon la page tarifs Respecter casse et suffixe de version

Si l'adresse complète renvoie 404, essayez sans /v1 ; si le domaine seul renvoie 404, ajoutez /v1. Les versions de client n'assemblent pas les chemins de la même façon ; fiez-vous au résultat réel de la requête. 401 oriente vers la clé, 404 vers le chemin : cet ordre fait gagner beaucoup de temps.

5. ID de modèle et capacités

En ajout manuel, il faut souvent choisir le type de modèle et ses capacités. Correspondances courantes :

Type de modèle Usage Capacités à cocher
Modèle de chat Questions-réponses, rédaction, traduction Texte, streaming
Modèle de raisonnement Analyses complexes, planification Raisonnement ou processus de réflexion
Modèle visuel Compréhension d'images, questions sur captures Entrée d'images
Modèle à outils Appel de fonctions, plugins Appel d'outils

Un mauvais type peut empêcher le modèle d'apparaître dans le sélecteur de chat ; une capacité non cochée fait échouer le téléversement d'images ou l'appel d'outils. En cas de doute, configurez d'abord le chat texte, puis ajoutez les capacités une par une.

6. Vérifier la connexion

La fonction « Vérifier » teste généralement le texte, les images et l'appel d'outils séparément. Confirmez au minimum le succès du texte. Plus sûr : envoyez une vraie question et observez trois choses :

  1. Le premier caractère revient-il normalement, ou l'indicateur tourne-t-il longtemps ?
  2. Le contexte est-il conservé sur plusieurs tours ?
  3. Une réponse longue se coupe-t-elle en cours de route ?

Si seules les réponses longues se coupent, vérifiez le proxy réseau et le streaming ; si toutes les requêtes échouent, revenez à la clé et à l'URL de base. Vous pouvez comparer avec un logiciel proxy sur l'ordinateur, mais ne mettez pas l'adresse du proxy dans l'hôte API.

7. Erreurs courantes et traitement

Symptôme Cause fréquente Traitement
401 Unauthorized Clé erronée, expirée ou supprimée Recréer la clé, vérifier les espaces
404 Not Found Chemin de l'hôte API incorrect Ajouter ou retirer /v1 puis réessayer
model not found ID erroné ou modèle non ouvert Copier depuis la page tarifs
Délai de connexion Réseau injoignable ou proxy bloquant Changer de réseau, vérifier le pare-feu
Réponse qui s'arrête Connexion de streaming interrompue Désactiver le streaming pour comparer
429 Too Many Requests Concurrence ou quota limités Réduire la concurrence, consulter l'usage
Échec de téléversement d'image Modèle sans vision ou capacité non cochée Choisir un modèle visuel et cocher l'entrée d'images

Ne changez qu'une variable à la fois lors du dépannage. Si vous modifiez simultanément clé, adresse et modèle, même un rétablissement ne dira pas quelle étape a corrigé le problème, et l'erreur reviendra.

8. Sécurité et coûts

  1. Mobile et bureau peuvent stocker la clé ; prudence sur un appareil partagé.
  2. Émettre une clé dédiée à Chatbox, pour pouvoir la révoquer à tout moment.
  3. Fixer un plafond de budget côté passerelle, pour éviter une consommation en arrière-plan.
  4. Ne pas coller de clés de production, de listes clients ou de contrats dans les conversations.
  5. Exporter ou sauvegarder régulièrement les conversations importantes ; désinstaller le client ne signifie pas que le cloud conserve une copie.
  6. En usage d'équipe, émettre une clé par personne pour ventiler l'usage.

Questions fréquentes

Faut-il payer un abonnement avec sa propre clé API dans Chatbox ?

En mode clé personnelle, les appels de modèles sont facturés à l'usage par le fournisseur API ; la tarification du client Chatbox lui-même dépend de la version actuelle. Ne confondez pas les deux.

Pourquoi « Récupérer les modèles » échoue-t-il systématiquement ?

La passerelle peut ne pas exposer d'interface de liste, ou le chemin de l'URL de base être incorrect. Ajoutez d'abord un ID manuellement : si cela fonctionne, seule l'interface de liste n'est pas prise en charge.

Faut-il ajouter /v1 à l'hôte API ?

La plupart des configurations compatibles OpenAI l'exigent. Si l'adresse avec et sans /v1 échoue, vérifiez d'abord avec curl l'adresse complète correcte, puis reportez-la dans le client, sans deviner.

Peut-on configurer plusieurs fournisseurs en même temps ?

Oui. Nommez chaque fournisseur séparément et choisissez explicitement le modèle dans la conversation. Avec plusieurs fournisseurs, l'erreur la plus fréquente est de croire utiliser A alors que la requête part vers B.

Peut-on l'utiliser directement sur mobile ?

Oui, l'application mobile permet de configurer un fournisseur personnalisé, mais les entrées et capacités varient selon la plateforme et la version. Il est déconseillé de conserver longtemps une clé sensible sur un téléphone.

Pour aller plus loin

La configuration de Chatbox repose sur trois points : hôte API, clé et ID de modèle. Validez d'abord avec curl, puis ouvrez le client ; en cas d'échec, traitez 401 via la clé, 404 via le chemin et model not found via l'ID. Pour une entrée et une gestion d'usage unifiées, vous pouvez créer un compte ZSQH AI Gateway ; modèles et prix sont sur la page Tarifs des modèles.

Lectures associées :