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

# MiniMax H3 视频生成示例

> 通过平台 OpenAI 兼容视频接口调用 MiniMax-H3，支持文本、首尾帧及图片/视频/音频参考输入。

# MiniMax H3 视频生成示例

您可以通过平台统一的异步视频接口调用 MiniMax-H3。完整流程分为三步：

1. 调用 `POST /v1/videos` 创建任务；
2. 调用 `GET /v1/videos/{video_id}` 轮询任务状态；
3. 任务完成后使用响应中的 `url`，或调用 `GET /v1/videos/{video_id}/content` 下载视频。

<Note>
  请以本文中的平台接口字段为准。平台已将 MiniMax 原生字段适配为统一视频接口，例如使用 `seconds` 表示输出时长、使用 `watermark` 控制 AIGC 水印。当前支持 `768P` 和 `2K`，不支持 `720P`、`1080P` 等其他分辨率。
</Note>

## 快速开始

### 创建任务

```bash cURL theme={null}
curl --request POST \
  --url https://model-api.skyengine.com.cn/v1/videos \
  --header 'Authorization: Bearer <API-KEY>' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "清晨，一只橘猫沿着海边奔跑，电影感镜头，阳光穿过薄雾"
      }
    ],
    "resolution": "2K",
    "ratio": "16:9",
    "seconds": "4",
    "watermark": false
  }'
```

创建成功后返回任务 ID：

```json theme={null}
{
  "id": "426740781494778",
  "object": "video.generation",
  "created_at": 1785743414,
  "model": "MiniMax-H3",
  "status": "pending"
}
```

### 查询任务

任务 ID 可用于查询最近 7 天内的任务。建议保存任务 ID，并在创建后及时轮询和下载结果。

```bash cURL theme={null}
curl --request GET \
  --url https://model-api.skyengine.com.cn/v1/videos/426740781494778 \
  --header 'Authorization: Bearer <API-KEY>'
```

任务状态可能为：

| 状态            | 说明              |
| ------------- | --------------- |
| `pending`     | 已创建，等待处理        |
| `in_progress` | 正在生成            |
| `completed`   | 已完成，可下载         |
| `failed`      | 生成失败，查看 `error` |

完成响应示例：

```json theme={null}
{
  "id": "426740781494778",
  "object": "video.generation",
  "model": "MiniMax-H3",
  "status": "completed",
  "seconds": "4",
  "size": "2K",
  "url": "https://example.com/generated-video.mp4",
  "usage": {
    "input_video_seconds": 6,
    "output_video_seconds": 4,
    "input_image_count": 0
  }
}
```

### 下载视频

```bash cURL theme={null}
curl --request GET \
  --url https://model-api.skyengine.com.cn/v1/videos/426740781494778/content \
  --header 'Authorization: Bearer <API-KEY>' \
  --output minimax-h3.mp4
```

<Warning>
  完成响应中的 `url` 可能带有效期。需要长期保存时，请在任务完成后及时下载或转存，不要将临时 URL 持久化为永久资源地址。
</Warning>

## 请求参数

| 参数           | 类型      | 必填   | 说明                                                           |
| ------------ | ------- | ---- | ------------------------------------------------------------ |
| `model`      | string  | 是    | 固定为 `MiniMax-H3`                                             |
| `content`    | array   | 是    | 多模态输入数组；必须包含至少一个非空 `text` 项，建议只提供一个文本项                       |
| `resolution` | string  | 是    | `768P` 或 `2K`；大小写不敏感，不支持 `720P`                              |
| `seconds`    | string  | 是    | 整数，范围 `"4"`～`"15"`                                           |
| `ratio`      | string  | 条件必填 | 支持 `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`，具体规则见下文 |
| `watermark`  | boolean | 否    | 是否添加 AIGC 水印，默认 `false`                                      |

不同生成模式的 `ratio` 规则如下：

