callBackUrl 参数设置回调地址。任务完成后,系统会自动将结果推送到您指定的地址。
回调机制概述
回调机制避免了您需要轮询 API 查询任务状态,系统会主动推送任务完成结果到您的服务器。
回调时机
系统会在以下情况发送回调通知:- AI 视频生成任务成功完成
- AI 视频生成任务失败
- 任务处理过程中发生错误
回调方式
- HTTP 方法: POST
- 内容类型: application/json
- 超时设置: 15 秒
回调请求格式
任务完成后,系统会向您的callBackUrl 发送 POST 请求,格式如下:
状态码说明
回调状态码,表示任务处理结果:
| 状态码 | 说明 |
|---|---|
| 200 | 成功 - 视频生成完成 |
| 400 | 客户端错误 - 不当内容、格式错误、配额限制或其他客户端问题 |
| 500 | 服务器错误 - 视频生成过程中的内部服务器错误 |
状态消息,提供详细的状态描述。常见错误消息包括:
- “检测到不当内容,请替换图像或视频。”
- “图像格式不正确。”
- “请稍后重试。您可以升级到标准会员以立即开始生成。”
- “已达到并发生成限制。”
- “不支持的宽度或高度,请调整尺寸后重试。”
- “您的提示词被我们的AI审核器捕获。请调整后重试!”
任务 ID,与您提交任务时返回的 taskId 一致
生成的视频 ID,用于标识和追踪
可访问的视频 URL,有效期 14 天。失败时为空。
生成视频的封面图片 URL。失败时为空。
回调接收示例
以下是用流行编程语言接收回调的示例代码:- Node.js
- Python
- PHP
最佳实践
回调 URL 配置建议
- 使用 HTTPS: 确保回调 URL 使用 HTTPS 协议,保证数据传输安全
- 验证来源: 在回调处理中验证请求来源的合法性
- 幂等处理: 同一个 task_id 可能收到多次回调,确保处理逻辑是幂等的
- 快速响应: 回调处理应尽快返回 200 状态码,避免超时
- 异步处理: 复杂的业务逻辑应异步处理,避免阻塞回调响应
- 立即下载: 视频 URL 只有 14 天有效期,收到成功回调后应立即下载保存文件
重要提醒
- 回调 URL 必须是公网可访问的地址
- 服务器必须在 15 秒内响应,否则会被认为是超时
- 连续 3 次重试失败后,系统将停止发送回调
- 视频 URL 14 天后过期 - 收到回调后请立即下载
- 请确保回调处理逻辑的稳定性,避免因异常导致回调失败
- 需要同时处理 video_url 和 image_url 字段,实现完整的媒体管理
- 注意错误消息中的具体失败原因(内容审核、格式问题、配额等)
故障排查
如果没有收到回调通知,请检查以下几点:网络连接问题
网络连接问题
- 确认回调 URL 可以从公网访问
- 检查防火墙设置,确保入站请求没有被阻止
- 验证域名解析是否正确
服务器响应问题
服务器响应问题
- 确保服务器在 15 秒内返回 HTTP 200 状态码
- 检查服务器日志中的错误信息
- 验证接口路径和 HTTP 方法是否正确
内容格式问题
内容格式问题
- 确认接收到的 POST 请求体是 JSON 格式
- 检查 Content-Type 是否为 application/json
- 验证 JSON 解析是否正确
视频处理问题
视频处理问题
- 确认视频 URL 可以正常访问
- 检查视频下载权限和网络连接
- 验证视频保存路径和权限
- 注意 14 天 URL 过期限制 - 实现立即下载逻辑
- 处理视频和封面图片的下载
内容审核问题
内容审核问题
- 查看错误消息中的内容政策违规提示
- 调整被 AI 审核器标记的提示词
- 确保上传的图片/视频符合内容准则
- 检查不当内容检测消息
替代方案
如果无法使用回调机制,您也可以使用轮询方式:轮询查询结果
使用获取 AI 视频详情接口定期查询任务状态,建议每 30 秒查询一次。
