技术博客 / 接入与实践
视频异步任务指南：查询状态、获取结果与处理超时
视频生成包含提交、排队、处理和取回结果几个阶段。创建请求返回任务 ID 后，应围绕这个 ID 查询后续进度。浏览器没有立即播放视频，不表示创建失败，也不应直接再发一遍创建请求。
三个接口各负责什么？
| 步骤 | 接口 | 需要保存 |
|---|---|---|
| 提交 | POST /v1/videos | 返回的任务 id 和创建时间 |
| 观察状态 | GET /v1/videos/{id} | status、progress 与错误信息 |
| 获取结果 | GET /v1/videos/{id}/content | 完成状态、文件和下载记录 |
如何查询与下载？
使用创建任务时对应的 MIGO 账户令牌访问自己的任务。下面只查询已有任务并下载结果，不会创建新视频。
# 将 VIDEO_ID 替换为创建任务返回的 id
curl "https://migofastapi.xyz/v1/videos/$VIDEO_ID" \
-H "Authorization: Bearer $MIGO_API_KEY"
# 仅在任务完成后获取视频结果
curl --fail --location \
"https://migofastapi.xyz/v1/videos/$VIDEO_ID/content" \
-H "Authorization: Bearer $MIGO_API_KEY" \
--output result.mp4客户端可按接口提示控制轮询间隔；没有提示时从 5 秒间隔开始，等待较久再逐步延长，设置业务可接受的总等待上限。查询失败时保留原任务 ID，先排查网络、权限和响应正文。
怎样理解状态变化？
queued 与 in_progress 通常表示尚未完成；completed 后再取内容；failed 时记录返回的错误字段并核查账单。实际字段以接口响应为准，客户端不能把未知状态一律当成成功。进度暂时不变，也不能单独认定任务已卡死。
视频下载失败与视频生成失败是不同问题。若生成已完成，先重试查询或下载，不要再次创建。获取内容时设置合适超时，并检查最终返回是否是视频而不是 JSON 错误。
提交超时后应该怎样处理？
如果已经拿到 ID，就查询该任务。如果没有 ID 且提交响应不明确，先保留时间、请求标识和脱敏参数，向支持人员核对是否受理；不要自动高频重提。仅根据客户端超时无法判断上游是否已经开始工作。
以上流程来自当前路由与适配器配置。实际生成效果、账户可用性和耗时需由小样本调用验证。
向支持人员提供哪些信息？
- 任务 ID、创建时间和时区。
- 模型 ID、时长、尺寸及接口路径。
- 最近一次 HTTP 状态和脱敏后的响应正文。
- 问题发生在创建、查询还是下载阶段。
不要公开 API 密钥或私人参考素材。联系入口见服务说明页。