Add Router One to Cherry Studio as a custom provider

Before you add the provider: what each Cherry feature needs

Cherry Studio sends each model's requests to the endpoint that model is set to use, so decide which endpoints you need before you fill in the form. Most people need only OpenAI, which serves every chat model. Create a key for Cherry Studio alone in Dashboard → API Keys with Create Key and give it a maxSpend cap. Cherry can rotate several comma-separated keys on one provider, but a single dedicated key keeps the spending cap and the Logs filter in one place.

Add Router One as a custom provider in Cherry Studio

Open Settings → Model Provider (设置 → 模型服务 in the Chinese interface) and click Add Provider below the provider list; the Add Custom Provider drawer opens. Enter Router One as Provider Name and paste the dedicated key into API Key. Under Endpoint settings, enter the host root https://api.router.one in the OpenAI field and in the Anthropic field. Once a root URL is in a field, Cherry shows the Request path it will call: https://api.router.one/v1/chat/completions and https://api.router.one/v1/messages. Under More options, add OpenAI Responses with the same host root. Image Generation Base URL can stay blank, in which case Cherry uses the default chat endpoint's base URL, and Gemini stays empty. Keep OpenAI as the default endpoint (Set as default), so models you add use Chat Completions, which serves every chat model. Click Add. With a key entered, Cherry 2.1.3 then opens a Choose models step: select the chat IDs you want and click Add selected models; Cherry adds them, sends one check request to one of them (billed, and shown in Dashboard → Logs) and switches the provider on. If you choose Skip instead, check that the switch at the top right of the provider page is on: until it is on, the provider's models appear in no model picker. The finished endpoint settings look like this:

OpenAI / Anthropic / OpenAI Responses Base URL

https://api.router.one

# Cherry Studio：设置 → 模型服务 → 添加服务商 → 添加自定义提供商
# Cherry Studio: Settings → Model Provider → Add Provider → Add Custom Provider
提供商名称 / Provider Name:   Router One
API 密钥 / API Key:           sk-your-router-one-key

# 端点设置 / Endpoint settings
OpenAI:              https://api.router.one   → …/v1/chat/completions（设为默认 / Set as default）
Anthropic:           https://api.router.one   → …/v1/messages
# 更多设置 / More options
OpenAI Responses:    https://api.router.one   → …/v1/responses
图像生成 Base URL / Image Generation Base URL:   留空 / blank（使用默认端点 / uses the default endpoint）
Gemini:              留空 / leave empty

Which endpoint each Router One model ID uses

Cherry adds the version and the path itself: it appends /v1 to a root URL that has no version segment, then /chat/completions, /responses, /messages or /images/generations for the endpoint type. Router One serves every chat model on Chat Completions, Claude-family and DeepSeek V4 IDs on Anthropic Messages, and GPT-family, DeepSeek V4 and Grok chat IDs natively on Responses, so the endpoint follows the model ID. A Claude ID sent to OpenAI Responses is rejected with HTTP 400 before any model runs (model '<id>' must be called via /v1/messages or /v1/chat/completions), and a chat ID outside the Claude and DeepSeek families sent to Anthropic gets 400 with must be called via /v1/chat/completions. Cherry sends the key both as Authorization: Bearer and as X-Api-Key, and Router One accepts either.

Host root or /v1? Why this guide enters the host root

Cherry's own docs say to enter only the root address and let Cherry add the rest, and that form works in every version. In Cherry Studio 1.7.0 and later, an address that already contains a version segment such as /v1 is left as it is, so https://api.router.one/v1 also works there. Versions up to 1.6.7 (released 2025-11-04) appended /v1/ to any address that did not end with a slash, so a /v1 address became /v1/v1/… and returned 404; Router One's 404 message for that path says the client appends /v1 by itself. Ending an address with # stops Cherry from adding the version segment, per its interface hint and source; Router One does not need it.

Model settings: chat protocol, context window and capabilities

Sync models requests GET /v1/models with your key and lists the models there for you to add, and + (Add model manually) adds an ID by hand. The list is the whole catalog, including image-generation models and IDs whose model page lists no capabilities, so add only the chat models you will use. Cherry shows each model's actual API ID under its name, and it must match /models exactly, for example anthropic/claude-sonnet-5 or openai/gpt-5.6-sol. For a custom provider, each model has a Model purpose (Chat, Image generation or Image editing) and, for chat, a Chat protocol chosen from the endpoints you configured; new models start on the provider's default endpoint. Move a Claude or DeepSeek V4 model to Anthropic, or a GPT model to OpenAI Responses, only when you want that wire format. Set Context window from the model page as a whole number, rounded down (1.05M becomes 1000000 for anthropic/claude-sonnet-5, and deepseek-v4.1-flash takes 1000000), leave Max output tokens empty unless you want a cap of your own, and tick capabilities such as image input or tool calling only when the model page lists them.

Cherry Agent, knowledge bases and image generation

Cherry's provider docs mark the Anthropic-compatible type as the one Cherry Agent requires, so for an agent use the Anthropic endpoint with a Claude-family or DeepSeek V4 ID whose page lists tool calling, such as anthropic/claude-sonnet-5 or deepseek-v4.1-flash. A knowledge base needs an embedding model to index documents, and Router One serves no embeddings endpoint, so choose another provider's embedding model there while chat stays on Router One. For images, add an image model such as gpt-image-2 with the purpose Image generation; Cherry calls /v1/images/generations on the Image Generation Base URL, or on the default endpoint's base URL when that field is blank. Image models are priced per image, as shown on each model page, and each generation appears in Logs with its cost.

Check the connection, then read Logs

Check sends a real request to the model you pick, so it is billed and appears in Dashboard → Logs; Cherry's own warning notes that checking all models at once sends many real requests. If a check fails, match the status: 401 means the key is missing or wrong; 404 usually means the base URL and the endpoint do not fit, for example a /v1 address on a version older than 1.7.0; 400 with must be called via means that endpoint does not serve the model's ID, so move the model to the endpoint the message names; 402 means the wallet balance or the key's maxSpend is used up. Each record in Logs shows the model, tokens, cost, status, total time and, for streamed requests that produced output, time to first token (TTFT). Leave the provider's API settings, such as developer messages or service_tier, at their defaults for the first test.

Which model ID should Cherry Studio send?

Copy the exact model ID from /models, preserving case, hyphens, and version suffixes; do not substitute a display name. Open its detail page and match the supported API endpoints, context window, and capabilities such as tool calling to the provider and features selected in Cherry Studio. A catalog listing does not mean the client can use every feature of that model. Give each client or application a dedicated API key with a maxSpend cap.

Which API protocol is Cherry Studio using?

OpenAI-compatible describes an interface format; it does not make Chat Completions (/v1/chat/completions), Responses (/v1/responses), and Anthropic Messages (/v1/messages) interchangeable. Check the installed client version, provider configuration, and actual request path against the model detail page and API compatibility fact sheet. A successful plain-text chat does not establish support for hosted tools, conversation state, or file-editing features.

Verify the Cherry Studio call in your request trace

Send a simple text request from Cherry Studio, then match its trace in Dashboard → Logs by time, model, and request_id: tokens, cost, latency, and status. Next, test streaming, tool calls, and multi-turn history separately. For failures, retain the actual request path, full error message, and request_id. If there is no matching log, check client configuration and connectivity before attributing the error to the gateway or upstream.

FAQ