# 认证与请求约定
> 给程序调用用的 API Key、接口地址和请求头。

## API Key

Bearer 认证，每个请求携带：

```text
Authorization: Bearer sk-<region>-...
```

钥匙的前缀里写着地区，例如 `sk-row-...`。`row` 是这把钥匙所属的地区，它决定请求发往哪一台接口。`row` 对应 `https://api.beatra.cn/v1`。地区对不上时，请求会被拒绝。
在控制台 [console.beatra.cn](https://console.beatra.cn) 打开 **开发 → API Key** 创建。密钥只在创建时显示一次。更换时：新建一把 → 把程序改成用新的 → 再作废旧的（新旧可以同时有效）。

在控制台登录，是给人管理账户用的。API Key 给程序、服务和后台任务用。不要把控制台的登录状态放进自动运行的程序里。

## Base URL

```text
https://api.beatra.cn/v1
```

## 请求头

| Header | 必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | `Bearer <api_key>` |
| `Content-Type` | 是 | `application/json`（文件上传除外） |
| `Idempotency-Key` | 强烈建议 | 创建类 `POST` 携带；重试用同一个 key。去重是持久的：同一 key 始终解析到同一个任务 |
| `X-Request-Id` | 可选 | 响应原样回显；排障时的最快检索键 |

## 幂等规则

- 同一逻辑操作的重试 → **同一个** `Idempotency-Key`；
- 用户意图变了 → 换新 key；
- 同 key 不同 body → `409 idempotency_conflict`。

限流响应头与 429 处理见[限流](https://docs.beatra.cn/zh/docs/mechanisms/rate-limits)。

## 连接 MCP 宿主（OAuth）

在支持标准 MCP OAuth 的宿主里添加 `https://mcp.beatra.cn/mcp`。
宿主会自己找到 Beatra 的登录入口、完成注册，并在浏览器里打开 Beatra 的页面。
登录后看清楚连接去向，点**允许**即可。不需要 API 密钥，也没有要复制的令牌。

连接后，应用可以：

- 用你的 Beatra 积分生成图片、视频、音乐和语音，调用社媒公开数据工具；
- 使用和管理你的声音（包括克隆的声音）与数字人形象；
- 查看、取消任务，保存、读取作品；
- 查看余额和积分流水（含充值记录）。

连接的有效期：

- 用 OAuth 登录的宿主会一直保持登录，后台自动续期；连续一年没用，重新登录一次即可。
- 用[无头接入命令](/zh/docs/agent-connect)建立的连接一直有效，直到你断开，或连续一年没有使用。

在控制台的**设备 → 已连接的应用**里管理：查看每个应用、它连到哪里、首次连接和最近使用的时间，并可以断开。
如果检测到某个应用的登录凭据被复制使用，Beatra 会为了保护账号断开这个应用并在那里提示你；在应用里重新连接即可。

运行 Beatra Skill 的智能体通过 Skill 登录，见[快速开始](/zh/docs/quickstart)。