callBackUrl
参数设置回调URL。任务完成后,系统会自动将结果推送到您指定的地址。
回调机制概述
回调机制消除了轮询API查询任务状态的需要。系统会主动将任务完成结果推送到您的服务器。
回调时机
系统会在以下情况发送回调通知:- 文本生成完成(
text
阶段) - 第一个人声音轨生成完成(
first
阶段) - 所有人声音轨生成完成(
complete
阶段) - 人声生成任务失败
- 任务处理过程中发生错误
回调方式
- HTTP方法: POST
- 内容类型: application/json
- 超时时间: 15秒
回调请求格式
任务完成后,系统会向您的callBackUrl
发送如下格式的POST请求:
状态码说明
回调状态码,表示任务处理结果:
状态码 | 说明 |
---|---|
200 | 成功 - 人声生成完成 |
400 | 请求错误 - 参数错误或内容违规 |
401 | 未授权 - API密钥无效 |
413 | 内容过长 - 提示词或风格描述超出限制 |
429 | 积分不足 - 账户积分余额不足 |
500 | 服务器错误 - 请稍后重试 |
状态消息,提供详细的状态描述
回调类型,表示当前回调阶段:
text
: 文本生成完成first
: 第一个人声音轨生成完成complete
: 所有人声音轨生成完成failed
: 任务失败
任务ID,与您提交任务时返回的taskId一致
人声生成结果信息,成功时返回
音频唯一标识符
带人声的音频文件下载链接
原始源音频文件下载链接
带人声的流式音频播放链接
音乐封面图片链接
用于人声生成的提示词/歌词
用于人声生成的AI模型名称
带人声的音乐标题
包含人声特征的音乐风格标签
创建时间
音频时长(秒)
回调接收示例
以下是使用各种流行编程语言接收回调的示例代码:- Node.js
- Python
- PHP
最佳实践
人声生成回调配置建议
- 使用HTTPS: 确保回调URL使用HTTPS协议以保证数据传输安全
- 验证来源: 在回调处理中验证请求来源的合法性
- 幂等处理: 确保处理逻辑具有幂等性,因为相同taskId可能收到多次回调
- 快速响应: 回调处理应快速返回200状态码,避免超时
- 异步处理: 复杂的业务逻辑应异步处理,避免阻塞回调响应
- 分阶段处理: 针对不同回调阶段(text、first、complete)实施相应的业务逻辑
- 人声内容分析: 实施人声内容分析和质量评估
- 歌词提取: 从人声提示词中提取和处理歌词,便于内容管理
重要提醒
- 回调URL必须可公开访问
- 服务器必须在15秒内响应,否则视为超时
- 连续3次重试失败后,系统将停止发送回调
- 确保回调处理逻辑的稳定性,避免因异常导致回调失败
- 生成的人声音频URL可能有时效性,建议及时下载保存
- 注意人声内容合规性,避免因违规导致生成失败
- 人声生成分为三个阶段,每个阶段都会触发回调通知
- 考虑实施人声歌词和音频内容的内容过滤
故障排除
如果您没有收到回调通知,请检查以下项目:网络连接问题
网络连接问题
- 确认回调URL可从公网访问
- 检查防火墙设置,确保入站请求不被阻止
- 验证域名解析是否正确
服务器响应问题
服务器响应问题
- 确保服务器在15秒内返回HTTP 200状态码
- 检查服务器日志中的错误信息
- 验证接口路径和HTTP方法是否正确
内容格式问题
内容格式问题
- 确认接收到的POST请求体为JSON格式
- 检查Content-Type是否为application/json
- 验证JSON解析是否正确
人声处理问题
人声处理问题
- 确认人声音频URL可访问
- 检查人声音频下载权限和网络连通性
- 验证音频保存路径和权限
- 注意人声内容必须符合内容政策
- 验证人声质量是否符合您的应用要求
回调阶段处理
回调阶段处理
- 理解三个回调阶段的差异和处理方法
- text阶段:仅表示文本生成完成,无音频数据
- first阶段:第一个人声音轨完成,包含一个音轨的数据
- complete阶段:所有人声音轨完成,包含完整的人声音轨列表
人声内容分析
人声内容分析
- 实施从人声提示词中提取歌词的功能
- 检查人声内容是否符合平台政策
- 评估人声质量和适用性
- 适当处理不同的人声风格和语言
替代方案
如果您无法使用回调机制,还可以使用轮询方式:轮询查询结果
使用获取音乐生成详情接口定期查询任务状态。建议每30秒查询一次。