callBackUrl
参数设置回调 URL。系统将在任务完成时自动将结果推送到您指定的地址。
回调机制概述
回调机制无需轮询 API 查询任务状态。系统将主动向您的服务器推送任务完成结果。
回调时机
系统将在以下情况发送回调通知:- MIDI 生成任务成功完成
- MIDI 生成任务失败
- 任务处理过程中发生错误
回调方法
- HTTP 方法: POST
- Content Type: application/json
- 超时设置: 15 秒
回调请求格式
当任务完成时,系统将向您的callBackUrl
发送 POST 请求:
状态码说明
回调状态码,指示任务处理结果:
状态码 | 说明 |
---|---|
200 | 成功 - MIDI 生成已成功完成 |
500 | 内部错误 - 请重试或联系技术支持 |
状态消息,提供详细的状态描述
任务 ID,与您提交任务时返回的 task_id 一致
MIDI 生成结果信息,成功时返回
成功响应字段
处理状态。成功时值为
complete
检测到的乐器数组及其 MIDI 音符数据
回调接收示例
以下是使用主流编程语言接收回调的示例代码:- Node.js
- Python
- PHP
最佳实践
回调 URL 配置建议
- 使用 HTTPS: 确保回调 URL 使用 HTTPS 协议以保证数据传输安全
- 验证来源: 在回调处理中验证请求来源的合法性
- 幂等处理: 同一 task_id 可能收到多次回调,确保处理逻辑是幂等的
- 快速响应: 回调处理应快速返回 200 状态码以避免超时
- 异步处理: 复杂的业务逻辑(如 MIDI 文件转换)应异步处理
- 处理缺失乐器: 不是所有乐器都会被检测到 - 优雅地处理空的或缺失的乐器数组
- 存储原始数据: 保存完整的 JSON 响应以供未来参考和重新处理
重要提醒
- 回调 URL 必须可从公网访问
- 服务器必须在 15 秒内响应,否则将被视为超时
- 如果连续 3 次重试失败,系统将停止发送回调
- 请确保回调处理逻辑的稳定性,避免因异常导致回调失败
- MIDI 数据保留 14 天 - 如需长期保存请及时下载保存
- 检测到的乐器数量和类型取决于音频内容
- 音符时间(start/end)可能是字符串或数字 - 需要处理这两种类型
故障排查
如果您没有收到回调通知,请检查以下内容:网络连接问题
网络连接问题
- 确认回调 URL 可从公网访问
- 检查防火墙设置,确保入站请求未被阻止
- 验证域名解析正确
服务器响应问题
服务器响应问题
- 确保服务器在 15 秒内返回 HTTP 200 状态码
- 检查服务器日志是否有错误消息
- 验证端点路径和 HTTP 方法正确
内容格式问题
内容格式问题
- 确认收到的 POST 请求体为 JSON 格式
- 检查 Content-Type 是否为 application/json
- 验证 JSON 解析正确
- 处理时间值的字符串和数字两种类型
数据处理问题
数据处理问题
- 某些乐器可能有空的音符数组
- 并非所有音频都会检测到所有乐器类型
- 验证原始人声分离使用的是
split_stem
类型(而非separate_vocal
) - 检查源 taskId 是否来自成功完成的分离任务
替代方案
如果您无法使用回调机制,也可以使用轮询方式:轮询查询结果
使用获取 MIDI 生成详情接口定期查询任务状态。我们建议每 10-30 秒查询一次。