认证与请求约定
给程序调用用的 API Key、接口地址和请求头。
API Key
Bearer 认证，每个请求携带：
钥匙的前缀里写着地区，例如 sk-row-...。row 是这把钥匙所属的地区，它决定请求发往哪一台接口。row 对应 https://api.beatra.cn/v1。地区对不上时，请求会被拒绝。
在控制台 console.beatra.cn 打开 开发 → API Key 创建。密钥只在创建时显示一次。更换时：新建一把 → 把程序改成用新的 → 再作废旧的（新旧可以同时有效）。
在控制台登录，是给人管理账户用的。API Key 给程序、服务和后台任务用。不要把控制台的登录状态放进自动运行的程序里。
Base URL
请求头
| 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 处理见限流。
连接 MCP 宿主（OAuth）
在支持标准 MCP OAuth 的宿主里添加 https://mcp.beatra.cn/mcp。
宿主会自己找到 Beatra 的登录入口、完成注册，并在浏览器里打开 Beatra 的页面。
登录后看清楚连接去向，点允许即可。不需要 API 密钥，也没有要复制的令牌。
连接后，应用可以：
- 用你的 Beatra 积分生成图片、视频、音乐和语音，调用社媒公开数据工具；
- 使用和管理你的声音（包括克隆的声音）与数字人形象；
- 查看、取消任务，保存、读取作品；
- 查看余额和积分流水（含充值记录）。
连接的有效期：
- 用 OAuth 登录的宿主会一直保持登录，后台自动续期；连续一年没用，重新登录一次即可。
- 用无头接入命令建立的连接一直有效，直到你断开，或连续一年没有使用。
在控制台的设备 → 已连接的应用里管理：查看每个应用、它连到哪里、首次连接和最近使用的时间，并可以断开。 如果检测到某个应用的登录凭据被复制使用，Beatra 会为了保护账号断开这个应用并在那里提示你；在应用里重新连接即可。
运行 Beatra Skill 的智能体通过 Skill 登录，见快速开始。
最后更新