> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 在 Cherry Studio 中使用 BeatAPI

> 把 BeatAPI 添加为 Cherry Studio 的 OpenAI 类型服务商，在一个桌面程序里使用账户下的全部文本模型。

# 在 Cherry Studio 中使用 BeatAPI

Cherry Studio 是一个可以并列接入多个服务商的桌面对话客户端。把 BeatAPI 添加为 OpenAI 类型的服务商之后，账户下所有文本模型都会出现在它的模型选择器里。

## 准备工作

1. **已安装 Cherry Studio** —— 从[官网](https://cherry-ai.com/)下载。
2. **一把 BeatAPI 密钥** —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)创建。

## 第一步：打开服务商设置

点右上角设置图标，或按 `Ctrl+,`（macOS 为 `Cmd+,`），然后在左侧菜单选择 **模型服务**。

## 第二步：添加 BeatAPI 服务商

在模型服务页面底部点 **+ 添加**，填写：

| 字段    | 值         |
| ----- | --------- |
| 服务商名称 | `BeatAPI` |
| 服务商类型 | `OpenAI`  |

点**确定**。然后在右侧配置区填写：

| 字段     | 值                        |
| ------ | ------------------------ |
| API 密钥 | 你的 BeatAPI 密钥            |
| API 地址 | `https://api.beatapi.io` |

> **Note**
>
> 这里填 `https://api.beatapi.io`，**不要**带 `/v1`，后面也不加任何路径。Cherry Studio 会自己拼上 `/v1/chat/completions`；你再加一个 `/v1` 就变成了 `/v1/v1/chat/completions`，每条消息都会 404。

确认右上角 BeatAPI 服务商的开关是**打开**状态（绿色），再用**检测**按钮验证一下连通，然后再添加模型。

## 第三步：添加模型

服务商配好后，在**模型**区域点**管理**打开模型选择窗口，搜索编号后点 **+** 添加。

| 模型编号                   | 适用场景                          |
| ---------------------- | ----------------------------- |
| `claude-fable-5-1`     | 最新一代 Claude                   |
| `gpt-6-astra`          | 最新一代 GPT，输入超过 272K 后按长上下文档位计费 |
| `gpt-5.6-terra`        | 日常对话，能力与成本均衡                  |
| `gemini-3.7-flash`     | 快、便宜、多模态                      |
| `deepseek-v4-pro-0813` | 低价强推理                         |
| `glm-5.3-flash`        | 最便宜的档位，适合高频对话                 |
| `kimi-k3`              | 超长上下文任务                       |
| `qwen3.8-max`          | 中文任务                          |

完整目录见[文本 API](/text-api) 各页与[价目页](https://beatapi.io/pricing)。想加多少加多少，聊天时在顶部下拉里随时切换。

## 第四步：开始对话

回到主界面，点 **+** 新建对话，在顶部点模型选择器，在 **BeatAPI** 服务商下选一个模型即可。

## 常见问题

### Cherry Studio 连不上

1. API 地址必须是 `https://api.beatapi.io` —— 不带 `/v1`。
2. 密钥必须处于可用状态 —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)确认。
3. 服务商开关必须是打开的。

### 模型列表为空或刷新不出来

在模型管理里按编号手工添加。编号见[价目页](https://beatapi.io/pricing)，区分大小写。

### 对话过程中报错

| 状态码           | 含义                                                          | 处理                                                  |
| ------------- | ----------------------------------------------------------- | --------------------------------------------------- |
| `401`         | `missing_api_key` 或 `invalid_api_key`：密钥缺失、错误、已过期、已停用或额度已用尽 | 从控制台重新复制密钥                                          |
| `402`         | `insufficient_credits`：余额为零或低于本次价格                          | 充值                                                  |
| `404`         | 模型编号或 API 地址填错了                                             | 对照上面两条说明检查                                          |
| `429`         | 超出请求频率上限                                                    | 稍等；额度随累计充值提升                                        |
| `500` / `503` | 我方临时故障（`internal_error`、`processing_*`）                     | 保留 `request_id`，退避重试，见[错误码](/errors#text-endpoints) |

### 查看用量与消费

控制台按密钥展示调用次数、token 与费用，同样的数据也可从 [`GET /v1/usage`](/quick-guide) 获取。

## 获取支持

在[控制台](https://beatapi.io/dashboard)提交工单，并附上失败响应里的 `request_id`。