AI 视频生成回调

当您向 Runway API 提交视频生成任务时，可以通过 callBackUrl 参数设置回调地址。任务完成后，系统会自动将结果推送到您指定的地址。

回调机制概述

回调机制避免了您需要轮询 API 查询任务状态，系统会主动推送任务完成结果到您的服务器。

Webhook 安全性：为确保回调请求的真实性和完整性，我们强烈建议您实现 webhook 签名验证。请参阅我们的 Webhook 校验指南了解详细实现步骤。

回调时机

系统会在以下情况发送回调通知：

AI 视频生成任务成功完成

AI 视频生成任务失败

任务处理过程中发生错误

回调方式

HTTP 方法: POST

内容类型: application/json

超时设置: 15 秒

回调请求格式

任务完成后，系统会向您的 callBackUrl 发送 POST 请求，格式如下：

成功回调

失败回调

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "task_id": "ee603959-debb-48d1-98c4-a6d1c717eba6",
    "video_id": "485da89c-7fca-4340-8c04-101025b2ae71",
    "video_url": "https://file.com/k/xxxxxxx.mp4",
    "image_url": "https://file.com/m/xxxxxxxx.png"
  }
}

状态码说明

参数说明

参数	类型	必需	说明
`code`	integer	是	回调状态码，表示任务处理结果
`msg`	string	是	状态消息，提供详细的状态描述
`data.task_id`	string	是	任务 ID，与您提交任务时返回的 taskId 一致
`data.video_id`	string	是	生成的视频 ID，用于标识和追踪
`data.video_url`	string	否	可访问的视频 URL，有效期 14 天。失败时为空
`data.image_url`	string	否	生成视频的封面图片 URL。失败时为空

状态码详情

状态码	说明
200	成功 - 视频生成完成
400	客户端错误 - 不当内容、格式错误、配额限制或其他客户端问题
500	服务器错误 - 视频生成过程中的内部服务器错误

常见错误消息

"检测到不当内容，请替换图像或视频。"

"图像格式不正确。"

"请稍后重试。您可以升级到标准会员以立即开始生成。"

"已达到并发生成限制。"

"不支持的宽度或高度，请调整尺寸后重试。"

"您的提示词被我们的AI审核器捕获。请调整后重试！"

回调接收示例

以下是用流行编程语言接收回调的示例代码：

Node.js

Python

PHP

最佳实践

回调 URL 配置建议

使用 HTTPS: 确保回调 URL 使用 HTTPS 协议，保证数据传输安全

验证来源: 在回调处理中验证请求来源的合法性

幂等处理: 同一个 task_id 可能收到多次回调，确保处理逻辑是幂等的

快速响应: 回调处理应尽快返回 200 状态码，避免超时

异步处理: 复杂的业务逻辑应异步处理，避免阻塞回调响应

立即下载: 视频 URL 只有 14 天有效期，收到成功回调后应立即下载保存文件

重要提醒

回调 URL 必须是公网可访问的地址

服务器必须在 15 秒内响应，否则会被认为是超时

连续 3 次重试失败后，系统将停止发送回调

视频 URL 14 天后过期 - 收到回调后请立即下载

请确保回调处理逻辑的稳定性，避免因异常导致回调失败

需要同时处理 video_url 和 image_url 字段，实现完整的媒体管理

注意错误消息中的具体失败原因（内容审核、格式问题、配额等）

故障排查

如果没有收到回调通知，请检查以下几点：

网络连接问题

服务器响应问题

内容格式问题

视频处理问题

内容审核问题

替代方案

如果无法使用回调机制，您也可以使用轮询方式：

轮询查询结果

使用获取 AI 视频详情接口定期查询任务状态，建议每 30 秒查询一次。

AI 视频生成回调

回调机制概述#

回调时机#

回调方式#

回调请求格式#

状态码说明#

参数说明#

状态码详情#

常见错误消息#

回调接收示例#

最佳实践#

故障排查#

替代方案#

回调机制概述

回调时机

回调方式

回调请求格式

状态码说明

参数说明

状态码详情

常见错误消息

回调接收示例

最佳实践

故障排查

替代方案