音频处理、人声提取与分轨

从背景噪音与音乐中提取干净人声、将歌曲分离为伴奏与多轨，或执行裁剪、循环、淡入淡出、响度归一化与格式转换。

从嘈杂录音或背景音乐中提取纯净人声、将混音歌曲分离为独立音轨，或执行确定性的音频后期处理——裁剪、无缝循环延展、淡入淡出、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`

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

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

Markdown

人声提取

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

{
  "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）分离为独立的人声与乐器音轨。

{
  "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：

{
  "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 请求头）及共享任务端点，详见接口参考。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。