Configuration de l’API Cherry Studio : ajouter un fournisseur personnalisé, une adresse et un modèle

Pour configurer sa propre API dans Cherry Studio, accédez à 設定 → 模型供應商 → 新增供應商 : saisissez la clé API, renseignez une adresse racine dans chacun des champs OpenAI et Anthropic de « 端點設定 », enregistrez, cliquez sur « 同步模型 » pour importer les modèles, puis utilisez « 檢查 » pour vérifier que cela fonctionne. Cet article se base sur la v2.1.4 publiée le 30 septembre 2026 ; tous les noms des menus sont reproduits tels qu’ils figurent dans l’interface de Cherry Studio en chinois traditionnel. La version v2 a profondément modifié l’écran d’ajout d’un fournisseur : les tutoriels de l’époque de la v1 indiquant de « sélectionner OpenAI comme type » ne correspondent plus.

Cette page concerne la version de bureau de CherryHQ/cherry-studio (AGPL-3.0, compatible avec Windows, macOS et Linux). Lors de la vérification du 1er octobre 2026, le dépôt n’était pas archivé et la dernière version était la v2.1.4. L’application homonyme de l’App Store est un produit sans rapport provenant d’un autre développeur. Par ailleurs, la documentation officielle de Cherry Studio est en chinois simplifié ; lorsque l’interface passe en chinois traditionnel, « 提供商／服務商 » devient « 供應商 ». Ne confondez pas les appellations en consultant la documentation.

Configuration étape par étape

設定 → 模型供應商 → 新增供應商
  （對話框標題：新增自訂供應商）

  供應商名稱                 Kunavo
  API 金鑰                   sk-kn-...
  端點設定
    OpenAI Chat Completions  https://api.kunavo.com/v1
    Anthropic Messages       https://api.kunavo.com
  更多選項
    OpenAI Responses         https://api.kunavo.com/v1   （選填）
    影像產生基礎 URL           https://api.kunavo.com/v1   （選填）
    Google Gemini            留空

→ 儲存 → 在模型清單按「同步模型」→ 加入要用的模型 → 「檢查」

1. Ouvrez Paramètres → Fournisseurs de modèles, puis cliquez sur Ajouter un fournisseur. La boîte de dialogue qui s’affiche s’intitule « Ajouter un fournisseur personnalisé ». Pour les services de type Coding Plan, les comptes multiples ou la séparation par projet, vous pouvez utiliser en haut « Commencer à partir d’un modèle (facultatif) » pour créer un fournisseur à partir d’un modèle existant.
2. Renseignez le nom du fournisseur et la clé API.
3. La configuration des endpoints contient par défaut deux champs, OpenAI Chat Completions et Anthropic Messages ; vous devez en configurer au moins un pour le texte. Remplissez les deux si vous voulez que les modèles soient disponibles pour les agents et les fonctions utilisant le format Anthropic, en plus du chat.
4. Développez Plus d’options pour accéder à OpenAI Responses, Google Gemini, l’URL de base de génération d’images et l’URL de base de retouche d’images. Laissez vides les champs inutilisés.
5. Après l’enregistrement, vérifiez que ce fournisseur est activé. La documentation officielle précise qu’un fournisseur configuré mais non activé ne fait pas apparaître ses modèles dans le menu — c’est la cause la plus fréquente d’une « clé sans effet ».
6. Dans la liste des modèles, cliquez sur Synchroniser les modèles, ajoutez les modèles à utiliser, puis cliquez sur Vérifier pour en tester un.

Comment renseigner l’adresse : saisir uniquement l’adresse racine

D’après le code source de la v2.1.4, chaque champ attend une adresse racine : si aucun segment de version n’est présent, /v1 est ajouté automatiquement (sans duplication s’il existe déjà), puis le chemin fixe propre au champ est ajouté. Chaque champ affiche son « chemin de requête » en dessous : il s’agit de l’URL finale envoyée.

Deux erreurs fréquentes : premièrement, coller une URL complète contenant /chat/completions ou /messages, ce qui duplique le chemin et renvoie 404 ; deuxièmement, ajouter # à la fin. L’interface l’indique clairement : « Ajoutez # à la fin pour désactiver l’ajout automatique de la version de l’API. » Sur un endpoint standard, cela fait disparaître /v1.

Configurez-le au passage et réduisez la facture

Cherry Studio appelle des modèles en arrière-plan, en plus du chat. Selon l’interface, le modèle rapide sert « aux tâches simples telles que nommer les conversations et extraire des mots-clés pour les recherches », et l’invite précise de « choisir un modèle léger et d’éviter les modèles de raisonnement ». Placez-y un modèle bon marché pour éviter d’utiliser un modèle coûteux à chaque conversation. Le modèle de traduction se configure également séparément. Si vous interrogez plusieurs modèles à la fois, chacun reçoit une requête et est facturé séparément. Le montant affiché dans les statistiques d’utilisation de l’application est une estimation calculée à partir des tarifs publics ; il sera trop élevé avec une route bénéficiant d’une remise. Modifiez le prix unitaire dans les paramètres du modèle pour utiliser votre tarif réel. Pour plus de détails, consultez Cherry Studio API cost en anglais.

Points d’attention pour Kunavo et paiements depuis Taïwan

• Périmètre de la vérification : la configuration ci-dessus a été compilée à partir du code source et de la documentation officielle de Cherry Studio ; Kunavo n’a pas réellement connecté Cherry Studio à ses propres endpoints. Conservez la route que vous utilisez actuellement et testez celle-ci séparément.
• Chat et images uniquement : Kunavo ne propose pas de modèles d’embeddings. La recherche vectorielle de la base de connaissances doit donc utiliser un autre fournisseur ou un modèle d’embeddings local ; la documentation officielle précise qu’en l’absence de modèle d’embeddings, la base de connaissances continue de fonctionner avec une recherche par mots-clés BM25.
• Outils MCP : les outils ajoutés dans Paramètres → Serveurs MCP nécessitent un modèle prenant en charge les appels d’outils ; les modèles Claude et GPT ajoutés ci-dessus sont compatibles.
• Paiement : rechargement prépayé, facturation au token, sans frais mensuels. Rechargement minimum de $10, paiement via Stripe ; à Taïwan, les cartes de crédit (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay et Link sont disponibles ; JKOPay et LINE Pay ne figurent pas dans la liste des moyens disponibles. Consultez les informations de facturation ; une fois prêt, vous pouvez créer un compte et générer une clé. La page de configuration en anglais est le guide d’intégration de Cherry Studio.

Questions fréquentes

Vérification du 1er octobre 2026 : API GitHub (CherryHQ/cherry-studio, v2.1.4), chaînes de l’interface chinoise traditionnelle de la v2.1.4 (zh-tw.json), code source de l’écran d’ajout d’un fournisseur et documentation officielle de Cherry Studio. Kunavo n’a pas réellement exécuté Cherry Studio avec ses propres endpoints.