视频生成 | MaiToken

自部署模型支持 duration、image、reference_image_urls 等统一参数，平台会自动转换为上游字段，无需手动改用 seconds、images 等原生写法。

1. 接口地址

操作	请求方法	路径
提交生成任务	POST	`/v1/video/generations`
提交生成任务（等价接口）	POST	`/v1/videos`
查询任务	GET	`/v1/video/generations/{task_id}`
下载生成结果	GET	`/v1/videos/{task_id}/content`

视频生成采用异步任务流程：提交生成请求后，使用返回的 task_id 查询任务，待生成完成后下载视频。

本文使用 {BASE_URL} 表示平台 API 根地址。

2. 模型与能力

能力	`MiniMax-H3`（官方）	自部署三档
模型名称	`MiniMax-H3`	`minimax-h3-base` / `minimax-h3-base-fast` / `minimax-h3-mini`
视频时长	4–15 秒，默认 5 秒	5–15 秒
分辨率	`768P`（默认）、`2K`	仅 `720p`；传入 `768P` 会转换为 `720p`
首帧与尾帧	支持	支持
参考图片	最多 9 张	最多 9 张，单张不超过 20MB
参考视频	最多 3 段	不支持
参考音频	最多 3 段	最多 3 段，单段不超过 50MB
输出说明	自带原生立体声音频	MP4、24fps

自部署三档的参数与能力一致，区别为生成速度和单价。

所有模型的参考素材 URL 均须可从中国大陆公网访问。请勿使用中国大陆无法访问的境外直链。

3. 提交生成任务

POST {BASE_URL}/v1/video/generationsContent-Type: application/json

也可使用等价路径：

POST {BASE_URL}/v1/videos

3.1 通用参数

参数	类型	说明
`model`	string	必填，指定模型名称
`prompt`	string	视频生成提示词；自部署模型必填，最长 30000 字符
`duration`	number	视频时长，单位为秒；官方支持 4–15，自部署支持 5–15
`resolution`	string	官方支持 `768P`、`2K`；自部署建议明确传入 `720p`
`aspect_ratio`	string	输出画幅，具体规则见下文
`image`	string	首帧或单张参考图 URL
`images`	array of strings	图片 URL 列表，兼容字段
`last_frame_image_url`	string	尾帧图片 URL；与 `image` 同时传入可用于首尾帧生成
`reference_image_urls`	array of strings	参考图片 URL 列表，最多 9 张
`reference_video_urls`	array of strings	参考视频 URL 列表，仅官方模型支持，最多 3 段
`reference_audio_urls`	array of strings	参考音频 URL 列表，最多 3 段
`generation_mode`	string	可选，`t2v` / `i2v` / `r2v`；省略时平台按素材自动判定

建议显式设置 duration 和 resolution，避免不同模型的默认行为影响结果。

3.2 画幅设置

官方模型

纯文生视频默认使用 16:9。
首尾帧或多参考素材生成建议使用 adaptive。

自部署模型

支持以下固定画幅：

16:9、9:16、1:1、4:3、3:4、21:9、9:21、4:5、5:4

传入 aspect_ratio: "adaptive" 时，平台会省略发给上游的画幅字段，由上游决定最终画幅。

3.3 自部署专用参数与限制

参数或素材	规则
`prompt_optimization`	可选布尔值，默认 `false`；设为 `true` 时，上游按官方 H3 结构改写提示词
参考图片	最多 9 张，单张不超过 20MB
参考音频	最多 3 段，单段不超过 50MB
多参参考	参考图片与参考音频至少提供一种
首尾帧	使用 `image` + `last_frame_image_url`，依次作为首帧和尾帧
参考视频	不支持，请勿传入 `reference_video_urls`

自部署服务不会在平台侧拦截越界参数。 提交 4 秒、2K 或参考视频等不支持的配置时，相关值或字段会继续传给上游，由上游忽略或报错；计费仍按请求声明的秒数预扣。

因此，自部署请求应使用 5–15 秒、720p，且不传参考视频。

4. 请求示例

以下请求体可提交到任一 POST 接口。示例中的素材地址仅为占位符，请替换为真实可访问的 URL。

4.1 官方模型：参考图片生成

{  "model": "MiniMax-H3",  "prompt": "参考图1中的角色在雨夜街头奔跑，电影感镜头",  "resolution": "768P",  "duration": 8,  "aspect_ratio": "16:9",  "reference_image_urls": [    "https://example.com/character.png"  ]}

4.2 自部署模型：纯文生视频

{  "model": "minimax-h3-base-fast",  "prompt": "清晨的海边，一只海鸥掠过海面，镜头缓慢向前推进，柔和自然光",  "resolution": "720p",  "duration": 8,  "aspect_ratio": "16:9",  "generation_mode": "t2v"}

4.3 自部署模型：首帧生视频

{  "model": "minimax-h3-base",  "prompt": "图中角色在雨夜街头奔跑，电影感镜头",  "resolution": "720p",  "aspect_ratio": "16:9",  "duration": 8,  "image": "https://example.com/character.png"}

4.4 自部署模型：首尾帧生成

{  "model": "minimax-h3-base",  "prompt": "角色从街道一端自然走向另一端，保持人物形象一致，镜头平稳跟随",  "resolution": "720p",  "duration": 8,  "aspect_ratio": "adaptive",  "image": "https://example.com/first-frame.png",  "last_frame_image_url": "https://example.com/last-frame.png"}

平台会将图片按首帧、尾帧顺序传给上游，并自动设置上游模式为 fl2va。

4.5 自部署模型：图片与音频多参参考

{  "model": "minimax-h3-mini",  "prompt": "保持图1的角色形象，按音频1的语气与节奏说话",  "resolution": "720p",  "duration": 10,  "reference_image_urls": [    "https://example.com/character.png"  ],  "reference_audio_urls": [    "https://example.com/voice.mp3"  ]}

4.6 cURL 提交示例

将请求体保存为 request.json，执行：

curl --request POST "${BASE_URL}/v1/video/generations" \  --header "Content-Type: application/json" \  --data-binary @request.json

如平台要求鉴权，请按其规定补充鉴权请求头。

5. 查询任务与下载视频

5.1 查询任务

将提交响应中实际返回的任务 ID 填入 {task_id}：

GET {BASE_URL}/v1/video/generations/{task_id}

cURL 示例：

curl "${BASE_URL}/v1/video/generations/${TASK_ID}"

根据查询响应判断任务是否完成；具体状态字段、状态值和失败信息格式以平台实际返回为准。

5.2 下载结果

任务生成完成后，可直接下载视频：

GET {BASE_URL}/v1/videos/{task_id}/content