| 生成模式         | `ratio` 规则                           |
| ------------ | ------------------------------------ |
| 文生视频         | 必填，且不能为 `adaptive`                   |
| 首帧/尾帧/首尾帧生视频 | 输出比例由输入图片决定；建议传 `adaptive`，其他合法值会被忽略 |
| 多模态参考生视频     | 可选，默认 `adaptive`；也可以指定具体比例           |

生成较低分辨率视频时，将 `resolution` 设置为 `768P`：

```json theme={null}
{
  "model": "MiniMax-H3",
  "content": [{ "type": "text", "text": "海边日落，电影感镜头" }],
  "resolution": "768P",
  "ratio": "16:9",
  "seconds": "4"
}
```

<Note>
  MiniMax-H3 的低分辨率规格名称是 `768P`，不是 `720P`。平台也接受 `768p`，并在调用 MiniMax-H3 时规范化为 `768P`。
</Note>

### content 类型与 role

| type        | role              | 用途                                                |
| ----------- | ----------------- | ------------------------------------------------- |
| `text`      | 不填                | 提示词；必须至少提供一项非空文本，建议只提供一项；平台最多接收 7000 个 Unicode 字符 |
| `image_url` | `first_frame`     | 首帧图片；单张图片不填 role 时也按首帧处理                          |
| `image_url` | `last_frame`      | 尾帧图片                                              |
| `image_url` | `reference_image` | 多模态参考图片，最多9张                                      |
| `video_url` | `reference_video` | 多模态参考视频，最多3个                                      |
| `audio_url` | `reference_audio` | 多模态参考音频，最多3个                                      |

首帧/尾帧模式与 `reference_*` 多模态参考模式互斥。`reference_audio` 不能单独使用，必须同时提供至少一个 `reference_image` 或 `reference_video`。

### 输入媒体限制

媒体必须使用 MiniMax 服务可访问的公网 HTTP/HTTPS URL。不要使用 Base64 或 data URI；请求体总大小不能超过 64 MB。建议使用稳定的 HTTPS URL，并确保任务处理期间 URL 不会过期。

#### 图片

| 项目       | 限制                          |
| -------- | --------------------------- |
| 格式       | JPG、JPEG、PNG、WEBP、HEIC、HEIF |
| 单文件大小    | 不超过 30 MB                   |
| 宽、高      | 均在 256～5760 px 范围内          |
| 宽高比（宽/高） | 0.4～2.5                     |
| 数量       | 首帧最多1张、尾帧最多1张、参考图片最多9张      |

#### 视频

| 项目       | 限制                      |
| -------- | ----------------------- |
| 格式       | MP4、MOV                 |
| 视频编码     | H.264/AVC、H.265/HEVC    |
| 视频内音频编码  | AAC、MP3                 |
| 单文件大小    | 不超过 50 MB               |
| 数量       | 最多3个                    |
| 时长       | 单段2～15秒，全部参考视频总时长不超过15秒 |
| 宽、高      | 均在 256～5760 px 范围内      |
| 宽高比（宽/高） | 0.4～2.5                 |
| 帧率       | 23.976～60 fps           |

#### 音频

| 项目    | 限制                      |
| ----- | ----------------------- |
| 格式    | WAV、MP3                 |
| 单文件大小 | 不超过 15 MB               |
| 数量    | 最多3个                    |
| 时长    | 单段2～15秒，全部参考音频总时长不超过15秒 |

## 首帧生成视频

```json theme={null}
{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "保持人物外观，从静止状态开始自然向镜头挥手"
    },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {
        "url": "https://example.com/first-frame.jpg"
      }
    }
  ],
  "resolution": "2K",
  "ratio": "adaptive",
  "seconds": "4",
  "watermark": false
}
```

## 首尾帧生成视频

```json theme={null}
{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "镜头平滑推进，人物从室内自然走到窗边"
    },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {
        "url": "https://example.com/first-frame.jpg"
      }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": {
        "url": "https://example.com/last-frame.jpg"
      }
    }
  ],
  "resolution": "2K",
  "ratio": "adaptive",
  "seconds": "6"
}
```

