> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magic666.top/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax H3 视频概览

> 说明 MiniMax H3 系列中普通档与 Pro 参考视频档、768P 与 2K 清晰度档的差异、模型映射、生成能力和查询链路。

# MiniMax H3 视频

MiniMax H3 系列使用 `POST /v1/videos` 创建异步视频任务，使用 `GET /v1/videos/{task_id}` 查询状态，并可通过 `GET /v1/videos/{task_id}/content` 下载生成结果。

当前项目把 H3 和 H3 Pro 放在同一个 MiniMax H3 系列里，不单开 Pro 系列。开发者先判断是否需要参考视频，再判断输出清晰度：

* 普通档：`minimax-h3-768p`、`minimax-h3-2k`，全能参考规格为 `503`，不接收参考视频。
* Pro 档：`minimax-h3-pro-768p`、`minimax-h3-pro-2k`，全能参考规格为 `913`，增加 1 段参考视频输入。
* `768P` 和 `2K` 是清晰度差异，不是能力差异。

## 先选模型

| 实际模型                  | 档位    | 清晰度  | 全能参考                            | 参考视频                  | 时长           | 适合场景                            | 接入建议                                  |
| --------------------- | ----- | ---- | ------------------------------- | --------------------- | ------------ | ------------------------------- | ------------------------------------- |
| `minimax-h3-768p`     | 普通档   | 768P | `503`：最多 5 张参考图、0 段参考视频、3 段参考音频 | 不支持                   | `4` 到 `15` 秒 | 草稿预览、批量生成、移动端分发、常规清晰度任务         | 默认优先使用这一档；没有明确高清交付要求时，不建议默认使用 2K      |
| `minimax-h3-2k`       | 普通档   | 2K   | `503`：最多 5 张参考图、0 段参考视频、3 段参考音频 | 不支持                   | `4` 到 `15` 秒 | 成片交付、大屏展示、需要保留更多画面细节或后期裁切的任务    | 在确认要高清输出时使用；2K 任务生成耗时也可能更长            |
| `minimax-h3-pro-768p` | Pro 档 | 768P | `913`：最多 9 张参考图、1 段参考视频、3 段参考音频 | 支持 1 段，时长 `2` 到 `5` 秒 | `4` 到 `15` 秒 | 基础能力加参考视频，适合用关键片段约束动作、镜头运动或主体状态 | 需要参考视频驱动时使用；把关键片段放进 `referenceVideos` |
| `minimax-h3-pro-2k`   | Pro 档 | 2K   | `913`：最多 9 张参考图、1 段参考视频、3 段参考音频 | 支持 1 段，时长 `2` 到 `5` 秒 | `4` 到 `15` 秒 | 同上，2K 超清输出                      | 适合参考视频驱动且需要高清交付的任务；2K 和参考视频任务通常更慢     |

<Warning>
  普通档和 Pro 档的关键差异是是否支持参考视频；`768P` 和 `2K` 的关键差异是输出清晰度。不要把 2K 当作更强的生成模式，也不要期待普通档通过传 `referenceVideos` 自动升级为 Pro。
</Warning>

## 入口映射

直接调用 API 时，推荐把 `model` 写成真实模型名：`minimax-h3-768p`、`minimax-h3-2k`、`minimax-h3-pro-768p` 或 `minimax-h3-pro-2k`。

前端插件为了简化配置，会展示一个单入口 `minimax-h3`。当前适配层只把这个单入口分流到普通档，不会自动选择 Pro 档：

1. 清晰度是 `2K` 或字段值包含 `2160` 时，实际模型使用 `minimax-h3-2k`。
2. 其他情况默认使用 `minimax-h3-768p`。
3. 如果调用方已经直接传 `minimax-h3-768p`、`minimax-h3-2k`、`minimax-h3-pro-768p` 或 `minimax-h3-pro-2k`，以传入的真实模型为准。
4. 需要参考视频时，请直接传 Pro 模型名，并把 2 到 5 秒关键片段放进 `referenceVideos`。

<CardGroup cols={2}>
  <Card title="创建视频任务" icon="sparkles" href="/api-reference/videos/minimax-h3/generation">
    使用 H3 普通档或 Pro 档提交文生视频、图生视频、首尾帧、参考音频和参考视频任务。
  </Card>

  <Card title="查询视频任务" icon="hourglass" href="/api-reference/videos/minimax-h3/query">
    使用 `GET /v1/videos/{task_id}` 轮询任务状态，并在完成后获取结果地址。
  </Card>
</CardGroup>

## 支持能力

| 能力   | 字段                         | 说明                                                       |
| ---- | -------------------------- | -------------------------------------------------------- |
| 文生视频 | `prompt`                   | 只传文本提示词，不需要参考素材                                          |
| 图生视频 | `referenceImages`          | 传 1 张参考图时常用于首帧图生视频                                       |
| 多参考图 | `referenceImages`          | 普通档最多 5 张，Pro 档最多 9 张，适合角色、主体、风格或场景参考                    |
| 首尾帧  | `first_image`、`last_image` | 用首帧和尾帧约束视频起止画面；不要同时传 `referenceImages`                   |
| 参考音频 | `referenceAudios`          | 最多 3 段公网音频 URL，合计建议不超过 15 秒；需要搭配至少 1 张 `referenceImages` |
| 参考视频 | `referenceVideos`          | 仅 Pro 档支持，最多 1 段，时长 2 到 5 秒；可叠加参考图、参考音频、首尾帧              |

## 接口约定

| 项目        | 规则                                                        |
| --------- | --------------------------------------------------------- |
| 创建任务      | `POST /v1/videos`                                         |
| 查询任务      | `GET /v1/videos/{task_id}`                                |
| 下载内容      | `GET /v1/videos/{task_id}/content`                        |
| 请求格式      | `application/json`                                        |
| 鉴权方式      | `Authorization: Bearer YOUR_API_KEY`                      |
| 时长字段      | `duration`，整数秒，范围 `4` 到 `15`                              |
| 画幅字段      | `ratio`，支持 `16:9`、`9:16`、`1:1`、`21:9`、`4:3`、`3:4`         |
| 清晰度字段     | `resolution`、`video_resolution` 或 `size`，支持 `768P` 和 `2K` |
| 普通档参考规格   | `503`，表示 5 张参考图、0 段参考视频、3 段参考音频                           |
| Pro 档参考规格 | `913`，表示 9 张参考图、1 段参考视频、3 段参考音频                           |
| 参考视频字段    | `referenceVideos`，仅 Pro 档支持，建议上传需要控制的关键片段                 |

## 当前边界

* Pro 模型不单开系列页面，统一写在 MiniMax H3 系列里。
* 当前插件前端单入口 `minimax-h3` 只自动分流普通档；Pro 档需要直接传 `minimax-h3-pro-768p` 或 `minimax-h3-pro-2k`。
* 当前项目 H3 适配层不透出 `adaptive` 画幅；如果传入不支持的比例，会回退为 `16:9`。
* 2K 或参考视频任务生成耗时可能更长，高峰期偶发排队；任务失败后可重新提交。

## 推荐阅读

1. [MiniMax H3 创建视频任务](./generation)
2. [MiniMax H3 查询视频任务](./query)
3. [视频模型支持矩阵](/api-reference/videos/model-matrix)