# 伴奏人声提取

# 使用场景和限制

# 使用场景(仅供参考)

  • 某音乐软件使用团子的“伴奏提取”功能,处理了大量歌曲,将其数据库内的歌曲提前消音化,并在此之上提供“K歌”功能。
  • 某提供伴奏制作的工作室网站,对接了团子的 API 服务,并在此之上二次包装,并自己定制收费规则,来达到盈利的效果。

# 限制

  • 由于团子伴奏提取的 AI 系统极其复杂,不支持对实时性要求较高的业务,适合需要处理大量音乐文件并转为伴奏、且对实时性要求不强的的业务,因为AI需要载入一整首歌曲来进行学习处理(AI的CNN注意力机制),无法把歌曲进行分割,否则可能出现每一段的处理效果都不同的问题。
  • 请勿过快调用接口,以免被自动限制,本页面全部接口限制最大QPS(每秒可调用接口次数):5次

# 创建上传通道

在使用团子上传歌曲之前,你必须创建一条临时一次性的上传通道(channel),你可以在通道里提交即将上传的文件的选项,当服务器确认无误后将返回该通道的信息,持有这些信息就可以上传歌曲了。

创建通道不会扣费,只会预测余额是否不足且传递一些配置信息。

请求地址:

POST https://api.dango.ai/vocal-remover/upload/channel

请求参数:

参数名 类型 必须 默认 描述
filename string 歌曲的文件名(需要包含扩展名,如"1.mp3")
style int 必填 AI算法,请参考歌曲算法

# 歌曲算法

值(int) 描述
0 团子2.0多轨提取算法(已过时不推荐)
5 团子4.0伴奏人声提取算法
6 团子4.0更好人声提取算法(已过时不推荐)
7 团子4.0和声保留提取算法(已过时不推荐)
8 团子4.0伴奏人声提取算法(激进)(已过时不推荐)
9 团子5.0伴奏人声提取算法
10 团子5.0更好人声提取算法
11 团子5.0和声保留算法
12 团子3.0多轨提取算法

请求举例:

POST https://api.dango.ai/vocal-remover/upload/channel

{
	"style": 5,
	"filename": "test.mp3"
}

返回结果:

参数名 类型 必须 默认 描述
channel string 上传的通道号,持有此通道号用来获取上传结果
key string 持有此字段用以上传歌曲,详情参见“上传歌曲”
OSSAccessKeyId string 持有此字段用以上传歌曲,详情参见“上传歌曲”
policy string 持有此字段用以上传歌曲,详情参见“上传歌曲”
sign string 持有此字段用以上传歌曲,详情参见“上传歌曲”
url string 持有此字段用以上传歌曲,此为上传歌曲的地址,详情参见“上传歌曲”

返回举例:

{
	"code": 0,
	"message": "success",
	"data": {
		"channel": "25ff1dbf0d504d65bf1dbf0d50ed65da",
		"key": "in/33441abf7d3f4d3c841abf7d3f2d3c86",
		"OSSAccessKeyId": "LTAI4FjWorTQQBz4EaGzxWhA",
		"policy": "eyJleHBpcmF0aW9uIjoiMjAyMi0wMS0yOVQxMjo0MDoxMi4wMjFaIiwiY29uZGl0aW9ucyI6W1siY29udGVudC1sZW5ndGgtcmFuZ2UiLDAsMTA0ODU3NjAwXSxbImVxIiwiJHgtb3NzLWZvcmJpZC1vdmVyd3JpdGUiLCJ0cnVlIl0sWyJlcSIsIiRrZXkiLCJpbi8zMzQ0MWFiZjdkM2Y0ZDNjODQxYWJmN2QzZjJkM2M4NiJdXX0=",
		"sign": "C15BeQBmiZDfulMN8ZeEE7wut0I=",
		"url": "https://dangoai.oss-accelerate.aliyuncs.com"
	}
}

可能的错误:

code message 描述
-10 余额不足 你没有足够的余额来进行运算,请在开放平台充值后再试。

# 接下来做什么:

在获取到返回结果之后,你可以通过该通道进行上传文件了。

# 上传歌曲

您需要将歌曲上传至团子指定的URL内,为了保证上传成功,请将http头的Content-Type设置为multipart/form-data来上传文件。

# 文件的格式与限制

服务器仅接收12分钟以内的、类型为MP3 / FLAC / WAV的歌曲文件。

请求地址:

POST 动态地址,值为“创建上传通道接口”返回结果中的"url"值。

请求参数:

