# MiniMax-H3-Max 视频生成 API 对接文档 ## 概述 MiniMax-H3-Max 是高质量视频生成接口，支持文生视频（T2V）与图生视频（I2V，首帧 / 尾帧）。生成模式由输入素材自动判定，无需显式声明。 **特性**： - 🎬 **文生视频**：纯文本描述直接生成视频 - 🖼️ **首尾帧控制**：支持传入首帧 / 尾帧图片，精确约束视频起止画面 - 🧠 **模式自动判定**：根据输入素材自动选择 T2V / I2V - 📐 **双分辨率**：支持 768p（默认）与 480p - ⏱️ **长时长**：单次可生成 5 ~ 15 秒视频 > 说明：本模型**不支持**参考图、中间帧、参考视频与参考音频，也**不支持** 2K 分辨率。如需上述能力请使用 MiniMax-H3。 **Base URL**: `https://api.apiverse.ai`（国内专线） --- ## 认证方式 所有接口均需要在请求头中携带 Token 进行认证： ``` Authorization: Bearer {YOUR_AUTH_TOKEN} ``` --- ## 素材组合规则 MiniMax-H3-Max 根据输入素材自动判定生成模式： | 输入素材 | 判定模式 | |---------|---------| | 仅 `prompt` | 文生视频（T2V） | | 含 `firstFrameImage` 和/或 `lastFrameImage` | 图生视频（I2V） | - `prompt`、`firstFrameImage` **至少提供一项**，`prompt` 最长 7000 字符。 - 首帧、尾帧可只传其一，也可同时传入。 - 本接口不接受参考图、参考视频、参考音频参数。 --- ## 支持的使用场景 ### 场景1：文生视频（T2V） 纯文本描述生成视频。 ```bash curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3-max" \ -H "Authorization: Bearer your_auth_token_here" \ -H "Content-Type: application/json" \ -d '{ "prompt": "写实风格，晴朗的蓝天之下，一大片白色的雏菊花田，镜头逐渐拉近，最终定格在一朵雏菊花的特写上，花瓣上有几颗晶莹的露珠", "aspectRatio": "16:9", "resolution": "768p", "duration": 5 }' ``` ### 场景2：首帧生视频（I2V） 传入首帧图片，模型以该画面为起点生成视频。 ```bash curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3-max" \ -H "Authorization: Bearer your_auth_token_here" \ -H "Content-Type: application/json" \ -d '{ "prompt": "画面中的女孩温柔地看向镜头，镜头缓缓拉出，头发被风吹动", "firstFrameImage": "https://example.com/girl.png", "resolution": "768p", "duration": 8 }' ``` ### 场景3：首尾帧生视频 同时传入首帧与尾帧图片，精确约束视频的起止画面。 ```bash curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/minimax-h3-max" \ -H "Authorization: Bearer your_auth_token_here" \ -H "Content-Type: application/json" \ -d '{ "prompt": "镜头从清晨的城市街道缓缓推进到日落时分的同一街道", "firstFrameImage": "https://example.com/morning.png", "lastFrameImage": "https://example.com/sunset.png", "resolution": "768p", "duration": 10 }' ``` > 提示：传入首尾帧时，输出画幅由图片自适应决定，`aspectRatio` 不再生效。 --- ## 查询任务状态 ```bash curl -X GET "https://api.apiverse.ai/api/v2/open/aigc/{taskId}" \ -H "Authorization: Bearer your_auth_token_here" ``` --- ## 接口详情 ### 1. 创建 MiniMax-H3-Max 任务 **POST** `/api/v2/open/aigc/minimax-h3-max` 创建一个 MiniMax-H3-Max 视频生成任务。生成模式（T2V / I2V）由输入素材自动判定。 **Content-Type**: `application/json` #### 请求参数 | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | prompt | string | 否 | 提示词，最长 7000 字符。与 `firstFrameImage` 至少提供一项 | | firstFrameImage | string | 否 | 首帧图片 URL（触发图生视频） | | lastFrameImage | string | 否 | 尾帧图片 URL（触发图生视频） | | aspectRatio | string | 否 | 宽高比：`21:9` / `16:9`(默认) / `4:3` / `1:1` / `3:4` / `9:16`。传入首尾帧时按图片自适应，本参数不生效 | | resolution | string | 否 | 输出分辨率：`768p`(默认) / `480p`。**不支持 2K** | | duration | int | 否 | 视频时长（秒），范围 5~15，默认 5。越界回退默认值 | | watermark | bool | 否 | 是否添加水印 | | taskNickname | string | 否 | 任务昵称，便于业务侧标识 | | callbackUrl | string | 否 | 任务完成后的回调通知 URL | #### 响应参数 | 参数 | 类型 | 说明 | |-----|------|------| | code | int | 状态码，0 表示成功 | | msg | string | 状态信息 | | data.taskId | string | 任务 ID，用于查询任务状态 | | data.status | string | 任务状态，创建时固定为 `processing` | | data.createdAt | string | 创建时间 | #### 响应示例 **成功** ```json { "code": 0, "msg": "success", "data": { "taskId": "task_20260831150000_abc12345", "status": "processing", "createdAt": "2026-08-31 15:00:00" } } ``` --- ### 2. 查询任务状态 **GET** `/api/v2/open/aigc/{taskId}` 查询单个任务的执行状态。 #### 路径参数 | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | taskId | string | 是 | 任务 ID | #### 响应参数 | 参数 | 类型 | 说明 | |-----|------|------| | code | int | 状态码，0 表示成功 | | msg | string | 状态信息 | | data.taskId | string | 任务 ID | | data.status | string | 任务状态：`processing` / `success` / `failed` | | data.result | string[] | 生成的视频 URL 列表（成功时返回） | | data.errorMsg | string | 错误信息（失败时返回） | | data.createdAt | string | 创建时间 | | data.updatedAt | string | 更新时间 | #### 响应示例 **处理中** ```json { "code": 0, "msg": "success", "data": { "taskId": "task_20260831150000_abc12345", "status": "processing", "createdAt": "2026-08-31 15:00:00", "updatedAt": "2026-08-31 15:00:05" } } ``` **成功** ```json { "code": 0, "msg": "success", "data": { "taskId": "task_20260831150000_abc12345", "status": "success", "result": [ "https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/2026/08/31/output.mp4" ], "createdAt": "2026-08-31 15:00:00", "updatedAt": "2026-08-31 15:02:30" } } ``` --- ### 3. 批量查询任务状态 **POST** `/api/v2/open/aigc/batch` 批量查询多个任务的执行状态（最多 100 个）。 #### 请求参数 | 参数 | 类型 | 必填 | 说明 | |-----|------|-----|------| | taskIds | string[] | 是 | 任务 ID 列表，最多 100 个 | #### 请求示例 ```json { "taskIds": ["task_20260831150000_abc12345", "task_20260831150200_def67890"] } ``` --- ## 回调通知 当任务完成（成功或失败）时，如果创建任务时提供了 `callbackUrl`，系统会向该 URL 发送 POST 请求。 ### 回调请求 **Headers** ``` Content-Type: application/json X-Funcloud-Event: task.completed X-Funcloud-Signature: {签名} ``` **Body** ```json { "event": "task.completed", "taskId": "task_20260831150000_abc12345", "status": "success", "result": ["https://fc-gw-sh.oss-accelerate.aliyuncs.com/videos/output.mp4"], "errorMsg": "", "timestamp": "2026-08-31T15:02:30+08:00", "signature": "a1b2c3d4e5f6..." } ``` --- ## 参数取值范围 ### 分辨率 (resolution) | 值 | 说明 | |----|------| | `768p` | 默认，推荐 | | `480p` | 低清，成本更低 | > 本模型不支持 2K；传入其他值将回退为默认 `768p`。 ### 宽高比 (aspectRatio) | 值 | 说明 | |----|------| | `21:9` | 超宽屏 | | `16:9` | 横屏（默认） | | `4:3` | 标准横屏 | | `1:1` | 方形 | | `3:4` | 标准竖屏 | | `9:16` | 竖屏 | > 传入首帧 / 尾帧时输出画幅按图片自适应，本参数不生效。 ### 时长 (duration) - 范围：5 ~ 15 秒 - 默认：5 秒 - 传入越界值将回退为默认 5 秒 --- ## 计费说明 按视频时长（秒）计费，分辨率越高单价越高（`480p` < `768p`）。首尾帧**不额外计费**。 下单时按 15 秒上限预冻结额度，任务完成后按实际请求时长结算并退回差额（只退不追）；任务失败则全额解冻。 --- ## 错误码 | code | 说明 | |------|------| | 0 | 成功 | | 10002 | 参数缺失或格式错误 | | 10005 | API Key 无效或缺失 | | 10006 | 余额不足 | | 30003 | 任务不存在 | | 90003 | 服务器内部错误 | --- ## 最佳实践 ### 1. 轮询策略 建议的轮询间隔： - 前 30 秒：每 3 秒查询一次 - 30 秒 ~ 2 分钟：每 5 秒查询一次 - 2 分钟后：每 10 秒查询一次 ### 2. 处理时间参考 - 纯文本生视频：通常 1 ~ 3 分钟 - 首尾帧生视频：通常 1 ~ 3 分钟 - 时长越长、分辨率越高，处理时间越长 ### 3. Prompt 建议 - 提示词最长 7000 字符 - 提示词 = 主体 + 运动，背景 + 运动，镜头 + 运动 - 用简洁准确的自然语言描述想要的效果 - 可以指定镜头运动（推进、拉远、环绕等） - 结果不符合预期时，建议将抽象描述换成具象描述再重试 --- ## 常见问题 ### Q1: 如何选择 T2V / I2V？ **A**: 无需显式声明。只传 `prompt` 为文生视频；传入 `firstFrameImage` 和/或 `lastFrameImage` 为图生视频。 ### Q2: 可以传参考图 / 参考视频 / 参考音频吗？ **A**: 不可以。本模型仅支持首帧、尾帧图片。需要参考图、参考视频或参考音频请改用 MiniMax-H3。 ### Q3: 支持 2K 分辨率吗？ **A**: 不支持。本模型仅提供 `480p` 与 `768p` 两档，传入其他值会回退为 `768p`。 ### Q4: 只传尾帧可以吗？ **A**: 可以。首帧、尾帧可只传其一，也可同时传入。 ### Q5: 时长可以超过 15 秒吗？ **A**: 不可以。范围为 5 ~ 15 秒，越界会回退为默认 5 秒。 --- ## 技术支持 如有疑问，请联系我们的技术支持团队。