Connect Cherry Studio to a Custom AI API: Full Setup Guide

Cherry Studio lets you run many model providers from one desktop client, which makes it a natural front end for an API gateway. Connecting a custom AI API takes exactly three values — endpoint, API key, and model ID — yet most failed setups come from the same three mistakes: entering too much of the endpoint path, pasting an incomplete key, or keeping a stale model entry. This guide walks the full setup against Zivv's OpenAI-compatible endpoint, then covers testing and the two errors you are most likely to meet.

Before You Open Cherry Studio

Get three things ready:

1. A Zivv account, registered and topped up (minimum ¥10, at ¥1 = $1)
2. An API key from the console's API Keys page
3. A model chosen from Model Hub

Name the key after the client and device, for example "Cherry Studio - Laptop." When usage shows up in the console you will know exactly where it came from, and if the laptop is ever lost you revoke one key without touching your server, Claude Code, or Codex credentials.

Step 1: Add an OpenAI-Compatible Provider

In Cherry Studio's model service settings, create a custom OpenAI-compatible provider and enter three values:

The endpoint stops at /v1. Do not enter /chat/completions — Cherry Studio appends the operation path itself, and entering it manually produces a doubled path and a 404.

Step 2: Add and Select Models

If Cherry Studio can fetch the model list automatically, refresh it and pick from the results. If you add a model manually, the name must match the API id character for character — claude-sonnet-5, not "Claude Sonnet."

You can verify what IDs are available before touching the client:

curl https://zivv.pro/v1/models \
  -H "Authorization: Bearer sk-your-key"

A practical mapping from workload to model family:

Catalogs change over time, so treat Model Hub as the source of truth for names and prices rather than any fixed recommendation in a setup guide.

Step 3: Run a Connection Test First

Use Cherry Studio's built-in connection test before enabling anything advanced. If your version has no test button, open a new conversation and send the smallest possible message: "Reply OK."

Only after that first minimal exchange succeeds should you turn on web access, tool calls, images, or long context. The order matters for debugging: a failure before the minimal test is a configuration problem; a failure after it is a feature or capability mismatch. Mixing the two is how setups end up being reinstalled for no reason.

You can also prove the full chain outside the client entirely:

curl https://zivv.pro/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"Reply OK"}]}'

If this works but Cherry Studio fails, the problem is inside the client's provider profile — not the key, not the platform.

Fixing a 401 in Cherry Studio

A 401 means authentication was rejected. In order of likelihood:

• Re-copy the complete key via a plain-text editor and strip surrounding spaces
• Confirm you pasted an API key, not your account login password
• Delete old keys lingering in duplicate provider profiles
• Fully quit and restart Cherry Studio so the new key is actually loaded

The 401 troubleshooting checklist covers the complete sequence, including how to tell a key problem from a client problem in one curl call.

Fixing a 404 or Missing Model

Check the two usual suspects first:

1. The endpoint is exactly https://zivv.pro/v1 — nothing more, nothing less
2. The model ID was copied from the current live list, not typed from memory

If both are right and the error persists, confirm the key's group permits that model and delete any cached model entries in the client. The 404 model not found guide has the full checklist and a minimal reproduction request.

Keys Across Devices and Teams

One key per device beats one shared key every time:

• Usage in the console identifies the device at a glance
• A lost or compromised device means revoking one key, not rotating everything
• Each device can carry its own spending limit
• Server, Claude Code, and Codex keys stay untouched

The same logic scales to teams: issue one key per member and manage budgets centrally through Zivv's team features, which provide a shared balance, independent member keys, and usage analytics by member, key, and model. Never drop a shared account key into a group chat or a shared document.

Key Safety

Cherry Studio is a local client, but the key inside it is still a credential:

• Do not screenshot a complete key
• Do not publish exported configuration files that embed it
• Do not commit it to a Git repository
• On any suspicion of exposure, revoke and re-create immediately

FAQ

Q: Can I use Claude, GPT, and Gemini models in Cherry Studio with one key? A: Yes. Through Zivv's OpenAI-compatible endpoint, one sk- key reaches 100+ models across all three families. Add each model ID under the same provider profile.

Q: The connection test passes but a specific model errors. Why? A: The endpoint and key are fine; the model entry is not. Either the ID does not match the live list exactly, or your key's group does not include that model — see the 404 guide above.

Q: Should Cherry Studio and Claude Code share one key? A: They can, but separate keys are better practice: per-tool usage stays attributable, and revoking one client never interrupts the other.

Q: Does Cherry Studio need a special protocol for Claude models? A: No. Through the gateway, Claude models are served over the OpenAI-compatible protocol at /v1, so Cherry Studio treats them like any other OpenAI-style model.

Wrap-Up

A complete setup is five checkmarks: a dedicated named key, the endpoint https://zivv.pro/v1, an exact current model ID, one successful minimal conversation, and a matching entry in the console's usage log. From there, adding more models is a copy-paste. If you have not created your gateway account yet, register and you will be sending your first Cherry Studio message within minutes; client-by-client details live in the Zivv documentation.