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

# 在 ChatBox 中使用 BeatAPI

> 通过 ChatBox 的 OpenAI、Claude 或 Gemini 三种类型接入 BeatAPI。

# 在 ChatBox 中使用 BeatAPI

ChatBox 是一个跨平台桌面对话客户端。BeatAPI 同时提供 OpenAI、Anthropic、Gemini 三种请求格式，所以 ChatBox 的三种服务商类型都能用，选哪个取决于你想调的模型。

## 准备工作

1. **已安装 ChatBox** —— Windows、macOS、Linux 或网页版。
2. **一把 BeatAPI 密钥** —— 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)创建。

## 第一步：打开配置

首次启动会出现配置向导，点 **Use your own API Key or local model**。

已经配过的话，点左下角齿轮图标，或按 `Ctrl+,`（macOS 为 `Cmd+,`）。

## 第二步：选类型并填地址

**地址随服务商类型而不同**，因为每种客户端拼接的路径不一样。这一步填错是最常见的失败原因。

| 服务商类型      | API 地址                      | 用于                                         |
| ---------- | --------------------------- | ------------------------------------------ |
| OpenAI API | `https://api.beatapi.io`    | GPT、DeepSeek、GLM、Kimi、MiniMax、Qwen、MiMo、混元 |
| Claude API | `https://api.beatapi.io/v1` | Claude 系列                                  |
| Gemini API | `https://api.beatapi.io/`   | Gemini 系列                                  |

三种情况下密钥都是同一把 BeatAPI 密钥。

> **Note**
>
> 账户下每个模型都支持全部四种格式，所以服务商类型决定的是 ChatBox 发出什么结构的请求，而不是你能调哪些模型。三个地址之所以不同，是因为 OpenAI 类型会拼 `/v1/chat/completions`、Claude 类型会拼 `/messages`、Gemini 类型会拼 `v1beta/models/...`。上表每一组拼出来都正好是一个真实存在的 BeatAPI 端点。

## 第三步：选模型

在下拉列表里选择模型；列表没刷新出来的话直接输入编号。

| 模型编号                        | 服务商类型      | 适用场景          |
| --------------------------- | ---------- | ------------- |
| `gpt-6-astra`               | OpenAI API | 最新一代 GPT      |
| `gpt-5.6-terra`             | OpenAI API | 日常对话，能力与成本均衡  |
| `claude-fable-5-1`          | Claude API | 最新一代 Claude   |
| `claude-haiku-4-5-20251001` | Claude API | 快速便宜          |
| `gemini-3.7-flash`          | Gemini API | 快速、多模态        |
| `deepseek-v4-pro-0813`      | OpenAI API | 低价强推理         |
| `glm-5.3-flash`             | OpenAI API | 最便宜的档位，适合高频对话 |

完整目录见[文本 API](/text-api) 各页与[价目页](https://beatapi.io/pricing)。

### 可选参数

| 参数          | 作用     | 建议值                   |
| ----------- | ------ | --------------------- |
| Temperature | 输出随机性  | `0.7` 偏创意 / `0.3` 偏精确 |
| Max Tokens  | 输出长度上限 | 2000–4000             |
| Top P       | 核采样    | `0.9`                 |

设置 Max Tokens 是最简单的成本控制手段 —— 多数对话里，输出才是贵的那一半。

## 常见问题

### ChatBox 连不上

1. 对照上面的表复查 API 地址 —— 三种类型的 `/v1` 处理方式不同。
2. 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)确认密钥仍然可用。

### 列表里看不到 BeatAPI 的模型

直接在模型输入框里手工输入编号。编号见[价目页](https://beatapi.io/pricing)，区分大小写。

### 对话过程中报错

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

### 查看用量与消费

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

## 获取支持

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