Connect GPT and third-party APIs to Cherry Studio
Choose the right protocol, enter the provider root URL, add the exact model ID, and verify one small request before expanding the setup.
Searching for how to connect GPT to Cherry Studio usually means you need a working provider configuration, not a feature tour. The important fields are the protocol, API key, base URL, and exact model ID.
The short path is:
Settings → Model Service → choose or add a provider → enter the credential and API URL → fetch or add a model → enable the provider → run a health check.
Cherry Studio has built-in providers for services such as OpenAI, Anthropic, Google Gemini, DeepSeek, Moonshot, Ollama, and LM Studio. A gateway or self-hosted service can be added through a custom provider when it exposes an OpenAI-compatible, Anthropic, or Gemini endpoint. See the official provider settings guide for the current UI names.
What you need before opening Cherry Studio
Prepare four values from the service you want to use:
| Value | What it means |
|---|---|
| Protocol | OpenAI-compatible, Anthropic Messages, Gemini, or the provider's documented format |
| API key | The credential used to authenticate the request |
| Base URL | The root API address, unless the provider explicitly requires a full endpoint |
| Model ID | The exact string accepted by the upstream API |
Do not use a web-chat password as an API key. A ChatGPT subscription, an API account, and a third-party gateway are separate access paths. Use the credential and endpoint documented by the service you selected.
Connect GPT in five steps
1. Open Model Service
Start Cherry Studio and open Settings → Model Service. Choose the built-in OpenAI provider when you are calling OpenAI directly. For a gateway, aggregator, or private deployment, choose Add provider and create a separate custom entry.
The provider is selected by its protocol, not by the word GPT in the model name. A GPT-labeled model behind an Anthropic-compatible gateway still needs the Anthropic protocol profile.
2. Fill the provider fields
Use the provider's documentation for each field:
| Cherry Studio field | What to enter | Avoid |
|---|---|---|
| Provider name | A label you will recognize later | Reusing one label for unrelated endpoints |
| API key | The key value only | Extra spaces, quotes, or Bearer |
| API type | The protocol the endpoint actually implements | Guessing from the model's marketing name |
| API address | The documented root URL or required full URL | A dashboard URL or a duplicated path |
For a conventional OpenAI-compatible service, Cherry Studio generally expects the root address and appends the version and request path. If a provider shows both https://api.example.com and https://api.example.com/v1/chat/completions, the first is the normal base URL. Do not add /v1 twice. Use a full path only when the provider explicitly says to do so.
The custom provider guide covers extra endpoints, manual model entry, and vLLM-style local services.
3. Fetch or add the model
Click Get model list. If the endpoint exposes model discovery, add the model with the + button. The returned ID is authoritative: keep dates, vendor prefixes, hyphens, and version suffixes exactly as shown.
If the provider does not expose a model list, add the model manually. A successful provider save does not automatically make a model available in the chat picker. The model must be added and the provider switch must be enabled.
4. Check one short request
Use Check with the model you just added, then send a minimal prompt:
Reply with exactly: connection successful
This separates authentication and routing problems from vision, tools, long-context, or agent capability problems. Confirm the call in the provider's usage page when one is available.
5. Add advanced capabilities one at a time
After plain text works, test streaming, images, tools, or reasoning parameters one by one. A successful chat response only proves that the basic text route works; it does not prove that the model or protocol supports every feature Cherry Studio exposes.
Connecting other third-party APIs
OpenAI-compatible gateways
Use Custom provider → OpenAI when the gateway documents OpenAI Chat Completions or another OpenAI-compatible surface. This is the usual path for aggregators, private gateways, vLLM, and many hosted open models.
Multi-protocol gateways
NewAPI-style gateways can expose OpenAI Chat, OpenAI Responses, Anthropic Messages, and Gemini routes from one root address. Cherry Studio's NewAPI instructions explain that the client selects the version path for the chosen protocol. Use the NewAPI preset when the gateway follows that contract; use a custom provider when it has a documented path or model-discovery variation.
Ollama, LM Studio, and vLLM
Select the matching local provider, or use a custom OpenAI provider when the local server exposes an OpenAI-compatible API. Enter the model name that the local server actually loaded. Local execution can reduce data exposure, but local models still differ in vision, tools, context length, and reasoning support.
When the model list is empty
Work through these checks in order:
- Confirm that the service implements a model-list endpoint. Some APIs only accept a manually supplied model ID.
- Remove duplicated path segments. A root URL that already contains
/v1can fail when Cherry Studio appends another/v1. - Check that you used the API address, not the provider's management dashboard address.
- Copy the exact model ID returned by the provider. Display names and API IDs are not interchangeable.
- Make sure the provider is enabled. A disabled provider hides its models from the picker.
Common errors
| Error | Likely cause | First check |
|---|---|---|
401 Unauthorized | Invalid, expired, or incorrectly formatted key | Re-copy the key and confirm the protocol profile |
403 Forbidden | Account, project, balance, or key limit | Check provider permissions and quota |
404 Not Found | Wrong root URL, duplicated version path, or protocol mismatch | Restore the documented base URL |
400 Bad Request | Unsupported parameter or request shape | Remove custom parameters and retry plain text |
model not found | Wrong ID or model not added in Cherry Studio | Copy the exact upstream model ID |
| Text works but images/tools fail | Model or protocol lacks that capability | Check the capability list and route |
| Timeout | Provider latency, network issue, or oversized request | Retry with a short prompt and one model |
Change one variable at a time. Start with one provider, one model, and one short request; only then add multiple models or tools.
Comparing multiple models
Cherry Studio lets you switch models in the conversation picker and send the same prompt to multiple selected models. Each selection creates an independent request. It is useful for comparison, but it is not an automatic vote or quality guarantee; request count, cost, and data exposure increase with each selected model. The official comparison guide recommends writing explicit evaluation criteria instead of asking which answer is simply “best.”
Use OmniaKey as one provider
If you do not want to maintain separate entry points for GPT, Claude, Gemini, and other models, configure OmniaKey as a custom OpenAI-compatible provider in Cherry Studio.
- Create a dedicated OmniaKey API key and set a suitable key limit on the API Keys page.
- Open Settings → Model Service → Add provider in Cherry Studio.
- Choose the OpenAI-compatible type and enter the base URL and key from the OmniaKey quick start.
- Fetch the model list, or add an exact ID from the live model catalog.
- Enable the provider, run a short check, and confirm the request in Usage.
The current OmniaKey catalog includes Claude, GPT, Gemini, and Grok, along with additional model families. IDs and capabilities are dynamic, so use the live catalog rather than an old tutorial. An OpenAI-compatible route does not make every provider-specific feature identical; check the model and protocol capability before enabling vision or tools.
FAQ
Can Cherry Studio use any API I find?
Only when the service exposes a protocol Cherry Studio supports. An arbitrary URL without a documented request format, authentication method, and model ID is not enough.
Should I enter a root URL or /chat/completions?
Follow the provider documentation. Conventional providers normally use the root URL and let Cherry Studio append the request path; use a full endpoint only when the provider explicitly requires it.
Why can I chat but not use tools or images?
Basic text success does not prove that the selected model, protocol, and client route support tools or vision. Check each capability separately.
Is a ChatGPT web subscription an API key?
No. Cherry Studio needs a provider API credential or a compatible gateway credential. Web login details should never be pasted into the API key field.
Sources and freshness
This guide uses Cherry Studio's current provider, custom-provider, OpenAI, NewAPI, and multi-model documentation, plus OmniaKey's current API and model documentation. Technical values such as model IDs, provider capabilities, and routes can change; verify them at the time of configuration.