Cherry Studio API Settings: Custom Providers, Endpoints, and Models

To configure the API in Cherry Studio, go to Settings → Model Provider → Add Provider. Enter the API Key and put the root URL in the OpenAI and Anthropic fields under Endpoint settings, then save, fetch models with “Sync models,” and verify one with “Check.” One thing to know first: Cherry Studio has no Korean UI, so the menu labels are given in their original English. This page is based on v2.1.4, released on September 30, 2026. The provider-add screen changed substantially in v2, so instructions from the v1 era that say “Type: OpenAI” no longer match the interface.

This covers the desktop version of CherryHQ/cherry-studio (AGPL-3.0, Windows, macOS, and Linux). As of October 1, 2026, the repository was not archived and the latest version is v2.1.4. The App Store app with the same name is unrelated and made by a different developer. The built-in UI has 13 languages and no Korean (based on the v2.1.4 UI translation files), so these instructions assume the English UI.

Step-by-step setup

Settings → Model Provider → Add Provider
  (대화상자 제목: Add Custom Provider)

  Provider Name       Kunavo
  API Key             sk-kn-...
  Endpoint settings
    OpenAI            https://api.kunavo.com/v1
    Anthropic         https://api.kunavo.com
  More options
    OpenAI Responses            https://api.kunavo.com/v1   (선택)
    Image Generation Base URL   https://api.kunavo.com/v1   (선택)
    Gemini                      비워 둠

→ Save → 모델 목록에서 "Sync models" → 쓸 모델 추가 → "Check"

1. In Settings → Model Provider, select Add Provider. The dialog that opens is titled “Add Custom Provider.” If you need a Coding Plan service, multiple accounts, or project separation, you can also start from an existing preset using “Start from a preset (optional)” at the top.
2. Enter the Provider Name and API Key.
3. Endpoint settings has two fields by default: OpenAI and Anthropic. At least one text endpoint is required (if both are empty, the error is “Configure at least one text endpoint”). Filling in both fields lets you choose the models for chat, as well as for Agent and other features that use Anthropic format.
4. Expand More options to see the OpenAI Responses, Gemini, Image Generation Base URL, and Image Edit Base URL fields. Leave any unused fields empty.
5. After saving, make sure the provider is enabled. According to the official documentation, models from a configured but disabled provider do not appear in the selection list. This is the most common reason a “key doesn't work.”
6. In the model list, use Sync models to fetch models, add the ones you want to use, and verify one with Check.

How to enter the URL: use the root URL only

According to the v2.1.4 source, enter the root URL in each field. If the version part is missing, /v1 is appended automatically (and not appended if it is already there), then the fixed path for that field is added. The final URL is shown as “Request path” below each field, so check it before saving.

There are two common mistakes. Pasting a full URL that includes /chat/completions or /messages causes the path to be appended twice, resulting in a 404. A trailing # disables automatic version appending, as the UI says: “Add # at the end to disable the automatically appended API version.” Adding it to a standard endpoint leaves out /v1. The quickest way to check the URL and key is to run the command below.

curl https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

Basic model settings to save on costs

Cherry Studio calls models in the background as well as for chat. Quick Model, as described in the UI, is used for “simple tasks such as naming conversations and extracting search keywords”; its guidance also says to “choose a lightweight model and avoid reasoning models.” Assigning a low-cost model here means an expensive model is not used every time you chat. Set a separate Translate Model too. If you select several models and ask them a question at once, each model gets a separate request and is billed separately. The app's usage statistics show an estimate based on public prices, so they overstate costs for discounted routes. Change the unit prices in model settings to match your actual rates. See the English page Cherry Studio API cost for details.

Notes on using Kunavo and payment

• Verification scope: This setup guide is based on the Cherry Studio source and official documentation. Kunavo has not verified it by connecting Cherry Studio to its own endpoint and running it. Keep your current setup unchanged while testing.
• Chat and images only: Kunavo has no embedding model, so vector search in the knowledge base requires another provider or a local embedding model. The official documentation says the knowledge base can work with BM25 keyword search even without an embedding model.
• MCP tools: Tools added in Settings → MCP Servers require a model that supports tool calling. The Claude and GPT models added above do.
• Payment: Prepaid top-ups with no monthly fee; the balance is deducted per token. The minimum top-up is $10, and Stripe Checkout supports cards (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay, and Link. When checkout is displayed in Korean won, KakaoPay, Naver Pay, PAYCO, Samsung Pay, and domestic cards with international payments blocked are also offered as options (added October 3, 2026; no payments have yet been made using these methods). Amounts are set in dollars, and Stripe converts the displayed amount to Korean won; the exchange rate includes a 2–4% conversion fee paid by the payer. Toss Pay is not available. See payment details and create an account to issue a key. The English setup page is Cherry Studio integration guide.

Frequently asked questions

Verified October 1, 2026: GitHub API (CherryHQ/cherry-studio, v2.1.4), the v2.1.4 UI translation file list and English UI strings (en-us.json), the provider-add screen source, and Cherry Studio's official documentation. Kunavo has not run Cherry Studio against its own endpoint.