视频生成任务 API

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

使用真人照片或多张人物参考图生成 Seedance 视频时，先阅读真人素材视频生成完整教程：上传图片、发起审核、等待 active，再使用 asset:// 引用提交视频。教程提供完整调用脚本、参数表和审核任务查询说明。

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

MiniMax-H3 官方 V2 与 OpenAI remix

本站支持 MiniMax 官方格式的 POST /v2/video_generation、POST /v2/video_regeneration、POST /v2/h3_context_ir 和 GET /v2/query/video_generation/{task_id}，也支持 OpenAI 兼容的 POST /v1/videos/{video_id}/remix。所有创建和查询响应中的 ID 都是本站 system Task ID；source_task_id、路径 video_id 会在内部完成权限校验并映射为真实上游任务 ID，客户端不应保存、提交或依赖真实上游 ID。

官方路径固定操作，不自动切换：/v2/video_generation 始终按严格 generation schema 校验并调用 generation，/v2/video_regeneration 始终按严格 regeneration schema 校验并调用 regeneration，/v2/h3_context_ir 始终创建增强提示词任务。错误请求不会因为 body 看起来属于另一种操作而被静默改道。

POST /v1/videos 才使用强判据自动分流：非空 source_task_id 或恰好一个 base_video 选择 regeneration；reference_video 仍是 generation；没有强判据时也是 generation。source_task_id 与 base_video 并存、多个或空 base_video、以及显式 action 与结构不一致等冲突请求返回 400，并且不会先执行源任务查询、媒体处理、计费、持久化或上游调用。

每次渠道 retry 都从 immutable 原始请求重新恢复客户端 path、body 和媒体引用，再重新分类、校验、解析 system source Task ID 并选择当前 credential 的上游表示；上一 attempt 的 action、映射模型、content、暂存 URL 或真实 upstream ID 不会成为下一 attempt 的输入。客户端始终看到 system Task ID，真实上游 Task ID 只保存在私有映射中。

普通 H3 V2 生成沿用官方请求字段，duration、resolution 和 ratio 都必须按模型支持范围填写；创建响应仍只返回系统 Task ID。

MiniMax-H3 Context-IR 官方请求

POST /v2/h3_context_ir 创建异步增强提示词任务，不生成视频。请求必须使用 JSON，wire model 必须精确为 MiniMax-H3；顶层只允许 model、content、duration、ratio 和可选的 callback_url。task_type 由服务器根据路径派生并注入，客户端在该官方路径提交 task_type 会返回 400；resolution、aigc_watermark、顶层 prompt、action、source_task_id、metadata、seconds、size 和其他未知字段同样不被接受。

content 必须是非空数组并包含至少一个非空文本项，单个文本项最多 7000 个 Unicode 码点；duration 必须是 4 到 15 的整数。纯文本模式必须显式提供非 adaptive 的合法 ratio；首帧、仅尾帧、首尾帧或参考媒体模式可以省略 ratio。Context-IR 按其端点级 OpenAPI 支持 text + last_frame，不会借此放宽普通 generation/regeneration。callback_url 若提供会原样转发给 Hailuo。

Copy{
  "model": "MiniMax-H3",
  "content": [{"type": "text", "text": "把这段创意扩展为结构化视频提示词"}],
  "duration": 5,
  "ratio": "16:9",
  "callback_url": "https://callback.example/context-ir"
}

创建成功只返回本站 system task_id。继续请求 GET /v2/query/video_generation/{task_id}；成功结果是 task.content.prompt 中的增强提示词，而不是 task.content.url 视频地址。

MiniMax-H3 V2 official generation payload

参考文档：MiniMax-H3 创建视频生成任务（官方）。本站调用使用本站地址、令牌和系统 task_id，不要混用官方示例中的上游凭据与任务 ID。

Copy{
  "model": "MiniMax-H3",
  "content": [{"type": "text", "text": "纸雕白兔穿过晨雾森林"}],
  "duration": 5,
  "resolution": "768P",
  "ratio": "16:9"
}

官方 /v2/video_generation 不接受顶层 prompt，也不会把它转换成 content；这类扁平输入只属于 /v1/videos 兼容入口。官方路径始终按原生 raw schema 校验并在本地返回参数错误。

官方再生成请求必须使用 MiniMax-H3、显式 resolution: "2K"，并且恰好选择一种输入模式。源任务模式适合同一 MiniMax 账户中符合官方条件的成功任务：

Copycurl "$BASE_URL/v2/video_regeneration" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "source_task_id": "system-source-task-id",
    "resolution": "2K",
    "aigc_watermark": false
  }'

base_video 模式用于提交一个符合官方约束的源视频；不能与 source_task_id 同时出现，并应在 content 中带上生成该 768P 源视频时实际使用的最终提示词和原始参考媒体。

MiniMax-H3 V2 official content regeneration payload

Copy{
  "model": "MiniMax-H3",
  "resolution": "2K",
  "content": [
    {
      "type": "video_url",
      "role": "base_video",
      "video_url": {"url": "https://media.example.com/source.mp4"}
    },
    {"type": "text", "text": "源视频生成时的最终提示词"}
  ]
}

OpenAI 客户端可以把 system Task ID 放入路径，网关会转换成同一官方再生成能力：

Copycurl "$BASE_URL/v1/videos/system-source-task-id/remix" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MiniMax-H3","resolution":"2K"}'

官方创建响应为 {"task_id":"<system-task-id>"}。使用该值轮询 GET /v2/query/video_generation/{task_id}；OpenAI 客户端则轮询 GET /v1/videos/{task_id}，同一任务会按查询路径返回对应方言。MiniMax 官方再生成仅用于把符合 MiniMax-H3 官方 768P 输出约束的源视频再生成为 2K，不是任意视频的通用转码或超分接口。

再生成使用独立计价键 MiniMax-H3__regeneration；缺少该价格合同会在提交上游前拒绝请求，显式零价仍是有效合同。预扣使用冻结的请求和价格事实；成功优先按真实 upstream usage 结算，usage 缺失时使用冻结估算，对应 token/seconds 事实仍不可用时保留冻结预扣；失败按异步任务规则退款，并以终态 CAS 和唯一财务事件防止重复结算。外部 HTTP(S)、data URL、本站内容代理、MiniMax 文件引用和 /ximg/ 输入都进入统一的安全下载、类型/大小校验、暂存和渠道 URL 转换；重试时从冻结的原始媒体重新构造，成功结果只返回处理或加速后的客户端 URL。

创建和轮询最小示例

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 或供应商轮询打满。轮询器用租约防多节点重复消费，终态写入需幂等；回调若可用也必须验签、防重放并以主动查询补偿漏回调。部署前演练供应商超时、任务永久卡住、链接过期、对象存储失败和重复回调，确保退款或最终结算能与任务终态和使用日志对齐。