# Beatra Skill + MCP — 音频处理、人声提取与分轨

> 从背景噪音与音乐中提取干净人声、将歌曲分离为伴奏与多轨，或执行裁剪、循环、淡入淡出、响度归一化与格式转换。
> 面向 AI 智能体的独立工作流指南。
> 对应网页：https://docs.beatra.cn/zh/docs/capabilities/speech/audio-processing

- 主要接入方式：通用 Beatra Skill，经已授权的 MCP 调用。
- 安装或重新连接：https://beatra.ai/install.md
- MCP 端点：`https://mcp.beatra.cn/mcp`
- 计费操作：`beatra.audio.process`
- 动态模型信息：只在需要模型约束、控制项或价格时，调用 `beatra.models.list` 并传 `capability: "audio_process"`。
- 交互方式：生成一个不透明的 `client_request_id`，把最终参数只提交一次，再用 `beatra.tasks.get` 轮询返回的 `task_id`，直到任务结束。
- 本地媒体：调用 `beatra.assets.upload`，严格按返回的 HTTPS PUT 上传，再使用 PUT 响应里的 artifact ID。

REST/OpenAPI 是备用的协议路径，智能体以 Skill 为主要接入方式。

---

从嘈杂录音或背景音乐中提取纯净人声、将混音歌曲分离为独立音轨，或执行确定性的音频后期处理——裁剪、无缝循环延展、淡入淡出、EBU R128 响度归一化与格式转换。

## Agent 主路径

通过 Universal Skill 使用 MCP 工具 `beatra.audio.process`。同一个工具通过 `operation` 字段覆盖三类音频能力，每次调用都返回计费的异步任务：

| `operation` | 能力标识（`capability`） | 模型 | 对称 REST 端点 |
| --- | --- | --- | --- |
| `isolate_voice` | `audio_voice_isolation` | `elevenlabs-audio-isolation` | `POST /v1/audio/isolation` |
| `separate_stems` | `audio_stem_separation` | `beatra-stems-v1` | `POST /v1/audio/stems` |
| `trim`、`loop`、`fade`、`normalize_loudness`、`convert_format` | `audio_process` | `beatra-audio-v1` | `POST /v1/audio/process` |

1. 用 `beatra.assets.upload` 上传本地音频，将返回的 `artifact_id` 作为 `source` 传入（MCP 与 REST 均互换兼容 `source` 与 `audio` 字段；也可直接传 `https_url`）。拥有 `speech:generate` 或 `music:generate` 任一权限的令牌均可调用 `beatra.audio.process`。
2. 需要查看实时限制、支持格式或积分单价时，传入对应 `capability` 调用 `beatra.models.list`。
3. 创建一个不透明的 `client_request_id`，只提交一次，并用 `beatra.tasks.get` 轮询到终态。

## 人声提取

