For the complete documentation index, see llms.txt. This page is also available as Markdown.

API gateway

The API gateway provides the model capabilities configured in Cherry Studio to local programs through an OpenAI- and Anthropic-compatible HTTP API. It is also an internal service required for Agent operation.

Path: [Settings] → [API Gateway].

API 网关设置中的运行状态、连接地址、端口和访问凭据
Before external programs connect, check the status and port; only provide the key to trusted local programs or a controlled network.

Agent use vs external calling

  • Use only Cherry Studio Agent: just follow the app prompt [Enable and Start]; you do not need to copy the URL or key to other programs;

  • For local programs that need to call Cherry Studio: start the gateway, copy the URL and API key, and choose a compatible interface according to the API documentation;

  • To allow other devices to access it: this will expand the exposure scope; you need to verify network listening, firewalls, and access control yourself; it is not recommended to open it without security measures.

Start and connect

1

1. Check the port

You can change the port when the gateway is stopped. Choose a port not occupied by other programs; if there is a port conflict, the service cannot start properly.

2

2. Start the gateway

Click [Start]. After the status changes to [Running], the page will show an available URL and provide an [API Documentation] entry.

3

3. Configure authorization

Use by external programs Authorization: Bearer <API key>. The page can directly copy the authorization header; do not write the key into code repositories or screenshots.

4

4. Verify with the minimum request

First request the model list or send a short text according to the API documentation, then connect to the full application. When errors occur, record the HTTP status and response, and do not expose the full authorization header.

Use case: Let a local script call the model

First confirm in [Settings] → [Model Service] that the model can chat normally, then start the API gateway. The script only saves the local gateway address and key, first request the model list, then send a short sentence. Before integrating the full program, confirm that the client supports an OpenAI- or Anthropic-compatible interface.

Configuration
Suggested starting point
Effect
Notes

Listening scope

Local only

Reduce network exposure

Do not directly open it to the LAN or public Internet just for convenience in debugging

API key

Store separately for the current gateway

Verify client requests

Do not write into repositories, screenshots, or shared logs

Verify requests

First check the model list and short text

Verify connection and generation separately

When it fails, record the status code, not the full key

Completion criteria

The gateway shows [Running]; the model list can be read; the short text request succeeds; after stopping the gateway, the client can no longer continue calling.

Safe operations

  • When the gateway is running, the port and key remain read-only; stop it before making changes;

  • Do not display the key in public repositories, Issues, logs, or tutorial screenshots;

  • Only save the key for programs that need to call it;

  • Usage and charges are still generated by the actual model provider; you can view Cherry Studio records under [Settings] → [Usage Statistics].

What is the relationship between the API gateway and model services?

Model services store upstream provider connections; the API gateway converts these capabilities into compatible interfaces. The gateway itself does not provide models, so you still need at least one available provider and model.

What should I do if the port is normal but the client returns unauthorized?

Confirm the request header is Authorization: Bearer ..., with no extra quotation marks or spaces, and check whether the key used by the client is still the current value on the page.

Last updated

Was this helpful?