参数名 类型 必须 默认 描述
x-oss-forbid-overwrite string true 值必须为true,否则上传必定出错。
key string 值为“创建上传通道接口”返回结果中的"key"值。
OSSAccessKeyId string 值为“创建上传通道接口”返回结果中的"OSSAccessKeyId"值。
policy string 值为“创建上传通道接口”返回结果中的"policy"值。
Signature string 值为“创建上传通道接口”返回结果中的"sign"值,请注意此参数名为“Signature”,而“创建上传通道接口”返回结果的字段名为“sign”。
file File 要上传的文件,字段名必须为file否则服务器无法识别。该字段必须在表单最后的位置。

注意

请求举例:

POST https://dangoai.oss-accelerate.aliyuncs.com
请使用"multipart/form-data"模式调用此接口。
(即:将请求头的"Content-Type"的值设置为"multipart/form-data")。

formdata: {
	"x-oss-forbid-overwrite": "true",
	"key": "in/33441abf7d3f4d3c841abf7d3f2d3c86",
	"OSSAccessKeyId": "bcAI4FjWorcQQBzbEaGzx5hA",
	"policy": "eyJleHBpcmF0aW9hIjoiMjAyMi0wMS0yOVQxMjo0MDoxMi4wMjFaIiwiY29uZal0aW9ucyI6W1siY29udGVudC1sZW5ndGgtcmFuZ2UiLDAsMTA0ODt3NjAwXSxbImVxIiwiJHgtb3NzLWZvcmJpZC1vdmVyd3JpdGUiLCJ0cnVlIl0sWyJlcSIsIiRrZXkiLCJpbi8zMzQ0MWFiZjdkM2Y0ZDNjODQxYWJmN2QzZjJkM2M4NiJdXX0=",
	"Signature": "C15BeQBmiZDfulMN8ZeEE7wut0I=",
	"file": <FILE>
}

返回结果:

(无返回,即便有,请勿解析返回结果,查询歌曲是否上传成功、以及获取歌曲的处理情况请参考开始处理歌曲)

# 接下来做什么:

当上传文件到指定URL后,即可请求团子开始处理歌曲了。

# 开始处理歌曲

您上传的歌曲位置并非在团子的服务器内,而是上传到了阿里云的OSS(一种类似云盘)上。故上传完歌曲后需要调用此接口用以检查歌曲,并启动歌曲的处理。

本接口可以查询一首歌的上传结果,并开始处理这首歌。验证歌曲是否有效,余额是否可用,且返回歌曲的ID,持有歌曲ID即可查询歌曲处理情况以及下载歌曲。

注意

  • 一旦调用此接口,您就会开始扣除点数余额,如歌曲时长小于30秒,则扣除12点免费点数,否则扣除60 ~ 120点付费点数,具体的,请点击此页面 (opens new window),并在页面右上角找到工具与价格信息按钮并点击查看。
  • 如本请求返回错误(如您的余额不足),请重新创建通道并重新上传歌曲,一条通道只能使用一次

请求地址:

POST https://api.dango.ai/vocal-remover/upload/{channel}/result

请求参数:

参数名 类型 必须 默认 描述
channel string url参数,指32位长度字符串的上传通道,请通过创建上传通道获取。

请求举例:

POST https://api.dango.ai/vocal-remover/upload/25ff1dbf0d504d65bf1dbf0d50ed65da/result

返回结果:

参数名 类型 必须 默认 描述
(根) string 返回的歌曲musicId(32位长度),请妥善保存此ID以方便后面的下载歌曲等操作。

返回举例:

{
	"code": 0,
	"message": "success",
	"data": "33441abf7d3f4d3c841abf7d3f2d3c86"
}

可能的错误:

code message 描述
-10 余额不足 你没有足够的余额来进行运算,请充值后再试。
-1 暂不支持的文件格式,请上传常见的歌曲类型(如MP3、FLAC等) 文件格式有问题,请上传支持的文件格式,或者你的歌曲文件可能损坏。
-1 上传的歌曲不允许超过12分钟,请考虑裁剪音频文件 歌曲过长,超过12分钟,请参考文件的格式与限制
-100 - 参数错误,或通道不存在等其他原因。

# 接下来做什么:

歌曲上传成功后,稍等约2 ~ 3分钟即可处理完成(这取决于歌曲的长度)。 这期间您可以通过轮询查询歌曲处理情况

# 查询歌曲处理情况

通过本接口你可以获取到歌曲的状态(是否处理完成),以及歌曲的一些基本信息。

为了同时节省双方服务的带宽,一首歌根据时长最少也要 40 秒左右才会出现结果,所以在轮询本接口时可以添加一个 40 到 60 秒的延迟(即过了延迟时间再开始轮询),轮询频率请保持为 5 秒以上,否则可能触发服务器自动限流导致服务被暂停使用。

请求地址:

POST https://api.dango.ai/vocal-remover/{musicId}

请求参数:

参数名 类型 必须 默认 描述
musicId string url参数。音乐的ID,这个字段通过开始处理歌曲接口返回的。
此接口支持查询多个内容,您可以在多个ID直接用英文逗号隔开。

