Cherry Studio API configuration: add a custom provider, URL, and model

To configure your own API in Cherry Studio, go to 設定 → 模型供應商 → 新增供應商: enter your API key, then enter a root URL in each of the OpenAI and Anthropic fields under “端點設定.” Save, then click “同步模型” to fetch the models, and use “檢查” to verify.This guide follows v2.1.4, released on September 30, 2026, and uses menu names exactly as they appear in Cherry Studio’s Traditional Chinese interface. Version 2 overhauled the 新增供應商 screen, so v1-era guides that say to “select OpenAI as the type” no longer match.

This page covers the desktop edition of CherryHQ/cherry-studio (AGPL-3.0; supports Windows, macOS, and Linux). As of October 1, 2026, the repository was not archived and the latest version was v2.1.4. The App Store app with the same name is an unrelated product from a different developer. Also, Cherry Studio’s official documentation is in Simplified Chinese. When you switch the interface to Traditional Chinese, “提供商／服務商” appears as “供應商,” so keep that difference in mind when comparing the documentation.

Set it up step by step

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

  供應商名稱                 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. Open Settings → Model Providers and click Add Provider. The dialog that appears is titled “Add Custom Provider.” For Coding Plan services, multiple accounts, or separate projects, you can use “Start from Preset (Optional)” at the top to create one from an existing preset.
2. Enter the Provider Name and API Key.
3. Endpoint Settings includes OpenAI Chat Completions and Anthropic Messages fields by default. You must configure at least one text endpoint. Fill in both to make models available for Agents and features that use Anthropic format, as well as chat.
4. Expand More Options to see OpenAI Responses, Google Gemini, Image Generation Base URL, and Image Editing Base URL. Leave any fields you don’t need blank.
5. After saving, confirm that the provider is enabled. The official documentation says that models from a configured but disabled provider won’t appear in the menu — this is the most common reason a “key doesn’t work.”
6. In the model list, click Sync Models, add the models you want to use, then click Check to test one.

How to enter URLs: use only the root URL

According to the v2.1.4 source code, each field expects a root URL: if there is no version segment, /v1 is added automatically; if one is already present, it is not added. The fixed path for that field is then appended. Each field displays the “Request Path” underneath; this is the final URL that will be sent.

Two common mistakes: first, pasting a complete URL that includes /chat/completions or /messages duplicates the path and returns a 404; second, adding # at the end. The interface tip is clear: “Add # at the end to disable automatic API version appending.” On a standard endpoint, adding it removes /v1.

Set this up too, and trim your bill

Cherry Studio calls models in the background as well as for chat. According to the interface description, the Fast Model is “used for simple tasks such as naming conversations and extracting search keywords.” Its hint also says, “Please select a lightweight model and avoid using a reasoning model.” Set an inexpensive model here so the more expensive one isn’t used for every conversation. The Translation Model is configured separately. If you select multiple models to answer a prompt at once, each model receives a separate request and incurs a separate charge. The amounts shown in the app’s usage statistics are estimates based on public prices, so they will appear higher when you use a discounted route. Update the unit prices in the model settings to match your actual prices. For more details, see Cherry Studio API cost in English.

Using Kunavo: notes and payment in Taiwan

• Verification scope: The setup above is based on Cherry Studio’s source code and official documentation. Kunavo has not tested Cherry Studio with its own endpoints. Keep your current working setup and try this route alongside it.
• Chat and images only: Kunavo does not offer an embedding model. Use another provider or a local embedding model for vector search in the knowledge base. The official documentation says the knowledge base can still use BM25 keyword search without an embedding model.
• MCP tools: Tools added under Settings → MCP Servers require a model that supports tool calling. The Claude and GPT models added above support it.
• Payment: Prepaid top-ups, charged per token, with no monthly fee. Minimum top-up $10, checkout through Stripe, with Taiwanese cards (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay, and Link available in Taiwan; JKoPay and LINE Pay are not on the available list. See Billing details; when ready, create an account and generate a key. The English setup page is Cherry Studio integration guide.

Frequently asked questions

Verified on October 1, 2026: GitHub API (CherryHQ/cherry-studio, v2.1.4), v2.1.4 Traditional Chinese interface strings (zh-tw.json) and source code for the Add Provider screen, and Cherry Studio’s official documentation. Kunavo has not tested its own endpoints with Cherry Studio.