# 伴奏人声提取

# 使用场景和限制

# 使用场景（仅供参考）

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

# 限制

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

# 创建上传通道

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

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

请求地址：

POST https://api.tuanziai.com/vocal-remover/upload/channel

请求参数：

参数名	类型	必须	默认	描述
filename	string	是	必填	歌曲的文件名（需要包含扩展名，如"1.mp3"）
style	int	是	必填	AI算法，请参考歌曲算法
config	object	否		歌曲配置，为对象，对象形式参考歌曲配置

# 歌曲配置

参数名	类型	必须	默认	描述
drumEnhance	boolean	否	false	启用注意力机制。（实验性）仅生效于19号算法的“智能模式”算法、20号算法的“激进模式”算法，22号算法的全部模式，其他算法时填写无效，默认启用。在间奏阶段（即歌曲中无人声仅有伴奏的片段）将削弱人声提取能力，防止 AI 额外将伴奏乐器当成人声消除。但可能影响人声提取效果，关闭此机制可能会缓解某些歌曲人声残留问题。
recoverLite	boolean	否	true	尝试恢复受损鼓组。（实验性）仅生效于19号算法的“智能模式”算法，其他算法时填写无效，默认不启用。如在极少数歌曲中遇到鼓组丢失或发闷问题可以启用，启用后会尝试修复鼓组能量，但可能带来轻微人声残留。
superAggressive	boolean	否	false	超级激进模式。（实验性）仅生效于22号算法的“激进模式”算法，其他算法时填写无效，默认启用。可以更进一步的减少人声中的其他杂音，但可能会轻微丢失部分人声能量或某些类似混响的效果器，建议在默认情况下的”激进“模式仍然有残留时开启。
experimentModel	boolean	否	false	实验性算法。（实验性）仅生效于22号算法的全部模式算法，其他算法时填写无效，默认不启用。实验性的算法在激进模式下可以减少更多的杂音残留，但在嘈杂歌曲下会损坏部分人声。同时，在保守模式下提供更为丰富的人声能量，但可能增加更多杂音残留。

# 歌曲算法

值(int)	描述
18	~~团子7.5和声保留算法（即将废弃，不推荐）~~
19	~~团子8.0伴奏人声提取算法（即将废弃，不推荐）~~
20	~~团子8.0和声保留算法（即将废弃，不推荐）~~
21	团子8.0翻唱元素保留
22	~~团子8.0更好人声提取算法（即将废弃，不推荐）~~
23	~~团子9.0伴奏人声提取算法（即将废弃，不推荐）~~
24	团子9.0更好人声提取算法
25	团子9.0和声保留算法
26	团子10.0伴奏人声提取算法

请求举例：

POST https://api.tuanziai.com/vocal-remover/upload/channel

{
	"style": 5,
	"filename": "test.mp3",
    "config": {
	    "drumEnhance": false,
        "recoverLite": true   
    }   
}

返回结果：

参数名	类型	必须	描述
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`否则服务器无法识别。该字段必须在表单最后的位置。

注意

必须将请求头的"Content-Type"的值设置为"multipart/form-data"
"file"字段必须在表单域最后一位，否则必定出错。
如报错Invalid Policy，代表上传参数有误，请检查上传参数的key-value是否正确，key必须注意大小写
如报错FieldItemTooLong，请将file的文件名改成全英文后再试。
其他问题请自行排查，参考链接：阿里云OSS - 400错误解决方案 (opens new window)，以及阿里云OSS - 调用PostObject接口的常见错误及解决方法 (opens new window)

请求举例：

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.tuanziai.com/vocal-remover/upload/{channel}/result

请求参数：

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

请求举例：

POST https://api.tuanziai.com/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分钟即可处理完成（这取决于歌曲的长度）。这期间您可以通过轮询查询歌曲处理情况。

# 查询歌曲处理情况

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

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

请求地址：

POST https://api.tuanziai.com/vocal-remover/{musicId}

请求参数：

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

请求举例：

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

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

返回结果：

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

# 歌曲状态

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

返回举例：

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

可能的错误：

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

# 接下来做什么：

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

# 下载歌曲

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

下载歌曲时请确保歌曲status为2，否则歌曲无法下载。查询歌曲状态请参考查询歌曲信息。

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

返回的下载地址将在 15 分钟后过期，请及时下载。

请求地址：

POST https://api.tuanziai.com/vocal-remover/{musicId}/download/{modelType}/{extType}/{item}

请求参数：

参数名	类型	必须	描述
musicId	string	是	url参数。音乐的ID，这个字段通过开始处理歌曲后返回的。
modelType	string	是	url参数。团子 DeepClear AI深度人声消除算法，可为`default`（智能）、`conserve`（保守）或`aggressive`（激进），仅支持17、18、19、20、21、22号算法，其他算法请填写`default`。
extType	string	是	url参数。下载的文件类型，可为`mp3`和`flac`。其中flac类型必须上传时是WAV/FLAC类型才可以选择，如果上传的文件是MP3类型，选择flac会下载失败。
item	string	是	url参数。下载的文件，可为`instrumental`（仅伴奏）或`vocals`（仅人声）。

请求举例：

POST https://api.tuanziai.com/vocal-remover/cd038fd3c62b441a838fd3c62b941a84/download/aggressive/mp3/instrumental
解释：下载激进算法下的MP3格式的伴奏，音乐ID为cd038fd3c62b441a838fd3c62b941a84。

POST https://api.tuanziai.com/vocal-remover/cd038fd3c62b441a838fd3c62b941a84/download/default/flac/vocals
解释：下载智能算法下的FLAC格式的人声，音乐ID为cd038fd3c62b441a838fd3c62b941a84。

返回结果：

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

返回举例：

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

可能的错误：

code	message	描述
-1	无法下载的文件	你的歌曲为MP3格式，并非无损歌曲，故无法下载FLAC文件格式的歌曲。
-1	歌曲仍在准备中	歌曲正在处理中，或歌曲处理失败，请确保status为`2`时再下载歌曲。
-1	已经超过最大下载次数	7 次下载次数已用完。请注意，这是不应该出现的问题，出现此问题请考虑您的软件与产品系统设计问题，团子并非“云硬盘”，您的歌曲会过期永久删除，故请将歌曲下载到您的项目/产品里。

← 开始上手无损升降音调 →