请求举例:

POST https://api.dango.ai/vocal-remover/33441abf7d3f4d3c841abf7d3f2d3c86
查询歌曲ID"33441abf7d3f4d3c841abf7d3f2d3c86"的歌曲信息

POST https://api.dango.ai/vocal-remover/33441abf7d3f4d3c841abf7d3f2d3c86,25ff1dbf0d504d65bf1dbf0d50ed65da
查询歌曲ID"334...""25f..."的歌曲信息

返回结果:

参数名 类型 必须 默认 描述
status int 歌曲当前处理状态。请参考歌曲状态
length int 歌曲的长度(秒)
name string 歌曲的文件名(上传时由您提供的)
loseless boolean 歌曲是否为无损歌曲
download int 歌曲剩余下载次数
cost int 歌曲本次扣除的付费点数,如歌曲时长小于30秒,则此字段无意义。

# 歌曲状态

状态号 描述
0 歌曲仍在处理中
1 歌曲处理失败
通常代表歌曲格式有问题。如果一首歌两次以上出现这个状态,可以联系我们进行排查。
歌曲处理失败则会退回费用,不收费
2 歌曲处理成功,可以下载了

返回举例:

{
    "code": 0,
    "message": "success",
    "data": {
        "status": 2,
        "length": 137,
        "name": "七里香.mp3",
        "loseless": false,
        "download": 7,
	    "cost": 60
    }
}

可能的错误:

code message 描述
-10 歌曲已过期 歌曲已过期30天,已从服务器上永久删除无法获取信息。
-1 歌曲不存在 请检查musicId是否有误。

# 接下来做什么:

如果歌曲处理成功,您就可以下载它了,如果歌曲处理失败,您的点数将返回,不会扣费。

# 下载歌曲

当处理成功时,请及时将歌曲下载到您本身的数据存储中,团子只会暂存歌曲 30 天,过期后会删除。

下载歌曲时请确保歌曲status2,否则歌曲无法下载。查询歌曲状态请参考查询歌曲信息

下载歌曲会扣除一次下载次数下载次数每首歌为7次,除特殊情况恕不进行补充,请根据您的需求斟酌下载,下载次数的查询请参考查询歌曲信息

请求地址:

POST https://api.dango.ai/vocal-remover/{musicId}/download/default/{extType}/{item}

请求参数:

参数名 类型 必须 默认 描述
musicId string url参数。音乐的ID,这个字段通过开始处理歌曲后返回的。
extType string url参数。下载的文件类型,可为mp3flac。其中flac类型必须上传时是WAV/FLAC类型才可以选择,如果上传的文件是MP3类型,选择flac会下载失败。
item string url参数。下载的文件,可为instrumental(仅伴奏)、vocals(仅人声)和4stems(四音轨,仅限多轨提取算法)。其中四音轨下载(4stems)较为特殊,为zip包格式,包含4个音轨文件,文件的格式根据extType为MP3或flac格式。

请求举例:

POST https://api.dango.ai/vocal-remover/cd038fd3c62b441a838fd3c62b941a84/download/default/mp3/instrumental
解释:下载MP3格式的伴奏,音乐ID为cd038fd3c62b441a838fd3c62b941a84。

POST https://api.dango.ai/vocal-remover/cd038fd3c62b441a838fd3c62b941a84/download/default/flac/vocals
解释:下载FLAC格式的人声,音乐ID为cd038fd3c62b441a838fd3c62b941a84。

返回结果:

参数名 类型 必须 默认 描述
url string 下载地址,请在20分钟内下载,否则超时该链接将失效。20分钟内重复下载此URL不扣除下载次数。
download int 剩余下载次数,也可以通过查询歌曲信息来手动查询剩余下载次数。

返回举例:

{
    "code": 0,
    "message": "success",
    "data": {
        "url": "http://dangoai.oss-cn-hangzhou.aliyuncs.com/out/cd038fd3c62b441a838fd3c62b941a84/320_伴奏.mp3",
        "download": 6
    }
}

可能的错误:

code message 描述
-1 无法下载的文件 你的歌曲为MP3格式,并非无损歌曲,故无法下载FLAC文件格式的歌曲。
-1 歌曲仍在准备中 歌曲正在处理中,或歌曲处理失败,请确保status2时再下载歌曲。
-1 已经超过最大下载次数 7 次下载次数已用完。请注意,这是不应该出现的问题,出现此问题请考虑您的软件与产品系统设计问题,团子并非“云硬盘”,您的歌曲会过期永久删除,故请将歌曲下载到您的项目/产品里。
-1 当前模型没有4音轨模式 只有“多轨提取算法”支持下载4stems模式的文件。
最后更新时间: 2/9/2022, 3:36:24 AM