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

回调机制概述

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

回调时机

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

回调方式

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

回调请求格式

任务完成时,系统会向您的 callBackUrl 发送以下格式的POST请求:

状态码说明

integer
必填
回调状态码,表示任务处理结果:
string
必填
状态消息,提供详细的状态描述
string
必填
回调类型,表示当前回调的阶段:
  • text: 文本生成完成
  • first: 第一首曲目完成
  • complete: 所有曲目完成
  • error: 任务失败
string
必填
任务ID,与您提交任务时返回的taskId一致
array
乐器生成结果信息,成功时返回
string
音频唯一标识符
string
生成的乐器音频文件URL
string
原始乐器音频文件URL
string
流式乐器音频URL
string
原始流式乐器音频URL
string
封面图片URL
string
原始封面图片URL
string
生成提示词,描述乐器特征
string
生成使用的模型名称
string
乐器曲目标题
string
乐器曲目标签
string
创建时间
number
音频时长(秒)

回调接收示例

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

最佳实践

回调URL配置建议

  1. 使用HTTPS: 确保回调URL使用HTTPS协议,保障数据传输安全
  2. 验证来源: 在回调处理中验证请求来源的合法性
  3. 幂等处理: 同一个taskId可能收到多次回调,确保处理逻辑是幂等的
  4. 快速响应: 回调处理应尽快返回200状态码,避免超时
  5. 异步处理: 复杂的业务逻辑应异步处理,避免阻塞回调响应
  6. 音频处理: 音频下载和处理应在异步任务中进行,避免阻塞回调响应

重要提醒

  • 回调URL必须是公网可访问的地址
  • 服务器必须在15秒内响应,否则视为超时
  • 连续3次重试失败后,系统将停止发送回调
  • 请确保回调处理逻辑的稳定性,避免因异常导致回调失败
  • 生成的音频URL可能有时效限制,建议及时下载保存
  • 注意内容合规性,避免因违规导致生成失败

故障排查

如果您没有收到回调通知,请检查以下内容:
  • 确认回调URL可以从公网访问
  • 检查防火墙设置,确保不会阻拦入站请求
  • 验证域名解析是否正确
  • 确保服务器在15秒内返回HTTP 200状态码
  • 检查服务器日志是否有错误信息
  • 验证接口路径和HTTP方法是否正确
  • 确认接收到的POST请求体为JSON格式
  • 检查Content-Type是否为application/json
  • 验证JSON解析是否正确
  • 确认音频URL是否可访问
  • 检查音频下载权限和网络连接
  • 验证音频保存路径和权限
  • 注意音频内容是否符合内容政策

替代方案

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

轮询查询结果

使用获取音乐生成详情接口定时查询任务状态,建议每30秒查询一次。