# 任意乐器分离
# 使用场景和限制
# 使用场景（仅供参考）
- 某吉他音乐网站通过团子任意乐器分离制作大量无吉他歌曲吸引弹奏用户付费下载自行弹奏。
- 某乐器学习相关APP，集成团子的任意乐器分离功能供用户实时分离乐器，并在此之上自行定制收费规则，来达到盈利的效果。
# 限制
- 由于团子任意乐器分离的 AI 系统极其复杂，不支持对实时性要求较高的业务，适合需要处理大量音乐文件并分离乐器、且对实时性要求不强的的业务。
- 请勿过快调用接口，以免被自动限制，本页面全部接口限制最大QPS（每秒可调用接口次数）：5次
# 创建上传通道
在使用团子上传歌曲之前，你必须创建一条临时一次性的上传通道（channel），你可以在通道里提交即将上传的文件的选项，当服务器确认无误后将返回该通道的信息，持有这些信息就可以上传歌曲了。
创建通道不会扣费，只会预测余额是否不足且传递一些配置信息。
请求地址：
POST https://api.tuanziai.com/stem-separator/upload/channel
请求参数：
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| uploadVersion | int | 是 | 上传行为版本号，固定为2，必填，否则无法上传。 | |
| filename | string | 是 | 必填 | 歌曲的文件名（需要包含扩展名，如"1.mp3"） |
| stems | array | 是 | 必填 | 希望提取的音轨，为数组类型，数组内容请参考音轨信息 |
| config | object | 是 | 必填 | (目前需要必填) 设置，其中必须固定为{"unlock": true} |
# 音轨信息
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| name | string | 是 | 必填 | 音轨英文名，可以为预设（详见团子预设的音轨)中的一个 |
| cname | string | 是 | 必填 | 音轨中文名，同上，可以和name匹配也可以自由填写，cname将会作为您最终输出的文件名，如您将某个音轨cname设置为“test”，那么输出的文件的文件名将为“320_test.mp3”或"test.flac" |
| separateFromOrigin | boolean | 否 | false | 不推荐非高级用户使用，以免出现不可控的音质结果。独立分离此音轨，从“原曲”而不是上一条模型的“伴奏”中分离歌曲。启用后，部分歌曲可能会提高该乐器识别与提取能力，但会导致“其他”（伴奏）轨可能出现大幅度乐器残留问题或相位抵消问题，适合更需要“更好的乐器”而不是“更好的伴奏”时使用。 |
| revertModel | boolean | 否 | false | （仅限模型支持revertable=1的）使 AI 有限的算力更倾向于生成“更好的伴奏”而不是生成“更好的乐器”，启用后将进一步减少伴奏中乐器的残留，但副作用是会让“乐器轨”有轻微伴奏残留。如果您更在意“伴奏”的音质（如需要清晰伴奏用来演奏时），而不是分离出来的“乐器”的音质（如需要清晰乐器用来扒谱时），推荐勾选此选项，否则请勿勾选以免“乐器轨”音质降低。 |
# 预设音轨
这些音轨是团子内置的、预设的音轨，您可以直接使用这些音轨提取能力。
这些音轨可能无法和官网保持最新（尽管我们尽可能保持此文档更新），进一步的您也可以调用获取最新音轨接口获取最新的音轨列表。
| name | cname | 版本 |
|---|---|---|
| drums2 | 鼓组 | 2 |
| vocals4 | 人声 | 4 |
| bass2 | 贝斯 | 2 |
| erhu | 二胡 | 1 |
| e-guitar4 | 电吉他 | 4 |
| a-guitar4 | 木吉他 | 4 |
| piano3 | 钢琴 | 3 |
| sax3 | 萨克斯或号 | 3 |
| flute3 | 笛子 | 3 |
| string3 | 提琴 | 3 |
| 2 | ||
| 3 | ||
| 3 | ||
| 3 | ||
| 1 | ||
| 1 | ||
| 1 | ||
| 1 | ||
| 1 | ||
| 2 | ||
| 2 | ||
| 2 | ||
| 2 |
请求举例：
POST https://api.tuanziai.com/stem-separator/upload/channel
// 希望从song.mp3中分离出“鼓组”、“人声”和“其他”三条轨道
{
"filename": "song.mp3",
"stems": [
{"name": "drums", "cname": "鼓组", "separateFromOrigin": false, "revertModel": false},
{"name": "vocals", "cname": "人声", "separateFromOrigin": false, "revertModel": false}
],
"config": {"unlock": true}
}
返回结果：
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| channel | string | 是 | 上传的通道号，持有此通道号用来获取上传结果。 | |
| url | string | 是 | 上传歌曲的目标地址，详情参见“上传歌曲”。 | |
| form | object | 是 | 上传表单，持有此字段用以上传歌曲，详情参见“上传歌曲”。 |
返回举例：
{
"code": 0,
"message": "success",
"data": {
"channel": "25ff1dbf0d504d65bf1dbf0d50ed65da",
"url": "https://dangoai.oss-accelerate.aliyuncs.com",
"form": {
"xxxxx": "xxxxx", // 请将此字段作为表单的键值对
"xxxxx": "xxxxx",
"xxxxx": "xxxxx"
}
}
}
可能的错误：
| code | message | 描述 |
|---|---|---|
| -10 | 余额不足 | 你没有足够的余额来进行运算，请在开放平台充值后再试。 |
# 接下来做什么：
在获取到返回结果之后，你可以通过该通道进行上传文件了。
# 上传歌曲
v1接口停止服务通知
上传行为已升级为v2版本（当前页面所展示的），v1版本将于2025年6月1日后停止服务，请尽快升级您的代码，详细请参考上传文件接口v1迁移至v2。
您需要将歌曲上传至团子指定的动态URL内，该URL取自创建上传通道返回的url字段，同时还需要在上传文件时携带动态的表单信息，该信息取自创建上传通道返回的form字段。
# 如何创建表单
您需要构建一个http表单（而非和团子其他请求那样的JSON）
创建上传通道返回的form字段为object类型，包含多个键与值，您无需关心其内容，仅需将这些键值对作为表单的键值对，同时在表单的最后一位添加一个file字段，值为要上传的文件。
# 文件的格式与限制
服务器仅接收12分钟以内的、类型为MP3 / FLAC / WAV的歌曲文件。
请求地址：
POST 动态地址，值为“创建上传通道接口”返回结果中的"url"值。
请求参数：
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| form的键1 | ... | ... | ... | form的值1 |
| form的键2 | ... | ... | ... | form的值2 |
| ... | ... | ... | ... | ... |
| 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"）。
<formdata>:
"xxxx": "xxxx",
"xxxx": "xxxx",
"xxxx": "xxxx",
"file": <FILE>
返回结果：
(无返回，即便有，也无任何意义，无需解析此返回结果。查询歌曲是否上传成功、以及获取歌曲的处理情况请参考开始处理歌曲)
# 接下来做什么：
当上传文件到指定URL后，即可请求团子开始处理歌曲了。
# 开始处理歌曲
您上传的歌曲位置并非在团子的服务器内，而是上传到了阿里云的OSS（一种类似云盘）上。故上传完歌曲后需要调用此接口用以检查歌曲，并启动歌曲的处理。
本接口可以查询一首歌的上传结果，并开始处理这首歌。验证歌曲是否有效，余额是否可用，且返回歌曲的ID，持有歌曲ID即可查询歌曲处理情况以及下载歌曲。
注意
- 一旦调用此接口，您就会开始扣除点数余额，将根据歌曲时长和通道数量进行扣费，具体请点击此页面 (opens new window)，并在页面右上角找到
工具与价格信息按钮并点击查看。 - 如本请求返回错误（如您的余额不足），请重新创建通道并重新上传歌曲，一条通道只能使用一次。
请求地址：
POST https://api.tuanziai.com/stem-separator/upload/{channel}/result
请求参数：
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| channel | string | 是 | url参数，指32位长度字符串的上传通道，请通过创建上传通道获取。 |
请求举例：
POST https://api.tuanziai.com/stem-separator/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/stem-separator/{musicId}
请求参数：
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| musicId | string | 是 | url参数。音乐的ID，这个字段通过开始处理歌曲接口返回的。 此接口支持查询多个内容，您可以在多个ID直接用 英文逗号隔开。 |
请求举例：
POST https://api.tuanziai.com/stem-separator/33441abf7d3f4d3c841abf7d3f2d3c86
查询歌曲ID为"33441abf7d3f4d3c841abf7d3f2d3c86"的歌曲信息
POST https://api.tuanziai.com/stem-separator/33441abf7d3f4d3c841abf7d3f2d3c86,25ff1dbf0d504d65bf1dbf0d50ed65da
查询歌曲ID为"334..."和"25f..."的歌曲信息
返回结果：
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| status | int | 是 | 歌曲当前处理状态。请参考歌曲状态 | |
| length | int | 是 | 歌曲的长度（秒） | |
| name | string | 是 | 歌曲的文件名（上传时由您提供的） | |
| lossless | boolean | 是 | 歌曲是否为无损歌曲 | |
| downloadCount | int | 是 | 歌曲剩余下载次数 | |
| cost | int | 是 | 歌曲本次扣除的付费点数，如歌曲时长小于30秒，则此字段无意义。 | |
| stems | string | 是 | 歌曲包含的音轨，注意为string类型，如需读取，需手动解析其中json内容 |
# 歌曲状态
| 状态号 | 描述 |
|---|---|
| 0 | 歌曲仍在处理中 |
| 1 | 歌曲处理失败 通常代表歌曲格式有问题。如果一首歌两次以上出现这个状态，可以联系我们进行排查。 歌曲处理失败则会退回费用，不收费 |
| 2 | 歌曲处理成功，可以下载了 |
返回举例：
{
"code": 0,
"message": "success",
"data": {
"status": 2,
"length": 137,
"name": "七里香.mp3",
"lossless": false,
"downloadCount": 7,
"cost": 60,
"stems": "[{\"name\":\"bass\",\"cname\":\"贝斯\"}]"
}
}
可能的错误：
| code | message | 描述 |
|---|---|---|
| -10 | 歌曲已过期 | 歌曲已过期30天，已从服务器上永久删除无法获取信息。 |
| -1 | 歌曲不存在 | 请检查musicId是否有误。 |
# 接下来做什么：
如果歌曲处理成功，您就可以下载它了，如果歌曲处理失败，您的点数将返回，不会扣费。
# 下载歌曲
当处理成功时，请及时将歌曲下载到您本身的数据存储中，团子只会暂存歌曲 30 天，过期后会删除。
下载歌曲时请确保歌曲status为2，否则歌曲无法下载。查询歌曲状态请参考查询歌曲信息。
下载歌曲会扣除一次下载次数，下载次数每首歌为7次，除特殊情况恕不进行补充，请根据您的需求斟酌下载，下载次数的查询请参考查询歌曲信息。
返回的下载地址将在 15 分钟后过期，请及时下载。
请求地址：
POST https://api.tuanziai.com/stem-separator/{musicId}/download/@zip/{extType}
请求参数：
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| extType | string | 是 | url参数。下载的文件类型，可为mp3和flac。其中flac类型必须上传时是WAV/FLAC类型才可以选择，如果上传的文件是MP3类型，选择flac会下载失败。 |
请求举例：
POST https://api.tuanziai.com/stem-separator/cd038fd3c62b441a838fd3c62b941a84/download/@zip/mp3
解释：下载MP3格式的结果文件（为压缩包格式，内为全部音轨文件），音乐ID为cd038fd3c62b441a838fd3c62b941a84。
返回结果：
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| url | string | 是 | 下载地址，请在20分钟内下载，否则超时该链接将失效。20分钟内重复下载此URL不扣除下载次数。 | |
| downloadCountLeft | int | 是 | 剩余下载次数，也可以通过查询歌曲信息来手动查询剩余下载次数。 |
返回举例：
{
"code": 0,
"message": "success",
"data": {
"url": "http://dangoai.oss-cn-hangzhou.aliyuncs.com/out/cd038fd3c62b441a838fd3c62b941a84/all.zip",
"downloadCountLeft": 6
}
}
可能的错误：
| code | message | 描述 |
|---|---|---|
| -1 | 无法下载的文件 | 你的歌曲为MP3格式，并非无损歌曲，故无法下载FLAC文件格式的歌曲。 |
| -1 | 歌曲仍在准备中 | 歌曲正在处理中，或歌曲处理失败，请确保status为2时再下载歌曲。 |
| -1 | 已经超过最大下载次数 | 7 次下载次数已用完。请注意，这是不应该出现的问题，出现此问题请考虑您的软件与产品系统设计问题，团子并非“云硬盘”，您的歌曲会过期永久删除，故请将歌曲下载到您的项目/产品里。 |
# 下载的压缩文件格式
下载的压缩文件格式为zip，内部为全部音轨文件，下载的MP3和FLAC在压缩目录的文件夹结构上相同，但文件名不同，具体如下：
# MP3音轨的压缩包：
下载的zip包
├── [musicID] 以32位长度的musicID命名的文件夹
│ ├── 320_贝斯.mp3 贝斯音轨，其中的“贝斯”名是您上传的CNAME决定的，如果您上传的CNAME是“Bass”，那么这里的文件名就是“320_Bass.mp3”
│ ├── 320_其他.mp3 其他音轨，该音轨为“不包含”上述乐器的伴奏轨，名称固定。
# FLAC音轨的压缩包：
下载的zip包
├── [musicID] 以32位长度的musicID命名的文件夹
│ ├── 贝斯.flac 贝斯音轨，详情同上，注意该文件没有“320_”的前缀
│ ├── 其他.flac 其他音轨，详情同上，注意该文件没有“320_”的前缀
您可以下载压缩包到本地，并自行完成解压缩，至此为止您已获取团子的全部分离文件，接下来您就可以和自己的产品与创意进行对接，感谢您的使用。
# 获取最新音轨（可选）
团子的提取能力会随着时间的推移而不断提升，也会推出新的算法，您可以通过此接口来获取最新的全部提取能力。
如果您需要包装整个团子的“任意乐器分离”能力，可以考虑本接口。
如果您只需要固定的几种音轨（比如只需要贝斯、鼓组提取能力），这些音轨可能也会随着时间更新，name会发生改变，如鼓组一代算法的name是drums，一代已经废弃二代算法name改为drums2，仍然使用一代算法可能会在未来不支持导致上传失败，您也可以通过此接口来获得最新的算法名称，来增强提取能力。
请求地址：
POST https://api.tuanziai.com/stem-separator/stems
请求参数：
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| experimental | boolean | 否 | false | 默认false。获取实验性音轨（如木吉他（激进）、钢琴（保守）等），这些音轨为实验性的，可能提取质量有问题，无必要使用这些音轨可以置为false或不填写 |
请求举例：
POST https://api.tuanziai.com/stem-separator/stems
{
"experimental": false
}
返回结果（返回为数组类型，以下展示数组内元素的含义）：
| 参数名 | 类型 | 必须 | 默认 | 描述 |
|---|---|---|---|---|
| name | string | 是 | 音轨的name，唯一，不同版本即便cname相同此字段也不相同。 | |
| cname | string | 是 | 音轨的cname，中文名，不唯一，但固定（如1代鼓组和2代鼓组算法都叫“鼓组”） | |
| old | int | 是 | 该算法是否已经过期，1-已过期，0-最新的 | |
| status | int | 是 | 该算法是否可用，1-可用，其他-不可用 | |
| revertable | int | 是 | 该算法是否支持生成“更好的伴奏”而不是生成“更好的乐器”，1-支持，0-不支持，支持的模型在上传时可以配置该音轨的revertModel=true来获得更好的伴奏 |
返回举例：
{
"code": 0,
"message": "success",
"data": [
{
"id": 1,
"name": "drums",
"cname": "鼓组",
"keyword": "鼓点,guzu,gudian",
"description": "已过时，推荐使用新版算法，提供更少的残留和更清晰的提取",
"revert": 0,
"type": 0,
"publicModel": 3,
"version": 1,
"status": 1,
"revertable": 0,
"experimental": 0,
"old": 1,
"iconType": "drums"
},
{
"id": 186,
"name": "vocals2",
"cname": "人声",
"keyword": "语音,yuyin,rensheng",
"description": "从音乐或说话的场景中分离出人声，但分离的效果不如“伴奏人声提取”的分离效果好，此轨道仅能提供最基本的人声分离功能",
"revert": 0,
"type": 0,
"publicModel": 3,
"version": 2,
"status": 1,
"revertable": 0,
"experimental": 0,
"old": 0,
"iconType": "vocals",
"demo": "vocals"
},
...(过多，省略)
]
}
提示：
name和cname的区别：name是唯一的，cname不唯一，但固定，如1代鼓组和2代鼓组算法都叫“鼓组”，但name不同。- 进一步的，如果您需要“最新的鼓组算法”，可以在返回结果中查找
cname=鼓组、old=0、status=1的算法，一定能查找到一个唯一的算法，即为最新的鼓组算法。