视频生成 API 接入怎么验收：异步任务、回调、过期文件和内容审核都要测

视频生成和普通聊天接口最大的不同是：请求成功只代表任务已受理，不代表视频已经可用。任务可能排队数分钟、生成中途失败、回调重复抵达，或者结果文件很快过期。把它当成一次同步 HTTP 请求，会在订单、前端进度和成本统计中留下很多空洞。

任务状态必须可解释

至少区分已受理、排队、生成、审核、完成、失败、取消和结果未知。每个状态需要有更新时间、原因码和下一步动作。客户端重试创建任务时应复用业务幂等键；如果只因为回包超时就重新提交，可能生成两条内容相同的视频并产生双重费用。

回调是另一个关键边界。服务端要校验签名、时间戳、事件 ID 和任务归属，保存原始事件摘要后再更新业务状态。回调可重复、可乱序、也可能在用户取消后才到达，因此状态机不能只根据“最后收到的事件”覆盖全部记录。

文件与审核不能后补

完成状态里的视频 URL 应是短期、按项目授权的访问链接。前端下载前再次校验用户和任务归属；过期后可以重新签发，不应把永久公开对象存储链接直接发给用户。内容审核要把模型审核、业务规则和人工复核分开记录，避免用户无法理解为何任务被拒绝。

Wan2.1 等开源视频模型让团队可以控制推理流程，但会带来队列、显存、文件存储和审核运维工作。托管 API 降低接入门槛，但仍需把异步状态和账单核对接入自己的系统。

使用 top-api.cc 做多模型调用时，可把请求 ID、任务 ID、上游名称和费用估算关联起来，再在业务服务里维护最终任务状态。不要让网关的 HTTP 成功状态替代视频任务真正完成。

验收场景

• 网络超时后重复提交；
• 回调重复、乱序和签名失败；
• 审核拒绝、生成失败和部分成功；
• 用户取消后仍返回完成事件；
• 结果链接到期与权限变更；
• 长队列下的预计等待与真实完成时间。

参考资料：Wan2.1 项目和各视频 API 的异步任务、回调、媒体存储文档。不同供应商的状态枚举不可直接混用。

在 top-api.cc 统一上游调用后，建议持续保存任务状态转换和最终文件期限，便于复盘失败和核对账单。