资讯 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

音频分离

接口描述

提交一个音频或视频文件,音频分离服务会异步分离出人声、背景音、乐器等音轨,分离完成后可通过返回的下载链接获取结果。

调用流程:

  1. 调用「提交分离任务」接口,拿到每个文件对应的 task_id。
  2. 用 task_id 轮询「查询分离任务」接口,或在提交时配置回调地址等待通知。
  3. 任务状态变为 done 后,从查询结果中的下载链接获取各音轨文件。

通用说明

鉴权参数

以下两种方式任选其一,均未提供时返回鉴权失败(错误码 100020)

参数名称 类型 参数位置 是否必填 说明
access_token string query 鉴权方式二选一 鉴权令牌
Authorization string header 鉴权方式二选一 鉴权API Key

请求与响应格式

  • 请求体与响应体均为 JSON,提交接口请设置 Content-Type: application/json。
  • 响应统一结构如下,业务数据在 data 字段中:
{
  "log_id": "请求日志ID,排查问题时提供",
  "error_code": 0,
  "error_message": "success",
  "data": {}
}
  • error_code 为 0 表示成功;非 0 表示失败,error_message 为失败原因。

任务状态

状态值 含义
init 待处理
doing 处理中
done 已完成,可获取结果
failed 处理失败,见 fail_reason

音频分离-素材上传接口

接口说明

获取 BOS 临时上传凭证,用于客户端直传文件到 BOS 存储。凭证有效期固定为 1 小时。

典型上传流程:

  1. 调用本接口获取临时凭证(access_key_id、secret_access_key、session_token)和目标路径(resource、bucket_name、endpoint)
  2. 使用 BOS SDK 或 HTTP PUT 请求,将文件直传到 endpoint/bucket_name/resource,参考 BOS STS 文档
  3. 上传成功后,将 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 字符

请求示例

curl --location 'https://aip.baidubce.com/rpc/2.0/speech/publiccloudspeech/v1/echo/footage/upload' \
--header 'authorization: Bearer xxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "file_name":"test.mp4" 
}'

响应说明

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

响应示例

{
  "log_id": "20250622150000XXXX",
  "error_code": 0,
  "error_message": "success",
  "data": {
    "access_key_id": "STSxxxxxxxxxxxx",
    "secret_access_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "session_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "expiration": "2025-06-22T16:00:00Z",
    "resource": "prefix/projects/100001/550e8400-e29b-41d4-a716-446655440000/video_sample.mp4",
    "bucket_name": "echo-prod",
    "endpoint": "https://bos.bj.bcebos.com"
  }
}

错误码

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 必须在上述取值范围内。

请求示例

{
  "files": [
    {
      "file_url": "https://example.com/input/song.mp3",
      "file_type": "mp3",
      "file_name": "song.mp3"
    }
  ],
  "separation_mode": "vocals_background",
  "output": { "format": "wav", "sample_rate": 44100, "channels": "stereo" },
  "callback_url": "https://example.com/callback",
  "client_request_id": "req-20261012-0001"
}

响应说明

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

响应示例

{
  "log_id": "1234567890",
  "error_code": 0,
  "error_message": "success",
  "data": {
    "tasks": [
      {
        "file_url": "https://example.com/input/song.mp3",
        "file_type": "mp3",
        "file_name": "song.mp3",
        "task_id": "100001",
        "status": "init"
      }
    ]
  }
}

幂等说明

传入 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):

{
  "log_id": "1234567890",
  "error_code": 0,
  "error_message": "success",
  "data": {
    "task_id": "100001",
    "status": "done",
    "result": {
      "vocal_url": "https://.../vocals.wav?下载凭证",
      "background_audio_url": "https://.../background.wav?下载凭证"
    },
    "fail_reason": ""
  }
}

处理中:

{
  "log_id": "1234567890",
  "error_code": 0,
  "error_message": "success",
  "data": {
    "task_id": "100001",
    "status": "doing",
    "result": null,
    "fail_reason": ""
  }
}

回调通知

提交任务时若传入 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 不存在或不属于音轨分离任务
查询了非本账号的任务 无权限访问该任务
上一篇
语音识别
下一篇
SDK文档