音频分离
接口描述
提交一个音频或视频文件,音频分离服务会异步分离出人声、背景音、乐器等音轨,分离完成后可通过返回的下载链接获取结果。
调用流程:
- 调用「提交分离任务」接口,拿到每个文件对应的 task_id。
- 用 task_id 轮询「查询分离任务」接口,或在提交时配置回调地址等待通知。
- 任务状态变为 done 后,从查询结果中的下载链接获取各音轨文件。
通用说明
鉴权参数
以下两种方式任选其一,均未提供时返回鉴权失败(错误码 100020)
| 参数名称 | 类型 | 参数位置 | 是否必填 | 说明 |
|---|---|---|---|---|
| access_token | string | query | 鉴权方式二选一 | 鉴权令牌 |
| Authorization | string | header | 鉴权方式二选一 | 鉴权API Key |
请求与响应格式
- 请求体与响应体均为 JSON,提交接口请设置
Content-Type: application/json。 - 响应统一结构如下,业务数据在
data字段中:
1{
2 "log_id": "请求日志ID,排查问题时提供",
3 "error_code": 0,
4 "error_message": "success",
5 "data": {}
6}
error_code为 0 表示成功;非 0 表示失败,error_message为失败原因。
任务状态
| 状态值 | 含义 |
|---|---|
| init | 待处理 |
| doing | 处理中 |
| done | 已完成,可获取结果 |
| failed | 处理失败,见 fail_reason |
音频分离-素材上传接口
接口说明
获取 BOS 临时上传凭证,用于客户端直传文件到 BOS 存储。凭证有效期固定为 1 小时。
典型上传流程:
- 调用本接口获取临时凭证(
access_key_id、secret_access_key、session_token)和目标路径(resource、bucket_name、endpoint) - 使用 BOS SDK 或 HTTP PUT 请求,将文件直传到
endpoint/bucket_name/resource,参考 BOS STS 文档 - 上传成功后,将
https://<endpoint>/<bucket_name>/<resource>作为video_url传入任务创建接口
注意事项:
- 凭证有效期固定为 1 小时,请在过期前完成上传;超时后需重新调用本接口获取新凭证。
- 每次调用会生成唯一的 UUID 路径,避免多次上传覆盖同名文件。
- 上传成功后 BOS 文件永久保留,与创建任务无关联。任务删除不会删除 BOS 上的原始文件。
- 本接口仅生成凭证,不存储素材记录。
请求说明
HTTP方法:POST
请求方式:application/json
请求地址:https://aip.baidubce.com/rpc/2.0/speech/publiccloudspeech/v1/echo/footage/upload
Body参数
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| file_name | string | 是 | 文件名称,需带后缀(如 video.mp4),最大长度 50 字符 |
请求示例
1curl --location 'https://aip.baidubce.com/rpc/2.0/speech/publiccloudspeech/v1/echo/footage/upload' \
2--header 'authorization: Bearer xxxxxxx' \
3--header 'Content-Type: application/json' \
4--data '{
5 "file_name":"test.mp4"
6}'
响应说明
Data字段说明
| 字段名称 | 类型 | 说明 |
|---|---|---|
| access_key_id | string | 临时 Access Key ID,用于 BOS 客户端鉴权 |
| secret_access_key | string | 临时 Secret Access Key,用于 BOS 客户端鉴权 |
| session_token | string | 临时 Session Token,STS 鉴权必填 |
| expiration | string | 凭证过期时间,ISO 8601 格式(如 2025-06-22T16:00:00Z) |
| resource | string | BOS 目标对象路径,不含 bucket,如 prefix/projects/12345/uuid/video_sample.mp4 |
| bucket_name | string | BOS Bucket 名称 |
| endpoint | string | BOS Endpoint 地址,如 https://bos.bj.bcebos.com |
响应示例
1{
2 "log_id": "20250622150000XXXX",
3 "error_code": 0,
4 "error_message": "success",
5 "data": {
6 "access_key_id": "STSxxxxxxxxxxxx",
7 "secret_access_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
8 "session_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
9 "expiration": "2025-06-22T16:00:00Z",
10 "resource": "prefix/projects/100001/550e8400-e29b-41d4-a716-446655440000/video_sample.mp4",
11 "bucket_name": "echo-prod",
12 "endpoint": "https://bos.bj.bcebos.com"
13 }
14}
错误码
| error_code | error_message | 触发场景 |
|---|---|---|
| 0 | success | 成功 |
| 100001 | 请求体非法 | JSON 解析失败 |
| 100002 | 系统内部错误,请稍后重试 | 生成 STS Token 失败或内部异常 |
| 100003 | 无效的参数 | file_name 为空 |
| 100019 | 名称长度超限 | file_name 超过 50 字符 |
| 100027 | 生成上传文件Token失败 | STS Token 申请失败 |
音频分离-任务提交接口
接口说明
提交一批文件创建音轨分离任务,支持批量,一个文件对应一个独立的 task_id。
请求说明
请求方法:POST
请求方式:application/json
完整路径:https://aip.baidubce.com/rpc/2.0/speech/publiccloudspeech/v1/echo/audio/separation/create
Content-Type:application/json
Body参数
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| files | array | 是 | 输入文件列表,支持批量,最多 10 个 |
| files[].file_url | string | 是 | 输入文件下载地址,须为 http/https 公网可访问链接 |
| files[].file_type | string | 是 | 文件扩展名,小写不带点,取值如下: 音频: mp3、wav、flac、m4a、aac、ogg视频: mp4、mov、mkv、avi |
| files[].file_name | string | 否 | 原始文件名,长度不超过 50 个字符 |
| separation_mode | string | 否 | 分离模式,取值见下方「separation_mode 取值范围」,默认 vocals_background |
| output | object | 否 | 输出配置,不传则使用默认值 |
| output.format | string | 否 | 输出格式,取值仅 wav,默认 wav |
| output.sample_rate | int | 否 | 采样率,取值仅 44100,默认 44100 |
| output.channels | string | 否 | 声道,取值仅 stereo,默认 stereo |
| callback_url | string | 否 | 任务完成回调地址,须为 http/https 公网可访问链接 |
| client_request_id | string | 否 | 幂等键,用于避免重复提交,见下方「幂等说明」 |
separation_mode 取值范围
| 值 | 含义 | 产出音轨 |
|---|---|---|
| vocals | 仅人声 | vocals |
| background | 仅背景音 | background |
| vocals_background | 人声 + 背景音(默认) | vocals、background |
| stems_4 | 四轨分离 | vocals、drums、bass、other |
参数约束
files不能为空,且数量不超过 10 个。file_url、callback_url必须是http/https开头的公网可访问地址。file_type必须是上面列出的音频或视频类型之一。file_name若传入,长度不超过 50 个字符。separation_mode、output.format、output.sample_rate、output.channels必须在上述取值范围内。
请求示例
1{
2 "files": [
3 {
4 "file_url": "https://example.com/input/song.mp3",
5 "file_type": "mp3",
6 "file_name": "song.mp3"
7 }
8 ],
9 "separation_mode": "vocals_background",
10 "output": { "format": "wav", "sample_rate": 44100, "channels": "stereo" },
11 "callback_url": "https://example.com/callback",
12 "client_request_id": "req-20261012-0001"
13}
响应说明
Data字段说明
data.tasks 为数组,每个元素对应一个输入文件,回显其输入信息并关联 task_id:
| 字段名称 | 类型 | 说明 |
|---|---|---|
| tasks[].file_url | string | 对应的输入文件地址 |
| tasks[].file_type | string | 对应的输入文件扩展名 |
| tasks[].file_name | string | 对应的输入文件名(提交时未传则不返回) |
| tasks[].task_id | string | 任务 ID,用于后续查询 |
| tasks[].status | string | 任务初始状态,提交成功为 init |
响应示例
1{
2 "log_id": "1234567890",
3 "error_code": 0,
4 "error_message": "success",
5 "data": {
6 "tasks": [
7 {
8 "file_url": "https://example.com/input/song.mp3",
9 "file_type": "mp3",
10 "file_name": "song.mp3",
11 "task_id": "100001",
12 "status": "init"
13 }
14 ]
15 }
16}
幂等说明
传入 client_request_id 可避免网络重试等导致的重复提交:
- 24 小时内使用相同
client_request_id且参数一致的重复提交,直接返回首次提交的结果,不会重复创建任务。 - 相同
client_request_id但参数不一致,返回重复请求错误。
音频分离-结果查询接口
接口说明
根据 task_id 查询单个任务的状态与结果。任务 done 后,result 中返回各音轨的下载链接(链接有时效,1 小时内有效,过期后重新查询获取新链接)。
注意事项:
- 轮询查询时建议间隔若10s,避免过于频繁的请求。
- 下载链接有时效,获取后尽快下载;过期后重新查询可获取新链接。
请求说明
- 请求方法:POST
- 请求方式:application/json
- 完整路径:https://aip.baidubce.com/rpc/2.0/speech/publiccloudspeech/v1/echo/audio/separation/query
Query参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| task_id | string | 是 | 提交接口返回的任务 ID |
示例:https://aip.baidubce.com/rpc/2.0/speech/publiccloudspeech/v1/echo/audio/separation/query?task_id=xxxx
响应说明
响应参数
| 字段名称 | 类型 | 说明 |
|---|---|---|
| task_id | string | 任务 ID |
| status | string | 任务状态:init / doing / done / failed |
| result | object | 分离结果,仅 done 时有值,其余为 null |
| fail_reason | string | 失败原因,failed 时有值 |
result 字段(下载链接,按提交时的 separation_mode 返回对应音轨,未产出的音轨字段不返回):
| 字段名称 | 对应音轨 | 出现的分离模式 |
|---|---|---|
| vocal_url | 人声 | vocals / vocals_background / stem_4 |
| background_audio_url | 背景音 | background / vocals_background |
| drums_audio_url | 鼓 | stem_4 |
| bass_audio_url | 贝斯 | stem_4 |
| other_audio_url | 其他伴奏 | stem_4 |
响应示例
任务完成(提交时 separation_mode = vocals_background):
1{
2 "log_id": "1234567890",
3 "error_code": 0,
4 "error_message": "success",
5 "data": {
6 "task_id": "100001",
7 "status": "done",
8 "result": {
9 "vocal_url": "https://.../vocals.wav?下载凭证",
10 "background_audio_url": "https://.../background.wav?下载凭证"
11 },
12 "fail_reason": ""
13 }
14}
处理中:
1{
2 "log_id": "1234567890",
3 "error_code": 0,
4 "error_message": "success",
5 "data": {
6 "task_id": "100001",
7 "status": "doing",
8 "result": null,
9 "fail_reason": ""
10 }
11}
回调通知
提交任务时若传入 callback_url,任务进入最终状态(done / failed)后,服务会向该地址发起一次 POST 通知:
- 请求体为与查询接口
data一致的 JSON(含task_id/status/result/fail_reason)。 - 回调为“尽力通知”,不保证送达,建议同时用查询接口确认最终结果。
错误码
调用失败时 error_code 为非 0,error_message 描述原因。常见场景:
| 场景 | 说明 |
|---|---|
| 请求体解析失败 | 请求 JSON 格式有误 |
| 鉴权失败 | 未携带或携带了无效的鉴权信息 |
files 为空或超过 10 个 |
文件数量不符合要求 |
file_url / callback_url 不合法 |
不是合法的公网 http/https 地址 |
file_type 不在支持范围 |
文件类型不受支持 |
file_name 超长 |
文件名超过 50 个字符 |
separation_mode / output.* 取值非法 |
参数不在支持的取值范围内 |
| 幂等键相同但参数不一致 | 重复请求 |
| 查询的任务不存在 | task_id 不存在或不属于音轨分离任务 |
| 查询了非本账号的任务 | 无权限访问该任务 |
评价此篇文章
