MiniMax 统一视频格式

使用 /v1/videos 或 /v1/video/generations 调用 H3、Max、Max Turbo，并理解字段映射和查询响应差异。

统一格式适合复用 aiiqq.com 视频客户端。生成模型使用小写 minimax-h3、minimax-h3-max 或 minimax-h3-max-turbo；H3 的上游名称映射已由服务端配置。minimax-h3-context-ir 和 minimax-h3-regeneration 使用原生专用接口，不作为统一视频生成模型。

请求字段映射

统一字段	发送给视频模型的字段
`model`	对应模型名称；H3 自动映射为 `MiniMax-H3`
`prompt`	`content` 的文本项
`images`，或 `image`	`content` 的 `reference_image` 图片项
`metadata.video_url`	`reference_video` 项
`metadata.audio_url`	`reference_audio` 项
`size`	`resolution`；H3 填 `768P` / `2K`，Max 填 `480P` / `768P`
`seconds` 或 `duration`	整数 `duration`，`seconds` 优先；不要传冲突值
`metadata.ratio` 或 `metadata.aspect_ratio`	`ratio`，前者优先
`metadata.content`	完整媒体数组，非空时优先于自动构造的文本和媒体项
`metadata.extra`	平台格式的 `extra`，例如 Max 的提示词扩展选项
`metadata.callback_url`、`metadata.aigc_watermark`	对应可选原生字段；保留显式 `false`

快捷字段仅在所选模型支持该素材时使用。需要首尾帧或多媒体明确角色时，提供完整 metadata.content，并把所需文本也包含在数组内。

统一接口的顶层 prompt 必须非空，即使已经提供 metadata.content 也要填写；原生 /v2 接口则在 content 内提供文本项。

H3：768P、4 秒

curl --max-time 300 "$MODELSELL_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $MODELSELL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "minimax-h3",
    "prompt": "一只红色茶壶放在木桌上，晨光照进房间，镜头缓慢推进",
    "seconds": "4",
    "size": "768P",
    "metadata": {"ratio": "16:9", "aigc_watermark": false}
  }'

Max：480P、5 秒

{
  "model": "minimax-h3-max",
  "prompt": "晨光中的红色茶壶产品短片",
  "seconds": "5",
  "size": "480P",
  "metadata": {
    "ratio": "16:9",
    "extra": {"prompt_expansion_mode": "balanced"}
  }
}

调用 Max Turbo 时将 model 改为 minimax-h3-max-turbo，保持 480P / 5 秒最小示例，并省略未经确认的 metadata.extra。

指定首尾帧

{
  "model": "minimax-h3",
  "prompt": "花苞在晨光中缓慢绽放",
  "seconds": "4",
  "size": "768P",
  "metadata": {
    "ratio": "adaptive",
    "content": [
      {"type": "text", "text": "花苞在晨光中缓慢绽放"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first.png"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://example.com/last.png"}, "role": "last_frame"}
    ]
  }
}

完整 metadata.content 生效后，不会再合并 prompt、images 或快捷视频/音频字段。图片和参考素材的角色约束见请求参数。

创建响应与查询

POST /v1/videos 和 POST /v1/video/generations 都返回统一视频创建对象，保存 id：

{"id": "task_example_h3_generation", "task_id": "task_example_h3_generation", "object": "video", "model": "minimax-h3", "status": "queued", "progress": 0, "created_at": 1793145600}

推荐使用 GET /v1/videos/{task_id}，继续使用创建任务时的 API Key。成功响应示例：

{
  "id": "task_example_h3_generation",
  "object": "video",
  "model": "minimax-h3",
  "status": "completed",
  "video_url": "https://example.com/result.mp4",
  "metadata": {
    "url": "https://example.com/result.mp4",
    "resolution": "768P",
    "usage": {"total_seconds": 4, "output_seconds": 4, "input_seconds": 0, "input_image_count": 0}
  }
}

平台 Max / Turbo 的统一查询也返回该视频对象；metadata.outputs 保留原始视频地址列表，metadata.usage 提供秒数等最终用量。

GET /v1/video/generations/{task_id} 使用不同的任务包装：读取 data.status（例如 SUCCESS）和 data.result_url；原始上游快照在 data.data。公共 ID 使用创建响应的 id / task_id 或外层 data.task_id，不要引用原始快照里的上游 ID。不要把该路径的响应按上面的根级 status / video_url 解析。需要标准化状态和元数据时使用 /v1/videos/{task_id}；原生取消状态在统一对象中映射为 failed。

统一查询根据任务的原渠道识别格式，不能据此把平台任务用于原生再生成的 source_task_id。原生创建格式及其查询路径见接口概览。