callBackUrl 参数设置回调地址。任务完成后,系统会自动将结果推送到您指定的地址。
回调机制概述
回调机制避免了您需要轮询 API 查询任务状态,系统会主动推送任务完成结果到您的服务器。
回调时机
系统会在以下情况发送回调通知:- 视频生成任务成功完成
- 视频生成任务失败
- 任务处理过程中发生错误
回调方式
- HTTP 方法: POST
- 内容类型: application/json
- 超时设置: 15 秒
回调请求格式
任务完成后,系统会向您的callBackUrl 发送 POST 请求,格式如下:
状态码说明
回调状态码,表示任务处理结果:
| 状态码 | 说明 |
|---|---|
| 200 | 成功 - 视频生成任务成功 |
| 400 | 客户端错误 - 提示词违反内容政策或其他输入错误 |
| 422 | 托底失败 - 当未开启托底且遇到特定错误时返回,错误信息格式为:Your request was rejected by Flow(原始错误信息). You may consider using our other fallback channels, which are likely to succeed. Please refer to the documentation. |
| 500 | 内部错误 - 请稍后重试,内部错误或超时 |
| 501 | 失败 - 视频生成任务失败 |
状态消息,提供详细的状态描述。不同状态码对应的错误信息:400 状态码错误信息:
- 您的提示词被网站标记为违反内容政策
- 仅支持英文提示词
- 无法获取图片。请验证您或您的服务提供商设置的任何访问限制
- 公共错误:不安全的图片上传
- Your request was rejected by Flow(原始错误信息). You may consider using our other fallback channels, which are likely to succeed. Please refer to the documentation.
enableFallback 且遇到以下错误时,系统会尝试使用备用模型:- public error minor upload
- Your prompt was flagged by Website as violating content policies
- public error prominent people upload
任务 ID,与您提交任务时返回的 taskId 一致
生成的视频URL数组(仅成功时返回)
原始视频URL数组(仅成功时返回),仅当aspectRatio不是16:9时才有值
视频分辨率信息(仅成功时返回),表示生成视频的分辨率
是否通过托底模型生成。true表示使用了备用模型生成,false表示使用主模型生成
托底功能说明
托底功能为智能备用生成机制,当主要模型遇到特定错误时,自动切换到备用模型继续生成,提高任务成功率。
启用条件
托底功能需要同时满足以下条件:- 请求中
enableFallback参数设置为true - 宽高比为
16:9 - 遇到以下特定错误之一:
- public error minor upload
- Your prompt was flagged by Website as violating content policies
- public error prominent people upload
托底限制
- 分辨率: 托底生成的视频默认使用 1080p 分辨率,无法通过获取1080P视频接口访问
- 图片要求: 如果使用图片生成视频,图片必须是 16:9 比例,否则会进行自动截取
- 积分计算: 成功兜底的积分消耗是不同的,具体计费详情请查看 https://kie.ai/billing
错误处理
- 开启托底: 遇到特定错误时自动切换备用模型,任务继续执行
- 未开启托底: 遇到特定错误时返回 422 状态码,提示使用托底功能
托底功能仅在特定错误场景下生效。如果是其他类型的错误(如积分不足、网络问题等),托底功能不会启用。
回调接收示例
以下是用流行编程语言接收回调的示例代码:- Node.js
- Python
- PHP
最佳实践
回调 URL 配置建议
- 使用 HTTPS: 确保回调 URL 使用 HTTPS 协议,保证数据传输安全
- 验证来源: 在回调处理中验证请求来源的合法性
- 幂等处理: 同一个 taskId 可能收到多次回调,确保处理逻辑是幂等的
- 快速响应: 回调处理应尽快返回 200 状态码,避免超时
- 异步处理: 复杂的业务逻辑应异步处理,避免阻塞回调响应
- 及时下载: 视频 URL 有一定有效期,请及时下载保存
- 数组处理: resultUrls 和 originUrls 是直接的数组格式,可以直接遍历使用
- 英文提示词: 确保使用英文提示词,避免语言相关错误
重要提醒
- 回调 URL 必须是公网可访问的地址
- 服务器必须在 15 秒内响应,否则会被认为是超时
- 连续 3 次重试失败后,系统将停止发送回调
- 仅支持英文提示词,请确保提示词使用英文
- 请确保回调处理逻辑的稳定性,避免因异常导致回调失败
- 适当处理内容审核错误,确保输入内容符合平台政策
- resultUrls 和 originUrls 返回的是直接的数组格式,可以直接遍历使用
- originUrls 仅在 aspectRatio 不是 16:9 时才有值
- 注意图片上传的安全检查,避免上传不安全的图片
故障排查
如果没有收到回调通知,请检查以下几点:网络连接问题
网络连接问题
- 确认回调 URL 可以从公网访问
- 检查防火墙设置,确保入站请求没有被阻止
- 验证域名解析是否正确
服务器响应问题
服务器响应问题
- 确保服务器在 15 秒内返回 HTTP 200 状态码
- 检查服务器日志中的错误信息
- 验证接口路径和 HTTP 方法是否正确
内容格式问题
内容格式问题
- 确认接收到的 POST 请求体是 JSON 格式
- 检查 Content-Type 是否为 application/json
- 验证 JSON 解析是否正确
- 正确处理 resultUrls 和 originUrls 数组格式
视频处理问题
视频处理问题
- 确认视频 URL 可以正常访问
- 检查视频下载权限和网络连接
- 验证视频保存路径和权限
- 注意视频 URL 的有效期限制
- 及时备份视频到长期存储系统
内容审核问题
内容审核问题
- 查看内容审核错误消息
- 确保提示词使用英文
- 确保输入图像不包含不当内容
- 检查提示词是否符合平台内容政策
- 避免使用敏感或违规的描述词汇
- 确保图像上传安全且格式正确
生成质量问题
生成质量问题
- 检查生成视频的质量和分辨率
- 验证视频时长是否符合预期
- 评估生成视频的画质和风格
- 确保视频内容符合预期
- 如有 originUrls,比较原始视频和生成视频的差异
Veo3 特定注意事项
Veo3 视频生成特性
Veo3 AI 视频生成功能具有以下特点:- 高质量生成: Veo3.1 提供高质量的AI视频生成能力
- 多宽高比支持: 支持多种宽高比,非16:9时会提供原始视频
- 英文提示词: 仅支持英文提示词,请确保输入为英文
- 内容安全: 严格的内容审核机制,确保生成内容安全合规
- 灵活输出: resultUrls 可能包含多个视频文件
- 原始保留: 当宽高比不是16:9时,会保留原始尺寸视频
替代方案
如果无法使用回调机制,您也可以使用轮询方式:轮询查询结果
使用获取 Veo3 视频详情接口定期查询任务状态,建议每 30 秒查询一次。
