Cherry Studio Omnirouter Setup: One Key | Part 2
Connect Cherry Studio to prepaid Omnirouter access. Configure the provider, enable a model, test a short prompt and avoid common endpoint mistakes.
By omnirouter
Practical AI with Cherry Studio and Omnirouter — Part 2 of 4.
This Cherry Studio Omnirouter setup guide connects your desktop chat workspace to prepaid model access. The goal is deliberately small: configure one provider, enable one model, and receive one useful text response. Leave tools, images and autonomous work for later.
Cherry Studio is the client. Omnirouter is the API service and billing layer. Installing the client does not give you prepaid credit, and adding an API key does not automatically configure every AI feature.
Before you start
Install Cherry Studio from its official project. In Omnirouter, create an account, open API keys and create a key. Copy the secret when it is shown; the Omnirouter docs explain that it is shown once and cannot be recovered later.
Add a modest amount of credit under Billing when you are ready to test. Usage is prepaid, with no subscription. Accounts begin with zero balance; a request without credit receives a 402. Do not paste your key into a conversation, source repository or screenshot.
Choose a current text model from the catalog. Copy its identifier exactly rather than turning its display name into a guessed ID. An available DeepSeek, GLM, Qwen, Kimi or MiniMax option is a sensible starting point to evaluate; availability and feature support still depend on the exact model.
Add a custom provider in Cherry Studio
The custom-provider guide describes adding a service under Settings and Model Services. Labels vary by release, but the configuration has four parts:
| Setting | What to use |
|---|---|
| Display name | Omnirouter |
| Provider or protocol type | The compatible chat-completions provider, rather than an unrelated vendor protocol |
| API key | Your own Omnirouter key; never a key copied from an article |
| Model | An exact identifier enabled for your account |
Enable the provider after configuring it. A saved provider and a provider available in Chat are not always the same thing.
Get the API address right
Omnirouter documents https://omnirouter.li/v1 as its API base and POST /v1/chat/completions as the text chat endpoint. Cherry's provider-address guidance recommends the root address for conventional compatible endpoints when the client appends the version and method path itself.
For that root-address field, start with https://omnirouter.li. If your version explicitly requests the complete API base instead, use https://omnirouter.li/v1. The important result is that the outgoing text request resolves to https://omnirouter.li/v1/chat/completions — with exactly one /v1 segment.
Do not randomly alternate trailing slashes, paste an endpoint into a base-address field, or assume every provider adapter builds URLs the same way. If an error shows a duplicated path such as /v1/v1/chat/completions, correct the address construction before changing models. Use your release's documentation and any endpoint preview it exposes.
These instructions combine the two products' published configuration guidance; they are not a claim that every Cherry release and every Omnirouter route has been end-to-end tested.
Add, enable and test one model
Use Manage or Get model list if your version offers discovery. Add the model you intend to use. If discovery does not list it, use manual model entry with the exact catalog identifier. Discovery alone does not prove that generation works.
Select the enabled provider and model in Chat. Start a fresh conversation with:
Reply with one sentence explaining what an API gateway does. Keep the answer under 30 words.
Check the answer, then inspect the corresponding usage record in your Omnirouter dashboard. This is a better first test than a large file upload or a long agent run: it isolates basic authentication, model selection and text generation without wasting context.
Troubleshoot in the right order
| Symptom | First check |
|---|---|
| 401 or authentication failure | Key copied correctly, provider enabled, correct service selected |
| 402 | Prepaid balance; add credit before retrying |
| 404 | Correct request path and exact enabled model ID |
| 503 or temporary capacity error | Stop rapid retries; try a tested alternative or contact support |
| Text works but tools or images fail | Feature-specific protocol and model support, not just the key |
Keep the error's request ID when available, along with the time and model ID. Send that information to Omnirouter support on Telegram. Never send the secret key.
Chat success is not Agent compatibility
Cherry's provider overview distinguishes provider types and states that its Agent workflow requires an Anthropic-compatible provider. A working chat-completions connection is therefore not sufficient evidence that Work or Agents will run through it.
Confirm the required protocol for your installed release and the gateway's supported route before configuring Agent access. Likewise, verify embeddings, vision, image generation and tools separately. Do not use this chat setup as proof of capabilities that have not been tested.
Keep an alternative ready
Our low-cost frontier routes depend on upstream capacity and can change in availability or quality. Evaluate a stable-backbone model for routine work and keep a second tested choice. Neither a desktop client nor provider failover creates an uptime guarantee.
Next: Part 3: documents, tools and bounded workflows. Review Part 1: workstation basics, or jump to Part 4: token costs.
Scope: Independent tutorial, not an official partnership. Menu names and URL handling are version-dependent. Illustrative cover artwork is not an application screenshot.