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
最佳实践
故障排除
如果您没有收到回调通知,请检查以下项目:网络连接问题
网络连接问题
- 确认回调URL可从公网访问
- 检查防火墙设置,确保入站请求不被阻止
- 验证域名解析是否正确
服务器响应问题
服务器响应问题
- 确保服务器在15秒内返回HTTP 200状态码
- 检查服务器日志中的错误信息
- 验证接口路径和HTTP方法是否正确
内容格式问题
内容格式问题
- 确认接收到的POST请求体为JSON格式
- 检查Content-Type是否为application/json
- 验证JSON解析是否正确
人声处理问题
人声处理问题
- 确认人声音频URL可访问
- 检查人声音频下载权限和网络连通性
- 验证音频保存路径和权限
- 注意人声内容必须符合内容政策
- 验证人声质量是否符合您的应用要求
回调阶段处理
回调阶段处理
- 理解三个回调阶段的差异和处理方法
- text阶段:仅表示文本生成完成,无音频数据
- first阶段:第一个人声音轨完成,包含一个音轨的数据
- complete阶段:所有人声音轨完成,包含完整的人声音轨列表
人声内容分析
人声内容分析
- 实施从人声提示词中提取歌词的功能
- 检查人声内容是否符合平台政策
- 评估人声质量和适用性
- 适当处理不同的人声风格和语言
替代方案
如果您无法使用回调机制,还可以使用轮询方式:轮询查询结果
使用获取音乐生成详情接口定期查询任务状态。建议每30秒查询一次。