## 图片、视频和音频参考

```bash cURL theme={null}
curl --request POST \
  --url https://model-api.skyengine.com.cn/v1/videos \
  --header 'Authorization: Bearer <API-KEY>' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "保持参考图片中的主体外观，参考视频中的动作和镜头运动，并结合参考音频自然生成画面"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": {
          "url": "https://example.com/character.jpg"
        }
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": {
          "url": "https://example.com/motion.mp4"
        }
      },
      {
        "type": "audio_url",
        "role": "reference_audio",
        "audio_url": {
          "url": "https://example.com/reference.mp3"
        }
      }
    ],
    "resolution": "2K",
    "ratio": "16:9",
    "seconds": "4",
    "watermark": false
  }'
```

## Python 完整流程

```python Python theme={null}
import time
import requests

API_KEY = "<API-KEY>"
BASE_URL = "https://model-api.skyengine.com.cn/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

request_body = {
    "model": "MiniMax-H3",
    "content": [
        {
            "type": "text",
            "text": "雪山日出，金色晨光照亮山峰，镜头缓慢向前推进",
        }
    ],
    "resolution": "2K",
    "ratio": "16:9",
    "seconds": "4",
    "watermark": False,
}

create_response = requests.post(
    f"{BASE_URL}/videos",
    headers={**HEADERS, "Content-Type": "application/json; charset=utf-8"},
    json=request_body,
)
create_response.raise_for_status()
video_id = create_response.json()["id"]

while True:
    status_response = requests.get(
        f"{BASE_URL}/videos/{video_id}", headers=HEADERS
    )
    status_response.raise_for_status()
    task = status_response.json()
    print("status:", task["status"])

    if task["status"] == "completed":
        break
    if task["status"] == "failed":
        raise RuntimeError(task.get("error", "video generation failed"))
    time.sleep(5)

content_response = requests.get(
    f"{BASE_URL}/videos/{video_id}/content", headers=HEADERS
)
content_response.raise_for_status()
with open("minimax-h3.mp4", "wb") as output_file:
    output_file.write(content_response.content)
```

## Usage 与计费

任务完成后，`usage` 返回本次任务的实际用量：

| 字段                     | 含义            |
| ---------------------- | ------------- |
| `input_video_seconds`  | 输入参考视频的实际计费秒数 |
| `output_video_seconds` | 输出视频的实际计费秒数   |
| `input_image_count`    | 输入参考图片数量      |

平台按模型广场展示的当前价格配置计费。当前参考图片计费量为 `max(input_image_count - 5, 0)`；是否收取输入视频、输出视频或音频费用，以调用时模型广场展示的各用量维度价格为准。

<Warning>
  视频生成通常需要较长处理时间并产生较高费用。`seconds`、输入视频总时长和参考图片数量可能增加计费用量。平台当前未按 `768P` 与 `2K` 区分单价；请在批量调用前查看模型广场的最新价格。
</Warning>

## 常见错误

| 场景                     | 处理建议                                                      |
| ---------------------- | --------------------------------------------------------- |
| 中文提示词乱码                | 使用 UTF-8 JSON；cURL 建议设置 `application/json; charset=utf-8` |
| 文生视频使用 `adaptive`      | 改为明确画幅，例如 `16:9`                                          |
| `reference_audio` 单独使用 | 同时提供 `reference_image` 或 `reference_video`                |
| 首尾帧和 reference 混用      | 二选一，不要在同一请求中混用                                            |
| 图片超过9张、视频或音频超过3个       | 减少输入媒体数量                                                  |
| 媒体 URL 无法访问或提前过期       | 使用无需登录、在任务处理期间持续有效的公网 HTTPS URL                           |
| 输入媒体格式或尺寸不符合要求         | 按“输入媒体限制”检查格式、编码、大小、像素、时长和帧率                              |
| 查询一直处于处理中              | 保持轮询间隔，建议5～20秒；不要重复创建相同任务                                 |