任意乐器分离

使用场景和限制

使用场景（仅供参考）

• 某吉他音乐网站通过团子任意乐器分离制作大量无吉他歌曲吸引弹奏用户付费下载自行弹奏。
• 某乐器学习相关APP，集成团子的任意乐器分离功能供用户实时分离乐器，并在此之上自行定制收费规则，来达到盈利的效果。

限制

• 由于团子任意乐器分离的 AI 系统极其复杂，不支持对实时性要求较高的业务，适合需要处理大量音乐文件并分离乐器、且对实时性要求不强的的业务。
• 请勿过快调用接口，以免被自动限制，本页面全部接口限制最大QPS（每秒可调用接口次数）：5次
• 上传的文件请遵守当地法律法规以及团子的《协议条款》，不得上传侵权文件。

创建上传通道

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

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

请求地址：

POST https://api.tuanziai.com/stem-separator/upload/channel

请求参数：

音轨信息

预设音轨

这些音轨是团子内置的、预设的音轨，您可以直接使用这些音轨提取能力。

这些音轨可能无法和官网保持最新（尽管我们尽可能保持此文档更新），进一步的您也可以调用获取最新音轨接口获取最新的音轨列表。

请求举例：

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}
}

返回结果：

返回举例：

{
	"code": 0,
	"message": "success",
	"data": {
		"channel": "25ff1dbf0d504d65bf1dbf0d50ed65da",
		"url": "https://dangoai.oss-accelerate.aliyuncs.com",
		"form": {
			"xxxxx": "xxxxx", // 请将此字段作为表单的键值对
			"xxxxx": "xxxxx",
			"xxxxx": "xxxxx"
		}
	}
}

可能的错误：

接下来做什么：

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

上传歌曲

您需要将歌曲上传至团子指定的动态URL内，该URL取自创建上传通道返回的url字段，同时还需要在上传文件时携带动态的表单信息，该信息取自创建上传通道返回的form字段。

如何创建表单

您需要构建一个http表单（而非和团子其他请求那样的JSON）

创建上传通道返回的form字段为object类型，包含多个键与值，您无需关心其内容，仅需将这些键值对作为表单的键值对，同时在表单的最后一位添加一个file字段，值为要上传的文件。

文件的格式与限制

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

请求地址：

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

请求参数：

请求举例：

POST https://dangoai.oss-accelerate.aliyuncs.com
请使用表单模式调用此接口（"multipart/form-data"）。

<formdata>
	"xxxx": "xxxx",
	"xxxx": "xxxx",
	"xxxx": "xxxx",
	"file": <FILE>

返回结果：

(无返回，即便有，也无任何意义，无需解析此返回结果。查询歌曲是否上传成功、以及获取歌曲的处理情况请参考开始处理歌曲)

接下来做什么：

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

开始处理歌曲

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

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

请求地址：

POST https://api.tuanziai.com/stem-separator/upload/{channel}/result

请求参数：

请求举例：

POST https://api.tuanziai.com/stem-separator/upload/25ff1dbf0d504d65bf1dbf0d50ed65da/result

返回结果：

返回举例：

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

可能的错误：

接下来做什么：

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

查询歌曲处理情况

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

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

请求地址：

POST https://api.tuanziai.com/stem-separator/{musicId}

请求参数：

请求举例：

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

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

返回结果：

歌曲状态

返回举例：

{
	"code": 0,
	"message": "success",
	"data": {
		"status": 2,
		"length": 137,
		"userFileName": "七里香.mp3",
		"lossless": false,
		"downloadCount": 7,
		"cost": 60,
		"stems": "[{\"name\":\"bass\",\"cname\":\"贝斯\"}]"
	}
}

可能的错误：

接下来做什么：

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

下载歌曲

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

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

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

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

请求地址：

POST https://api.tuanziai.com/stem-separator/{musicId}/download/@zip/{extType}

请求参数：

请求举例：

POST https://api.tuanziai.com/stem-separator/cd038fd3c62b441a838fd3c62b941a84/download/@zip/mp3
解释：下载MP3格式的结果文件（为压缩包格式，内为全部音轨文件），音乐ID为cd038fd3c62b441a838fd3c62b941a84。

返回结果：

返回举例：

{
    "code": 0,
    "message": "success",
    "data": {
        "url": "http://dangoai.oss-cn-hangzhou.aliyuncs.com/out/cd038fd3c62b441a838fd3c62b941a84/all.zip",
        "downloadCountLeft": 6
    }
}

可能的错误：

下载的压缩文件格式

下载的压缩文件格式为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

请求参数：

请求举例：

POST https://api.tuanziai.com/stem-separator/stems

{
	"experimental": false
}

返回结果（返回为数组类型，以下展示数组内元素的含义）：

返回举例：

{
    "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的算法，一定能查找到一个唯一的算法，即为最新的鼓组算法。