Skip to main content
当您向人声和乐器分离API提交任务时,可以使用 callBackUrl 参数设置回调URL。当任务完成时,系统会自动将结果推送到您指定的地址。

回调机制概述

回调机制免除了轮询API获取任务状态的需要。系统会主动将任务完成结果推送到您的服务器。根据请求时指定的 type 参数,回调数据结构会有所不同。

回调时机

系统会在以下情况发送回调通知:
  • 人声分离完成
  • 人声分离任务失败
  • 任务处理过程中发生错误
人声分离只有一个回调阶段,但根据分离类型(separate_vocalsplit_stem)会提供不同数量的分离音频文件URL

回调方法

  • HTTP方法: POST
  • Content Type: application/json
  • 超时设置: 15秒

回调请求格式

当任务完成时,系统会按以下格式向您的 callBackUrl 发送POST请求。回调数据结构根据请求的 type 参数而异:

状态码说明

integer
必填
回调状态码,表示任务处理结果:
string
必填
状态消息,提供详细的状态描述
string
必填
任务ID,与您提交任务时返回的taskId一致
object
人声分离结果信息,成功时返回。字段根据分离类型而异

separate_vocal 类型字段

string
原始音频文件URL
string
分离出的人声音频文件URL
string
分离出的伴奏音频文件URL(无人声)

split_stem 类型字段

string
原始音频文件URL
string
分离出的人声音频文件URL
string
分离出的背景人声音频文件URL
string
分离出的鼓声音频文件URL
string
分离出的贝斯音频文件URL
string
分离出的吉他音频文件URL
string
分离出的键盘音频文件URL
string
分离出的打击乐器音频文件URL
string
分离出的弦乐器音频文件URL
string
分离出的合成器音频文件URL
string
分离出的音效音频文件URL
string
分离出的铜管乐器音频文件URL
string
分离出的木管乐器音频文件URL

split_stem_advanced 类型字段

array
原始音频的分离结果数组,包含多个音轨组的提取和移除信息。每个元素代表一个独立的音轨组(如 Lead Vocal)。
object
提取出的指定音轨信息(保留该音轨,移除其他)。
number
提取音频的时长,单位为秒。
string
提取出的指定音轨音频文件的下载地址。
string
音轨类型分组名称(如 Lead Vocal),表示该组提取的是哪种类型的音轨。
string
提取音频的唯一标识符。
object
移除指定音轨后的剩余音频信息(移除该音轨,保留其他)。
number
移除后音频的时长,单位为秒。
string
移除指定音轨后剩余音频文件的下载地址。
string
音轨类型分组名称(如 Lead Vocal),与对应的 extract 保持一致。
string
移除后音频的唯一标识符。

回调接收示例

以下是各种流行编程语言接收回调的示例代码,支持两种分离类型:

最佳实践

回调URL配置建议

  1. 使用HTTPS: 确保回调URL使用HTTPS协议,保证数据传输安全
  2. 验证来源: 在回调处理中验证请求来源的合法性
  3. 幂等处理: 同一个taskId可能收到多次回调,确保处理逻辑具有幂等性
  4. 快速响应: 回调处理应尽快返回200状态码,避免超时
  5. 异步下载: 多个音频文件下载应在异步任务中进行,避免阻塞回调响应
  6. 存储管理: 合理规划存储空间,split_stem 类型会产生多达12个音频文件
  7. 质量验证: 下载后验证每个文件的完整性和音频质量
  8. 分类存储: 按音频类型(人声、伴奏、乐器等)分类存储文件
  9. 类型判断: 根据回调内容自动判断分离类型,适配不同的处理逻辑

重要提醒

  • 回调URL必须是公网可访问的地址
  • 服务器必须在15秒内响应,否则视为超时
  • 连续3次重试失败后,系统将停止发送回调
  • 请确保回调处理逻辑的稳定性,避免因异常导致回调失败
  • 不同分离类型产生的文件数量差异很大:
    • separate_vocal:2-3个文件(人声、伴奏、可能的原始文件)
    • split_stem:最多12个文件(各种乐器分离)
  • 生成的分离文件将保留14天,建议及时下载保存
  • 分离质量取决于原始音轨的复杂度和音乐风格
  • 所有输出文件均为MP3格式,质量与原始文件相同

故障排除

如果您没有收到回调通知,请检查以下几点:
  • 确认回调URL能够从公网访问
  • 检查防火墙设置,确保入站请求未被阻止
  • 验证域名解析是否正确
  • 确保服务器在15秒内返回HTTP 200状态码
  • 检查服务器日志是否有错误信息
  • 验证接口路径和HTTP方法是否正确
  • 确认源音频ID是否有效
  • 检查源音频格式是否支持分离
  • 验证任务ID和音频ID的匹配关系
  • 确认请求时是否正确设置了 type 参数
  • 注意某些音乐类型可能分离效果较差
  • 确认各个分离文件URL是否可访问
  • 检查下载权限和网络连接
  • 验证文件保存路径和磁盘空间
  • 注意同时下载多个文件可能需要较长时间
  • 检查是否有部分文件下载失败
  • split_stem 类型产生的文件较多,确保有足够的存储空间
  • 确认回调处理逻辑能正确识别两种分离类型
  • 检查是否正确处理了不同类型的字段结构
  • 验证文件命名和存储逻辑是否适配两种类型

替代方案

如果您无法使用回调机制,也可以使用轮询方式:

轮询查询结果

使用获取人声分离详情接口定期查询任务状态。建议每30秒查询一次。