AI VideoWebhooksIdempotencyAPI

视频生成回调收两次,成片只应交付一次

Webhook 重试、乱序和补偿轮询都可能报告同一视频任务。用任务身份、终态检查和唯一交付记录,避免成片重复入库或通知。

查看接入文档
视频生成回调收两次,成片只应交付一次

同一个视频生成任务可能先被轮询发现已完成,几秒后又收到两次 Webhook。把三次输入都当成同一条任务的状态更新,不要让它们分别触发下载和通知。HTTP 回调的 2xx 只表示应用已接收并处理或可靠保存这条消息,不表示视频已入库。

为什么相同回调会到两次?

应用写入成功、应答却在途中丢失,提供方就可能再次发送。fal Webhook 文档明确要求同一 request_id 的重复投递可安全处理;有内部重试时,gateway_request_id 可能表示最后一次尝试,不能代替队列的 request_id。Replicate 回调文档也说明终态通知可重试、消息可能乱序,而中间状态回调不重试。这是两家服务的投递约定,不是所有视频接口的规则。

第一次回调已经写入但应答丢失,第二次到达时应读取同一条处理记录

用服务文档指定的方法验证来源和签名,再把已注册的提供方账号与任务号对应起来。对 fal,按其文档验证原始请求体对应的签名和时间戳;不要直接依据未经验证的正文或媒体地址写入自己的库。Nbility Seedance 原生接口不接收回调地址,使用轮询;如果应用自己发送完成事件,也可以复用下面的交付规则,不需要向生成请求硬加一个字段。

去重键该用通知号还是任务号?

要避免成片入库两次,键应当描述业务动作,而不只是这次网络投递。比如用「提供方账号 + 任务号 + save-video」做唯一键。如果任务有多个独立产物,再加产物标识。不要按 URL 去重,链接续签会换地址;也不要按提示词去重,因为相同提示词可以合法生成多次。

让轮询和回调走同一条状态更新路径,在一次数据事务里处理终态与交付记录。简化成流程如下:

收到已验证的终态更新
  锁定已存在的本地任务记录
  已是终态 → 不回退;状态冲突记待核对
  首次确认成功 → 更新状态,插入唯一的 save-video 待办
  首次确认失败或取消 → 更新状态,不创建下载待办
提交后应答;后台从待办中下载并校验文件

轮询和回调经过同一个终态判断,首次成功才产生唯一待办

这个设计的前提是首次成功和待办写入一起提交。否则可能出现任务已成功、进程崩溃、但永远没有下载待办。终态冲突时重新查询权威状态,不用较晚到达的消息覆盖已保存的结果。

什么时候才通知用户?

等后台实际下载、校验并保存成片,才创建「可下载」通知。使用固定的对象存储键或目标系统支持的幂等键。如果目标不支持幂等,也无法查回执,发送后崩溃就应记为待确认;一个本地 sent 字段无法保证第三方消息只出现一次。更多例子见 n8n 重跑如何处理外部动作。

视频先通过下载和解码检查,再入库和发通知;通知回执未知时留待确认

上线前至少演练两次相同成功通知、轮询与回调同时到、结束后又收到较早的进行中状态,以及入库后通知回执丢失。前三种应只看到一条入库待办;最后一种应看到可查询或待确认的发送记录,而不是重新生成。本文于 2026 年 11 月 20 日查阅提供方文档,用合成事件检查去重规则,未接收真实回调或验证生产投递时限。

相关文章

用 Seedance 2.5 给已经拍好的镜头续一段
Seedance 2.5AI VideoVideo Editing

用 Seedance 2.5 给已经拍好的镜头续一段

Seedance 2.5 延长视频需要参考原片并使用 adaptive 画幅。用一个骑行镜头说明何时选 extend、提示词怎么写,以及接缝要验收什么。

用 Nbility 跑通你的 Agent 工作流

获取 API Key,统一接入 OpenAI 兼容模型和开发工具。

获取 API Key