视频生成任务 API

小白：提交、完成、下载是三步

视频生成通常需要几十秒到数分钟。POST /v1/videos 只负责创建任务，响应中的 id 或兼容字段 task_id 必须持久化；随后查询 GET /v1/videos/{task_id}。只有 status=completed 才读取结果；queued、in_progress 是中间态，failed 是失败终态。本站也保留 /v1/video/generations 兼容入口，客户端应固定一种契约，不要混用两套字段。

创建和轮询最小示例

Copycreate=$(curl -sS "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sora-2","prompt":"纸雕白兔穿过晨雾森林","seconds":"8","size":"1280x720"}')

task_id=$(printf '%s' "$create" | jq -r '.id // .task_id')
test -n "$task_id" && test "$task_id" != "null"

curl "$BASE_URL/v1/videos/$task_id" \
  -H "Authorization: Bearer $API_KEY"

查询响应可能包含 progress、created_at、completed_at、expires_at、video_url 和 error。不要只看 HTTP 200；任务对象内部仍可能是 failed。

终态机、超时与重试

建议状态机只允许 queued → in_progress → completed|failed，未知状态保留原值并告警，不能默认当成功。轮询从 2–5 秒开始，指数退避到合理上限并加随机抖动；为整项业务设置截止时间。网络超时不等于创建失败：重发前先用本地幂等键、Request-ID 或已保存任务 ID 对账，避免重复任务与重复计费。

只有读取状态这类幂等请求适合常规重试。创建和 remix 请求必须先验证供应商是否支持幂等语义；400 参数错误、401/403 认证错误和确定的内容拒绝不应自动重试。

输入、下载和生命周期

图生视频输入应使用受控 HTTPS URL 或本站适配器明确支持的格式。远程拉取必须防 SSRF、限制重定向、内容类型、像素、时长和字节数。任务完成后，可使用响应中的 video_url，或在支持时请求 GET /v1/videos/{task_id}/content。下载时使用流式复制、超时、最大字节数、哈希校验和临时文件原子落盘。

expires_at 是结果生命周期信号，不是永久存储承诺。把产物保存到自有对象存储并记录任务、用户、模型、提示词版本、内容类型、大小、哈希、保留期与删除状态。

生产可观测性与计费

指标至少包括提交成功率、排队时长、生成时长、终态成功率、失败码、过期前下载率和每个模型的成本。日志保存内部任务 ID、上游任务 ID、Request-ID 与用户幂等键，但不要记录完整敏感提示词或原始参考图。按时长、分辨率、模型档位、生成数量和重试分别核算；客户端断开不一定终止上游任务，因此取消能力和计费仍要单独确认。

专家：容量、回调与故障恢复

用队列隔离提交与轮询，限制单用户和全局在途任务，避免高峰把数据库、Redis 或供应商轮询打满。轮询器用租约防多节点重复消费，终态写入需幂等；回调若可用也必须验签、防重放并以主动查询补偿漏回调。部署前演练供应商超时、任务永久卡住、链接过期、对象存储失败和重复回调，确保退款或最终结算能与任务终态和使用日志对齐。