callBackUrl 参数设置回调地址。任务完成后,系统会自动将结果推送到您指定的地址。
回调机制概述
回调机制避免了您需要轮询 API 查询任务状态,系统会主动推送任务完成结果到您的服务器。
回调时机
系统会在以下情况发送回调通知:- 文本生成完成(callbackType: “text”)
- 第一首音频生成完成(callbackType: “first”)
- 全部音频生成完成(callbackType: “complete”)
- 音频生成任务失败
- 任务处理过程中发生错误
回调方式
- HTTP 方法: POST
- 内容类型: application/json
- 超时设置: 15 秒
回调请求格式
任务进展或完成后,系统会向您的callBackUrl 发送 POST 请求,格式如下:
状态码说明
回调状态码,表示任务处理结果:
| 状态码 | 说明 |
|---|---|
| 200 | 成功 - 请求已成功处理 |
| 400 | 验证错误 - 歌词包含受版权保护的内容 |
| 408 | 超出限制 - 超时 |
| 413 | 冲突 - 上传的音频与现有艺术作品匹配 |
| 500 | 服务器错误 - 处理请求时发生意外错误 |
| 501 | 音频生成失败 |
| 531 | 服务器错误 - 抱歉,由于问题生成失败。您的积分已退还。请重试 |
状态消息,提供详细的状态描述
回调类型,表示生成阶段:
- text: 文本生成完成
- first: 第一首完成
- complete: 全部完成
- error: 生成失败
任务 ID,与您提交任务时返回的 taskId 一致
生成的音频数组。文本回调或失败时为空。
音频唯一标识
翻唱的音频文件 URL,用于下载
原始音频文件 URL
翻唱的流式音频 URL,用于实时播放
原始流式音频 URL
翻唱的封面图片 URL
原始封面图片 URL
使用的生成提示词/歌词
使用的模型名称(如 “chirp-v3-5”)
音乐标题
音乐标签/风格
创建时间戳
音频时长(秒)
回调接收示例
以下是用流行编程语言接收回调的示例代码:- Node.js
- Python
- PHP
最佳实践
回调 URL 配置建议
- 使用 HTTPS: 确保回调 URL 使用 HTTPS 协议,保证数据传输安全
- 验证来源: 在回调处理中验证请求来源的合法性
- 幂等处理: 同一个 task_id 可能收到多次回调,确保处理逻辑是幂等的
- 快速响应: 回调处理应尽快返回 200 状态码,避免超时
- 异步处理: 复杂的业务逻辑应异步处理,避免阻塞回调响应
- 处理多次回调: 准备接收同一任务的 text、first、complete 回调
- 下载双版本: 考虑下载翻唱文件和原始文件用于对比
重要提醒
- 回调 URL 必须是公网可访问的地址
- 服务器必须在 15 秒内响应,否则会被认为是超时
- 连续 3 次重试失败后,系统将停止发送回调
- 您可能收到同一任务的多次回调(text → first → complete)
- 请确保回调处理逻辑的稳定性,避免因异常导致回调失败
- 适当处理版权和冲突错误(代码 400, 413)
- 某些服务器错误会自动退还积分(代码 531)
- 注意翻唱文件和原始文件 URL 的完整资产管理
故障排查
如果没有收到回调通知,请检查以下几点:网络连接问题
网络连接问题
- 确认回调 URL 可以从公网访问
- 检查防火墙设置,确保入站请求没有被阻止
- 验证域名解析是否正确
服务器响应问题
服务器响应问题
- 确保服务器在 15 秒内返回 HTTP 200 状态码
- 检查服务器日志中的错误信息
- 验证接口路径和 HTTP 方法是否正确
内容格式问题
内容格式问题
- 确认接收到的 POST 请求体是 JSON 格式
- 检查 Content-Type 是否为 application/json
- 验证 JSON 解析是否正确
音频处理问题
音频处理问题
- 确认音频 URL 可以正常访问
- 检查音频下载权限和网络连接
- 验证音频保存路径和权限
- 适当处理常规和流式音频 URL
- 在同一回调中处理多个音频
- 根据需要下载翻唱和原始音频文件
版权和内容问题
版权和内容问题
- 查看版权违规错误消息(代码 400)
- 检查与现有作品的内容冲突(代码 413)
- 确保遵循平台内容政策
- 如被标记,调整上传音频或提示词
- 验证上传音频的原创性
速率限制问题
速率限制问题
- 优雅处理超时错误(代码 408)
- 实现适当的退避重试逻辑
- 监控 API 使用情况以避免速率限制
- 如需要,考虑升级服务计划
文件管理问题
文件管理问题
- 按类型组织下载的文件(翻唱 vs 原始)
- 实现适当的文件命名约定
- 优雅处理潜在的重复下载
- 监控大音频文件的磁盘空间
替代方案
如果无法使用回调机制,您也可以使用轮询方式:轮询查询结果
使用获取音乐详情接口定期查询任务状态,建议每 30 秒查询一次。
