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].

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

The API key can call the model services you configured in Cherry Studio. If the key is leaked, first stop the gateway, then click [Regenerate] while stopped, and update all local clients.

• 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.