`operation: "isolate_voice"`（`elevenlabs-audio-isolation`，REST `POST /v1/audio/isolation`）从录音中提取纯净的说话声或演唱人声，去除背景音乐、房间混响、风声、车流与人群噪音；适合在进行[音色克隆](https://docs.beatra.cn/zh/docs/capabilities/speech/voice-clone)、[语音转文字](https://docs.beatra.cn/zh/docs/capabilities/speech/speech-to-text)或[语音转换](https://docs.beatra.cn/zh/docs/capabilities/speech/speech-to-speech)前清洗嘈杂素材。

```json
{
  "operation": "isolate_voice",
  "source": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "format": "wav",
  "client_request_id": "isolate-opaque-1"
}
```

- **输入限制**：源音频时长须在 **`4.6` 秒到 `300.0` 秒（`5 分钟`）**之间，文件不超过 `100 MB`。短于 `4.6` 秒或长于 `300.0` 秒的片段会在扣费前以 `422 invalid_request`（`details.reason: "audio_too_short"` 或 `"audio_too_long"`）拒绝，不扣积分。MCP `beatra.audio.process` 与 REST `POST /v1/audio/isolation` 均同时接受 `source` 或 `audio` 字段传入源媒体引用（并兼容旧模型别名 `"beatra-voice-isolate-v1"`，自动归一化为 `"elevenlabs-audio-isolation"`）。
- **可选输出编码参数**：`isolate_voice` 仅接受 `format`（默认 `"wav"`，可选 `"mp3"`、`"ogg"`、`"flac"`、`"m4a"`、`"ulaw_8k_wav"`）、`sample_rate`（`8000`、`16000`、`22050`、`24000`、`32000`、`44100`、`48000` Hz）、`bitrate_kbps`（有损 `"mp3"`、`"ogg"`、`"m4a"` 可选 `64`、`128`、`192`、`256`、`320`，其中 `"m4a"` 最高 `256`）与 `channels`（`1` 或 `2`）。请勿在 `isolate_voice` 上传 `fade_in_ms`、`fade_out_ms`、`loudness_lufs` 或 `true_peak_db`——如需淡入淡出或响度归一化，请在提取后调用下方确定性音频处理工具。
- **成本与输出**：按**输入音频的计费分钟数**（进位）预扣积分，每分钟 `721 积分`（`<= 60` 秒为 `721 积分`，`5` 分钟为 `3,605 积分`）。返回 `outputs: [{"role": "voice", ...}]`，只交付提取后的纯净人声，不生成伴奏音轨。

## 歌曲分轨

`operation: "separate_stems"`（`beatra-stems-v1`，REST `POST /v1/audio/stems`）把混音音乐（最长 `600` 秒 / `10 分钟`，`<= 100 MB`）分离为独立的人声与乐器音轨。

```json
{
  "operation": "separate_stems",
  "source": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "mode": "two_stem",
  "client_request_id": "stems-opaque-1"
}
```

- `mode: "two_stem"`（默认，每次 `180 积分`）：分离出 `vocals`（人声）与 `instrumental`（伴奏，`outputs[].role` 为 `"vocals"`、`"instrumental"`）。
- `mode: "multi_stem"`（每次 `360 积分`）：分离出最多 6 条音轨（`vocals`、`drums`、`bass`、`guitar`、`piano`、`other`，`outputs[].role` 分别为 `"stem:vocals"`、`"stem:drums"`、`"stem:bass"`、`"stem:guitar"`、`"stem:piano"`、`"stem:other"`）。
- 输出格式由分轨模型固定决定，`separate_stems` 不接受 `format` 或本地后期参数。

## 确定性音频处理工具

`beatra-audio-v1`（REST `POST /v1/audio/process`）对最长 `3,600` 秒（`60 分钟`，`<= 300 MB`）的音频执行确定性后期处理，按固定每次 **`60 积分`** 计费：

- `trim`：用 `start_ms`（`>= 0`，默认 `0`）配合 `end_ms`（`> start_ms`）或 `target_duration_ms` **二选一**精确裁剪区间。
- `loop`：把整段或子区间（`loop_start_ms` 默认 `0`、`loop_end_ms`，循环窗口不少于 `4,000` 毫秒）用 `target_duration_ms`（`1,000`–`3,600,000` 毫秒）或 `loop_count`（`2`–`100` 次）**二选一**循环延展，支持 `crossfade_ms`（`50`–`3,000` 毫秒，默认 `500` 毫秒）与 `end_with_fade`（布尔，默认 `true`）。
- `fade`：用 `fade_in_ms` 与／或 `fade_out_ms`（`0`–`30,000` 毫秒，至少传入一项）配合 `fade_curve`（默认 `"tri"`，可选 `"exp"`、`"log"`、`"qsin"`）添加淡入淡出。
- `normalize_loudness`：双遍 EBU R128 响度归一化，目标 `loudness_lufs`（`-30.0` 至 `-9.0` LUFS，默认 `-14.0`）与 `true_peak_db`（`-9.0` 至 `0.0` dBTP，默认 `-1.0`）。
- `convert_format`：转码或重采样为必填的 `format`（`"mp3"`、`"wav"`、`"ogg"`、`"flac"`、`"m4a"` 或 8 kHz 单声道电话音频 `"ulaw_8k_wav"`），可选 `sample_rate`、`bitrate_kbps` 与 `channels`（`1` 或 `2`）。
- 上述 5 种确定性操作均可在同一次任务中附带可选收尾参数（`fade_in_ms`、`fade_out_ms`、`fade_curve`、`loudness_lufs`、`true_peak_db`、`format`、`sample_rate`、`bitrate_kbps`、`channels`）。

## 结果

所有操作均返回 `"type": "audio_process"`、`"operation"` 与 `"outputs"`（`separate_stems` 另含 `"mode"`，确定性音频处理工具另含 `"metrics"` 与 `"steps"`）。每个 `outputs[]` 条目包含 `role`（人声提取为 `"voice"`，双轨分轨为 `"vocals"` / `"instrumental"`，多轨分轨为 `"stem:<kind>"`，确定性处理为 `"main"`）、`artifact_id`、CDN `url`、`mime_type` 与 `duration_seconds`；仅 `"role": "main"` 额外包含实测 `loudness_lufs` 与 `true_peak_db`：

```json
{
  "type": "audio_process",
  "operation": "isolate_voice",
  "outputs": [
    {
      "role": "voice",
      "artifact_id": "artifact_01JZ...",
      "url": "https://cdn.beatra.cn/tenants/.../voice.wav",
      "mime_type": "audio/wav",
      "duration_seconds": 18.4
    }
  ]
}
```

## 任务状态与恢复

`queued` 与 `running` 不是失败。请持续轮询同一个 `task_id`；创建响应丢失时用同一个 `client_request_id` 原样重试，参数有任何变化则换新 ID。失败任务自动退回预扣积分。产物 URL 是 CDN 地址——请尽快转存到自己的存储。

## 通过 REST 调用

直连协议集成可使用 `POST /v1/audio/isolation`、`POST /v1/audio/stems` 或 `POST /v1/audio/process`（携带固定的 `Idempotency-Key` 请求头）及共享任务端点，详见[接口参考](https://docs.beatra.cn/zh/docs/api-reference)。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。

---

## 附录：Skill + MCP 通用约定

### 重试标识

一次逻辑上的生成对应一个 `client_request_id`。创建请求的响应丢失时，用同一个 ID 和完全相同的参数重试。提示词、媒体、模型或输出控制项有任何变化，就换一个新 ID。任务处于 `queued` 或 `running` 是正常状态，继续轮询同一个任务即可，不另建付费任务。

### 轮询与计费以任务为准

用有上限的退避间隔调用 `beatra.tasks.get` 轮询，遇到 `succeeded`、`failed` 或 `canceled` 时停止。实际使用的模型、产物、扣除的积分和退回的积分，以任务响应为准。

### 出错后的处理

保留 Beatra 返回的结构化错误码。鉴权失败时重新连接；余额不足时停下来，请用户充值；模型校验失败后用 `beatra.models.list` 刷新当前约束；上传授权过期，或 MIME 类型、长度不符时，申请新的上传授权。生成参数有变化时，一律使用新的 `client_request_id`。