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

回调机制概述

回调机制无需轮询API查询任务状态,系统会主动将任务完成结果推送到您的服务器。

回调时机

系统会在以下情况发送回调通知:
  • 人声分离任务成功完成
  • 人声分离任务失败
  • 任务处理过程中发生错误

回调方式

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

回调请求格式

任务完成时,系统会根据您选择的分离类型发送不同格式的回调数据:

状态码说明

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. 文件管理: 分离后的音频文件下载和处理应在异步任务中进行
  7. 类型判断: 根据返回字段判断分离类型,采用相应的处理逻辑

重要提醒

  • 回调URL必须是公网可访问的地址
  • 服务器必须在15秒内响应,否则视为超时
  • 连续3次重试失败后,系统将停止发送回调
  • 请确保回调处理逻辑的稳定性,避免因异常导致回调失败
  • 生成的音频文件URL可能有时效限制,建议及时下载保存
  • split_stem 模式会产生更多文件,注意存储空间管理
  • 确保源音频文件包含对应的音乐成分以获得最佳分离效果
  • 不同分离类型的回调结构不同,需要相应的处理逻辑

故障排查

如果您没有收到回调通知,请检查以下内容:
  • 确认回调URL可以从公网访问
  • 检查防火墙设置,确保不会阻拦入站请求
  • 验证域名解析是否正确
  • 确保服务器在15秒内返回HTTP 200状态码
  • 检查服务器日志是否有错误信息
  • 验证接口路径和HTTP方法是否正确
  • 确认接收到的POST请求体为JSON格式
  • 检查Content-Type是否为application/json
  • 验证JSON解析是否正确
  • 确保能正确处理不同分离类型的数据结构
  • 确认分离后的音频文件URL是否可访问
  • 检查音频下载权限和网络连接
  • 验证音频保存路径和权限
  • 注意源音频文件质量对分离效果的影响
  • 确认源音频文件格式是否受支持
  • split_stem 模式需要检查更多的音频文件

替代方案

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

轮询查询结果

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