callBackUrl 参数设置回调URL。当任务完成时,系统会自动将结果推送到您指定的地址。
回调机制概述
回调机制免除了轮询API获取任务状态的需要。系统会主动将任务完成结果推送到您的服务器。根据请求时指定的
type 参数,回调数据结构会有所不同。回调时机
系统会在以下情况发送回调通知:- 人声分离完成
- 人声分离任务失败
- 任务处理过程中发生错误
人声分离只有一个回调阶段,但根据分离类型(
separate_vocal 或 split_stem)会提供不同数量的分离音频文件URL回调方法
- HTTP方法: POST
- Content Type: application/json
- 超时设置: 15秒
回调请求格式
当任务完成时,系统会按以下格式向您的callBackUrl 发送POST请求。回调数据结构根据请求的 type 参数而异:
状态码说明
回调状态码,表示任务处理结果:
状态消息,提供详细的状态描述
任务ID,与您提交任务时返回的taskId一致
人声分离结果信息,成功时返回。字段根据分离类型而异
separate_vocal 类型字段
原始音频文件URL
分离出的人声音频文件URL
分离出的伴奏音频文件URL(无人声)
split_stem 类型字段
原始音频文件URL
分离出的人声音频文件URL
分离出的背景人声音频文件URL
分离出的鼓声音频文件URL
分离出的贝斯音频文件URL
分离出的吉他音频文件URL
分离出的键盘音频文件URL
分离出的打击乐器音频文件URL
分离出的弦乐器音频文件URL
分离出的合成器音频文件URL
分离出的音效音频文件URL
分离出的铜管乐器音频文件URL
分离出的木管乐器音频文件URL
split_stem_advanced 类型字段
原始音频的分离结果数组,包含多个音轨组的提取和移除信息。每个元素代表一个独立的音轨组(如 Lead Vocal)。
提取出的指定音轨信息(保留该音轨,移除其他)。
提取音频的时长,单位为秒。
提取出的指定音轨音频文件的下载地址。
音轨类型分组名称(如 Lead Vocal),表示该组提取的是哪种类型的音轨。
提取音频的唯一标识符。
移除指定音轨后的剩余音频信息(移除该音轨,保留其他)。
移除后音频的时长,单位为秒。
移除指定音轨后剩余音频文件的下载地址。
音轨类型分组名称(如 Lead Vocal),与对应的 extract 保持一致。
移除后音频的唯一标识符。
回调接收示例
以下是各种流行编程语言接收回调的示例代码,支持两种分离类型:- Node.js
- Python
- PHP
最佳实践
故障排除
如果您没有收到回调通知,请检查以下几点:网络连接问题
网络连接问题
- 确认回调URL能够从公网访问
- 检查防火墙设置,确保入站请求未被阻止
- 验证域名解析是否正确
服务器响应问题
服务器响应问题
- 确保服务器在15秒内返回HTTP 200状态码
- 检查服务器日志是否有错误信息
- 验证接口路径和HTTP方法是否正确
人声分离问题
人声分离问题
- 确认源音频ID是否有效
- 检查源音频格式是否支持分离
- 验证任务ID和音频ID的匹配关系
- 确认请求时是否正确设置了
type参数 - 注意某些音乐类型可能分离效果较差
文件下载问题
文件下载问题
- 确认各个分离文件URL是否可访问
- 检查下载权限和网络连接
- 验证文件保存路径和磁盘空间
- 注意同时下载多个文件可能需要较长时间
- 检查是否有部分文件下载失败
split_stem类型产生的文件较多,确保有足够的存储空间
分离类型识别问题
分离类型识别问题
- 确认回调处理逻辑能正确识别两种分离类型
- 检查是否正确处理了不同类型的字段结构
- 验证文件命名和存储逻辑是否适配两种类型
替代方案
如果您无法使用回调机制,也可以使用轮询方式:轮询查询结果
使用获取人声分离详情接口定期查询任务状态。建议每30秒查询一次。
