当您向Suno API提交封面生成任务时,可以使用 callBackUrl 参数设置回调URL。任务完成时,系统将自动向您指定的地址推送结果。回调机制概述#
回调机制消除了轮询API获取任务状态的需要。系统会主动向您的服务器推送任务完成结果。
Webhook 安全性:为确保回调请求的真实性和完整性,我们强烈建议您实现 webhook 签名验证。请参阅我们的 Webhook 校验指南 了解详细实现步骤。 回调时机#
回调方式#
回调请求格式#
任务完成时,系统将向您的 callBackUrl 发送POST请求:{
"code": 200,
"data": {
"images": [
"https://tempfile.aiquickdraw.com/s/1753958521_6c1b3015141849d1a9bf17b738ce9347.png",
"https://tempfile.aiquickdraw.com/s/1753958524_c153143acc6340908431cf0e90cbce9e.png"
],
"taskId": "21aee3c3c2a01fa5e030b3799fa4dd56"
},
"msg": "success"
}
状态码说明#
code (integer, required)#
| 状态码 | 描述 |
|---|
| 200 | 成功 - 请求已成功处理 |
| 400 | 验证错误 - 请求参数有误 |
| 408 | 超出限制 - 超时 |
| 500 | 服务器错误 - 处理请求时发生意外错误 |
| 501 | 封面生成失败 |
| 531 | 服务器错误 - 抱歉,由于问题生成失败。您的积分已退还。请重试 |
msg (string, required)#
data.taskId (string, required)#
data.images (array)#
生成的封面图片URL数组,成功时返回。通常包含2张不同风格的封面图片回调接收示例#
最佳实践#
回调URL配置建议#
1.
使用HTTPS: 确保回调URL使用HTTPS协议以保证数据传输安全
3.
幂等处理: 同一taskId可能收到多次回调,确保处理逻辑是幂等的
4.
快速响应: 回调处理应尽快返回200状态码以避免超时
5.
异步处理: 复杂的业务逻辑应异步处理以避免阻塞回调响应
6.
图片管理: 及时下载和保存图片,注意URL的有效期
重要提醒#
请确保回调处理逻辑的稳定性,避免因异常导致回调失败
故障排查#
网络连接问题
服务器响应问题
内容格式问题
检查Content-Type是否为application/json
图片处理问题
替代方案#
轮询查询结果
使用获取Cover详情端点定期查询任务状态。我们建议每30秒查询一次。