Luma 修改视频回调

当视频生成任务完成时，系统将通过 POST 请求将结果发送到您提供的回调 URL

当您向 Luma API 提交视频修改任务时，可以使用 callBackUrl 参数设置回调 URL。任务完成时，系统将自动将结果推送到您指定的地址。

回调机制概述

回调机制消除了轮询 API 获取任务状态的需要。系统将主动将任务完成结果推送到您的服务器。

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

回调时机

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

视频修改任务成功完成

视频修改任务失败

任务处理过程中出现错误

回调方式

HTTP 方法：POST

内容类型：application/json

超时设置：15 秒

回调请求格式

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

成功回调

生成失败回调

{
  "code": 200,
  "msg": "修改记录生成成功。",
  "data": {
    "taskId": "774d9a7dd608a0e49293903095e45a4c",
    "promptJson": "{\"callBackUrl\":\"https://b7af305f36d6.ngrok-free.app/api/v1/modify/test\",\"prompt\":\"一个夜晚的未来主义城市景观，高耸的玻璃尖塔伸向繁星满天的天空。蓝色和紫色的霓虹灯照亮着建筑物，飞行器在建筑物之间静静滑行。全息广告在建筑物外墙上闪烁变化。\",\"videoUrl\":\"https://tempfile.aiquickdraw.com/kieai/file/veo3-video/1755074605154fqb0m8ge.mp4\",\"waterMark\":\"\"}",
    "resultUrls": [
      "https://tempfile.aiquickdraw.com/l/f782018c-6be4-4990-96ba-7231cd5a39e7.mp4"
    ]
  }
}

状态码说明

`code` (integer, required)

回调状态码，指示任务处理结果：

状态码	描述
200	成功 - 视频修改成功完成
500	失败 - 视频修改任务失败

`msg` (string, required)

状态消息，提供详细的状态描述

`data.taskId` (string, required)

任务 ID，与您提交任务时返回的 taskId 一致

`data.promptJson` (string, required)

JSON 格式的原始请求参数，包括提示、视频 URL、回调 URL 和水印设置

`data.resultUrls` (array)

生成的视频 URL。仅在成功完成时出现（code 200）。

回调接收示例

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

Node.js

Python

PHP

最佳实践

回调 URL 配置建议

使用 HTTPS：确保您的回调 URL 使用 HTTPS 协议进行安全数据传输

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

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

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

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

及时下载：生成的视频可能在一段时间后过期，收到成功回调后立即下载保存

重要提醒

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

服务器必须在 15 秒内响应，否则将被视为超时

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

生成的视频 URL 可能会过期 - 收到回调后立即下载

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

需要处理成功和失败两种状态码以实现完整的错误处理

大视频文件可能需要时间下载 - 实施适当的超时设置

问题排查

如果您没有收到回调通知，请检查以下内容：

网络连接问题

确认回调 URL 可从公网访问

检查防火墙设置，确保入站请求未被阻止

验证域名解析是否正确

服务器响应问题

确保服务器在 15 秒内返回 HTTP 200 状态码

检查服务器日志中的错误消息

验证接口路径和 HTTP 方法是否正确

内容格式问题

确认收到的 POST 请求体是 JSON 格式

检查 Content-Type 是否为 application/json

验证 JSON 解析是否正确

视频处理问题

确认视频 URL 可访问

检查视频下载权限和网络连接

验证视频保存路径和权限

处理视频下载超时和重试逻辑

为大视频文件实施校验和验证

任务失败问题

检查视频修改参数是否合理

验证输入视频格式和质量

确认提示长度和格式

考虑调整修改参数并重试

查看 promptJson 中的错误消息进行调试

替代方案

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

轮询查询结果

使用获取 Luma 修改详情端点定期查询任务状态。对于视频生成任务，我们建议每 30 秒查询一次。

Luma 修改视频回调

回调机制概述#

回调时机#

回调方式#

回调请求格式#

状态码说明#

code (integer, required)#

msg (string, required)#

data.taskId (string, required)#

data.promptJson (string, required)#

data.resultUrls (array)#

回调接收示例#

最佳实践#

回调 URL 配置建议#

重要提醒#

问题排查#

替代方案#

回调机制概述

回调时机

回调方式

回调请求格式

状态码说明

`code` (integer, required)

`msg` (string, required)

`data.taskId` (string, required)

`data.promptJson` (string, required)

`data.resultUrls` (array)

回调接收示例

最佳实践

回调 URL 配置建议

重要提醒

问题排查

替代方案