跳转到主要内容
当您向 Suno API 提交 MIDI 生成任务时,可以使用 callBackUrl 参数设置回调 URL。系统将在任务完成时自动将结果推送到您指定的地址。

回调机制概述

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

回调时机

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

回调方法

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

回调请求格式

当任务完成时,系统将向您的 callBackUrl 发送 POST 请求:

状态码说明

code
integer
必填
回调状态码,指示任务处理结果:
msg
string
必填
状态消息,提供详细的状态描述
task_id
string
必填
任务 ID,与您提交任务时返回的 task_id 一致
data
object
MIDI 生成结果信息,成功时返回

成功响应字段

data.state
string
处理状态。成功时值为 complete
data.instruments
array
检测到的乐器数组及其 MIDI 音符数据

回调接收示例

以下是使用主流编程语言接收回调的示例代码:

最佳实践

回调 URL 配置建议

  1. 使用 HTTPS: 确保回调 URL 使用 HTTPS 协议以保证数据传输安全
  2. 验证来源: 在回调处理中验证请求来源的合法性
  3. 幂等处理: 同一 task_id 可能收到多次回调,确保处理逻辑是幂等的
  4. 快速响应: 回调处理应快速返回 200 状态码以避免超时
  5. 异步处理: 复杂的业务逻辑(如 MIDI 文件转换)应异步处理
  6. 处理缺失乐器: 不是所有乐器都会被检测到 - 优雅地处理空的或缺失的乐器数组
  7. 存储原始数据: 保存完整的 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 秒查询一次。