callBackUrl 参数设置回调URL。任务完成时,系统将自动向您指定的地址推送结果。
回调机制概述
回调机制消除了轮询API获取任务状态的需要。系统会主动向您的服务器推送任务完成结果。
回调时机
系统将在以下情况发送回调通知:- 音乐分区替换任务成功完成
- 音乐分区替换任务失败
- 任务处理过程中发生错误
回调方式
- HTTP方法: POST
- 内容类型: application/json
- 超时设置: 15秒
回调请求格式
任务完成时,系统将以下格式向您的callBackUrl 发送POST请求:
状态码说明
回调状态码,表示任务处理结果:
| 状态码 | 描述 |
|---|---|
| 200 | 成功 - 请求已成功处理 |
| 400 | 验证错误 - 参数验证失败 |
| 408 | 超出限制 - 超时 |
| 500 | 服务器错误 - 处理请求时发生意外错误 |
| 501 | 音频生成失败 |
| 531 | 服务器错误 - 抱歉,由于问题生成失败。您的积分已退还。请重试 |
状态消息,提供更详细的状态描述
响应数据字段
包含回调数据的容器对象
回调类型,表示当前回调阶段:
| 类型 | 描述 |
|---|---|
| complete | 替换任务全部完成 |
| error | 任务失败或发生错误 |
任务唯一标识符,用于追踪和查询
生成的音乐数据数组。成功时包含替换后的音乐详细信息,失败时为 null
实现回调处理器
以下示例展示如何实现回调处理器:回调安全建议
为确保回调的安全性,建议实施以下措施:
- 验证请求来源:检查请求IP或使用签名验证
- 使用HTTPS:确保回调URL使用HTTPS协议
- 实现幂等性:处理可能的重复回调
- 超时处理:确保在15秒内响应回调请求
- 错误日志:记录所有回调详情以便调试
常见问题
为什么没有收到回调?
为什么没有收到回调?
可能的原因:
- 回调URL不可访问(检查防火墙设置)
- 回调处理器响应超时(超过15秒)
- URL格式错误或使用了HTTP而非HTTPS
- 服务器返回了非200状态码
如何处理回调重试?
如何处理回调重试?
系统可能会在以下情况重试回调:
- 回调URL返回非200状态码
- 请求超时
- 网络错误
- 实现幂等性处理,使用task_id识别重复回调
- 快速响应200状态码,然后异步处理数据
替换分区的时长有限制吗?
替换分区的时长有限制吗?
- 建议替换时长不超过原音乐总时长的50%
- 最小替换时长建议至少2秒
- 替换片段会自动与原音乐融合
替代方案:轮询查询
如果您不使用回调,也可以通过轮询方式查询任务状态:查询任务状态
使用获取音乐详情接口定期查询任务状态,建议每30秒查询一次。
