视频生成 API 的成片交付校验:从任务状态到文件验收
生成任务返回成功,只说明生成流程结束。真正交付前,还要确认结果文件能下载、包含可解码的视频流、时长和尺寸符合所选型号要求,并能与任务和账单记录对应起来。下面是一套不依赖具体模型的检查流程。
1. 先确认任务到达终态
异步生成任务先保存服务返回的 task ID,再查询这个 ID。不要用客户端的 HTTP 响应是否成功来代替任务状态判断。无限扩散 V1 文档把 queued、in_progress、completed、failed 作为视频任务状态;仅 completed 才进入下载步骤,failed 则先读取 error 并检查任务记录。
2. 下载结果时复用原任务 ID
对已完成的任务,使用文档中的下载路径 GET /v1/videos/{id}/content,并使用提交任务的同一 API 密钥和任务 ID。文档说明下载支持 Range,也提醒结果有时效;因此应把成片及时保存到自己的对象存储或媒体库,避免把临时链接当成永久地址。
若下载时发生网络中断,先重试文件下载或按 Range 续传;不要把下载失败当作生成失败再提交一条 POST /v1/videos。重新生成是另一项任务,可能产生另一笔费用。
示意命令(API_KEY 与 TASK_ID 应由服务端环境变量提供,切勿把真实密钥写进浏览器端代码或公开仓库):
curl --fail --location --output result.mp4 "https://api.wxksai.com/v1/videos/${TASK_ID}/content" --header "Authorization: Bearer ${API_KEY}"
3. 做基础媒体校验
下载完成后,先检查文件存在且大小大于零,再用 ffprobe 读取媒体信息。至少确认存在 video stream、时长可解析、宽高为正数;随后把实际时长、分辨率和画幅与请求参数以及所选型号的规格比较。不同型号支持范围不同,不要把一个型号的固定参数套用到所有型号。
ffprobe -v error -show_entries format=duration:stream=codec_type,codec_name,width,height -of json result.mp4
自动化验收时可以将文件损坏、缺少视频流、时长不符、尺寸不符分成不同错误码,保留媒体信息和校验日志。不要只检查扩展名;文件名以 .mp4 结尾不代表文件一定能解码。
4. 保存可审计的交付记录
每个成片记录任务 ID、完整 model ID、请求时长与分辨率、最终任务状态、下载时间、文件字节数、SHA-256 摘要,以及对应的账单记录。日志不要保存 API 密钥,也不要把含临时签名的下载 URL 当作长期资源地址。
当用户反馈文件无法播放时,这些信息能帮助区分任务未完成、下载中断、输出规格不符和本地播放器兼容问题,也能避免把客户端的重试次数误当作生成任务数。
5. 将“重新生成”与“重新下载”分开
- 任务仍在排队或生成:继续查询原 task ID。
- 任务已完成但文件下载中断:重试同一任务的下载。
- 文件成功下载但验收失败:保留失败样本与错误信息,先排查规格或解码问题,再由业务策略决定是否重新生成。
- 只有确实需要新成片时才创建新任务,并单独记录其 task ID 与账单。
无限扩散是第三方 API 接入服务,并非上游模型官方站点。本文以其 V1 视频任务和下载流程作示例;型号参数、文件有效期、价格及可用性以实时官方文档和实际账单为准。
参考: