# 使用场景和限制
# 使用场景（仅供参考）
- 某音乐软件使用团子的“伴奏提取”功能，处理了大量歌曲，将其数据库内的歌曲提前消音化，并在此之上提供“K歌”功能。 某提供伴奏制作的工作室网站，对接了团子的 API 服务，并在此之上二次包装，并自己定制收费规则，来达到盈利的效果。
# 限制
- 由于团子伴奏提取的 AI 系统极其复杂，不支持对实时性要求较高的业务，适合需要处理大量音乐文件并转为伴奏、且对实时性要求不强的的业务，因为AI需要载入一整首歌曲来进行学习处理（AI的注意力机制），无法把歌曲进行分割，否则可能出现每一段的处理效果都不同的问题。 请勿过快调用接口，以免被自动限制，本页面全部接口限制最大QPS（每秒可调用接口次数）：5次
# 创建上传通道
上传通道（channel） 创建通道不会扣费，只会预测余额是否不足且传递一些配置信息。
请求地址：
POST https://api.tuanziai.com/vocal-remover/upload/channel
请求参数：
2 # 歌曲配置
参数名 类型 必须 默认 描述 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伴奏人声提取算法 27 团子10.0更好人声提取算法 28 团子10.0和声保留算法请求举例：
POST https://api.tuanziai.com/vocal-remover/upload/channel
{
"uploadVersion": 2,
"style": 28,
"filename": "test.mp3",
"config": {
"drumEnhance": false,
"recoverLite": 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。
urlform # 如何创建表单
您需要构建一个http表单（而非和团子其他请求那样的JSON）
formfile # 文件的格式与限制
MP3FLACWAV 请求地址：
POST 动态地址，值为“创建上传通道接口”返回结果中的"url"值。
请求参数：
file Invalid PolicyFieldItemTooLong 请求举例：
POST https://dangoai.oss-accelerate.aliyuncs.com
请使用表单模式调用此接口（"multipart/form-data"）。
<formdata>:
"xxxx": "xxxx",
"xxxx": "xxxx",
"xxxx": "xxxx",
"file": <FILE>
返回结果：
(无返回，即便有，也无任何意义，无需解析此返回结果。查询歌曲是否上传成功、以及获取歌曲的处理情况请参考开始处理歌曲)
# 接下来做什么：
当上传文件到指定URL后，即可请求团子开始处理歌曲了。
# 开始处理歌曲
您上传的歌曲位置并非在团子的服务器内，而是上传到了阿里云的OSS（一种类似云盘）上。故上传完歌曲后需要调用此接口用以检查歌曲，并启动歌曲的处理。
本接口可以查询一首歌的上传结果，并开始处理这首歌。验证歌曲是否有效，余额是否可用，且返回歌曲的ID，持有歌曲ID即可查询歌曲处理情况以及下载歌曲。
12点免费点数60 ~ 120点付费点数工具与价格信息 请求地址：
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 - 参数错误，或通道不存在等其他原因。# 接下来做什么：
轮询 # 查询歌曲处理情况
通过本接口你可以获取到歌曲的状态（是否处理完成），以及歌曲的一些基本信息。
为了同时节省双方服务的带宽，一首歌根据时长最少也要 20 秒左右才会出现结果，所以在轮询本接口时可以添加一个 20 到 40 秒的延迟（即过了延迟时间再开始轮询），轮询频率请保持为 3 秒以上，否则可能触发服务器自动限流导致服务被暂停使用。
请求地址：
POST https://api.tuanziai.com/vocal-remover/{musicId}
请求参数：
英文逗号 请求举例：
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 天，过期后会删除。
2 下载次数下载次数7下载次数 返回的下载地址将在 15 分钟后过期，请及时下载。
请求地址：
POST https://api.tuanziai.com/vocal-remover/{musicId}/download/{modelType}/{extType}/{item}
请求参数：
defaultconserveaggressivedefaultmp3flacinstrumentalvocals 请求举例：
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
}
}
可能的错误：
2
Facebook刷粉
TikTok刷粉
Telegram刷粉
