Docs · Integrations
Cherry Studio with TopxAI: first chat and endpoint setup
Connect a route-scoped TopxAI key to Cherry Studio, choose the right endpoint, and diagnose the first request without guessing URL suffixes.
Start with one model and a key whose route includes it. For example, create a Claude-route key for claude-sonnet-5-5. A single OpenAI-compatible connection does not make every model available to every key.
Choose the endpoint your version exposes
Cherry Studio has changed its provider settings between versions. Older releases show a single API Address field and add a version suffix. The current v2 source stores a separate base URL for each endpoint. Follow the field in your installed version and inspect the resulting request path if setup fails.
| Endpoint | Base URL for a v2 endpoint configuration | Example model |
|---|---|---|
| OpenAI Chat Completions | https://ai.topxea.com/v1 |
claude-sonnet-5-5 on a Claude key; gpt-6.1-sol on a GPT key |
| OpenAI Responses | https://ai.topxea.com/v1 |
gpt-6.1-sol, grok-4.7 on their matching routes |
| Anthropic Messages | https://ai.topxea.com |
claude-sonnet-5-5, claude-opus-5-5 |
The resulting POST paths must be /v1/chat/completions, /v1/responses, or /v1/messages, respectively. Select Chat Completions for GLM. Kimi K3.1 Pro also accepts stateless Responses requests with the full conversation in input; server-side conversation persistence has not been verified. Jev uses a separate protocol and is outside this setup.
In older versions that explicitly append /v1, start with https://ai.topxea.com in the single API Address field. Do not apply that rule blindly to v2 endpoint fields. An address containing /v1 is not inherently wrong: the final request path is what matters. Avoid the advanced # endpoint override for this first setup.
Complete the first chat
- Open Settings → Model Provider, add a custom provider and name it
TopxAI. Choose an OpenAI-compatible Chat Completions connection, or Anthropic for a native Claude connection. Labels vary by version. - Set the matching address above and enter your TopxAI key locally. Keep screenshots and exported settings free of credentials.
- Fetch the model list or manually add a model permitted by that key. Fetching
/v1/modelschecks discovery, not generation. - Select that provider and model in a new chat. Send
Say hello in one sentence.Set a small output limit if the client exposes one. A connectivity check that generates text also consumes balance. - Confirm a response, then open TopxAI Usage to verify the model, route and charge. Add other models only after this works.
New TopxAI accounts start with an empty balance: add credit in Wallet first. Every top-up earns a bonus, and the first one an extra 10%. The key's own quota must also cover the request reservation.
Diagnose the boundary that failed
| Symptom | Check next |
|---|---|
| 401 | Correct key, no surrounding whitespace, correct authentication type |
| 402 with positive balance | Key quota and requested output limit; the initial reservation can exceed the available balance |
| 403 | The key's route and model limits; choosing a model in Cherry does not expand them |
404 or duplicated /v1/v1 |
Final request path and the version-specific address field |
| Models load but chat fails | Selected endpoint, model permissions and response format |
| Curl works but the client fails | Extra tools, attachments, reasoning options and automatic retries; start with plain text |
| Timeout after submission | Check Usage and the request ID before repeating; do not assume the first request never ran |
Image generation is a separate configuration and route. A working text-model key does not establish that image requests are enabled.
Verification scope and sources
This guide was checked against Cherry Studio's endpoint resolver, base URL selection and provider registry on September 19, 2026. It is a source-reviewed custom-provider recipe, not a claim that TopxAI is an official built-in preset or that every desktop version was tested end to end.
See Connect your SDK for a minimal comparison request and Common error responses for error details.
Models: claude-sonnet-5-5, gpt-6.1-sol · Models & pricing
Related
- Connect your SDK
- Create an API key and choose a route
- The model works in curl but not in my tool
- Common error responses
- ChatBox with TopxAI: a custom provider
- LobeChat with TopxAI: the OpenAI proxy address
- Claude Sonnet 5.5 API pricing
- GPT-6.1 Sol API pricing
Previous: LobeChat with TopxAI: the OpenAI proxy address · Next: ChatBox with TopxAI: a custom provider
Other languages: 简体中文