> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/en-us/advanced-basic/developer-tools/api-gateway.md).

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

<figure><img src="/files/290dd401e8f6214be1fd11c75b9871b1e8d42681" alt="API 网关设置中的运行状态、连接地址、端口和访问凭据"><figcaption><p>Before external programs connect, check the status and port; only provide the key to trusted local programs or a controlled network.</p></figcaption></figure>

## 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

{% stepper %}
{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.
{% endstep %}
{% endstepper %}

## 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

{% hint style="danger" %}
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.
{% endhint %}

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

<details>

<summary>What is the relationship between the API gateway and model services?</summary>

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.

</details>

<details>

<summary>What should I do if the port is normal but the client returns unauthorized?</summary>

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.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cherryai.com.cn/docs/en-us/advanced-basic/developer-tools/api-gateway.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.