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

# MiniMax H3

> MiniMax H3 视频生成参数、多模态输入与输出设置。

`MiniMax-H3` 支持文生视频、基于首尾帧的图生视频和多模态参考生成。顶层保留 `model`、`prompt`，厂商输入内容及输出控制项统一放入 `metadata`。

`POST https://api.mixroute.ai/v1/video/generations`

## 请求参数

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 使用区分大小写的 MixRoute 模型 ID `MiniMax-H3`。 |
| `prompt` | string | 是 | MixRoute 提示词，与 `metadata.content` 中的文本保持一致。 |
| `metadata` | object | 是 | 下列厂商必填字段及可选字段的容器。 |
| `metadata.content` | object\[] | 是 | 多模态输入列表。每个请求必须包含至少一个非空 `text` 项；纯文本生成使用一个文本项，图像、视频、音频输入须遵守下方场景规则。 |
| `metadata.resolution` | string | 是 | 输出分辨率为 `768P` 或 `2K`，大小写必须一致，须显式提供。 |
| `metadata.duration` | integer | 是 | 输出时长为 4-15 秒的整数，包含端点，须显式提供。 |
| `metadata.ratio` | string | 按场景 | 取值为 `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。默认 `adaptive`，但纯文本生成必须显式选择具体比例；首尾帧图生视频始终按输入图像比例适配。 |
| `metadata.callback_url` | string | 否 | 任务状态回调 URL。首次请求携带 `challenge`，须在 3 秒内原样返回；后续 POST 通知使用厂商任务查询结构，状态为 `queued`、`running`、`succeeded`、`failed` 或 `cancelled`。 |

## 内容项

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `metadata.content[].type` | string | 是 | `text`、`image_url`、`video_url` 或 `audio_url`。 |
| `metadata.content[].text` | string | 按场景 | 文本项必填且不能为空，每项最多 7000 个字符。 |
| `metadata.content[].image_url.url` | string | 按场景 | 图像项必填。支持公网 URL、可访问的 `mm_file://{file_id}` 或 `data:image/<format>;base64,...`，格式名须小写。 |
| `metadata.content[].video_url.url` | string | 按场景 | 视频参考项必填。支持公网 URL、可访问的 `mm_file://{file_id}` 或 `data:video/mp4;base64,...`。 |
| `metadata.content[].audio_url.url` | string | 按场景 | 音频参考项必填。支持公网 URL、可访问的 `mm_file://{file_id}` 或 `data:audio/<format>;base64,...`，格式名须小写。 |
| `metadata.content[].role` | string | 按场景 | 首尾帧输入使用 `first_frame` 或 `last_frame`；单张图像未指定角色时默认首帧。参考输入使用与内容类型对应的 `reference_image`、`reference_video` 或 `reference_audio`。 |

## 输入模式

| 模式 | `metadata.content` | `metadata.ratio` |
| - | - | - |
| 文生视频 | `text` | 必须为具体比例，不能为 `adaptive`。 |
| 首帧 | `text` + `image_url` (`first_frame`) | 始终为 `adaptive`，其他有效比例值会被忽略。 |
| 尾帧 | `text` + `image_url` (`last_frame`) | 始终为 `adaptive`，按图像比例适配。 |
| 首尾帧 | `text` + 2 `image_url` (`first_frame`, `last_frame`) | 始终为 `adaptive`，其他有效比例值会被忽略。 |
| 参考生视频 | `text` + `reference_*` | 可选，默认 `adaptive`，也可指定具体比例。 |

首尾帧角色与参考角色互斥。厂商文件 ID 必须能被上游账户访问，它不是 MixRoute 任务 ID。本页仅说明 `MiniMax-H3`，不套用到其他 H3 变体。

## 媒体限制

| 媒体 | 限制 |
| - | - |
| 图像 | JPG/JPEG/PNG/WebP/HEIC/HEIF；单个不超过 30 MB，宽高各为 256-5760 px，比例 0.4-2.5。首帧、尾帧各最多一张，参考图最多九张。 |
| 参考视频 | MP4/MOV，视频编码为 H.264/H.265，音频编码为 AAC/MP3。单个不超过 50 MB，最多三段，每段 2-15 秒且合计不超过 15 秒；宽高各为 256-5760 px，比例 0.4-2.5，帧率 23.976-60 fps。 |
| 参考音频 | WAV/MP3；单个不超过 15 MB，最多三段，每段 2-15 秒且合计不超过 15 秒。 |
| 请求 | 包括 Base64 编码开销在内不超过 64 MB，大文件优先使用公网 URL。 |

## 调用示例

调用前设置环境变量 `MIXROUTE_API_KEY`，并将媒体占位值替换为可访问的素材。请求被接受后会创建计费任务；提交超时后不要自动重复提交。

<Tabs>
  <Tab title="文生视频">
    ```bash theme={null}
    curl --location "https://api.mixroute.ai/v1/video/generations" \
      --header "Authorization: Bearer $MIXROUTE_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
      "model": "MiniMax-H3",
      "prompt": "A blue circle gently pulses on a clean white background.",
      "metadata": {
        "content": [
          {
            "type": "text",
            "text": "A blue circle gently pulses on a clean white background."
          }
        ],
        "resolution": "768P",
        "duration": 4,
        "ratio": "9:16"
      }
    }'
    ```
  </Tab>

  <Tab title="首尾帧">
    ```bash theme={null}
    curl --location "https://api.mixroute.ai/v1/video/generations" \
      --header "Authorization: Bearer $MIXROUTE_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
      "model": "MiniMax-H3",
      "prompt": "A professor is teaching a class in a classroom.",
      "metadata": {
        "content": [
          {
            "type": "text",
            "text": "A professor is teaching a class in a classroom."
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://static.freebeatfit.com/aiImageEdit/result/L001510027166320955392/1780060289776-1.png"
            },
            "role": "first_frame"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://static.freebeatfit.com/aiImageEdit/result/M1509975287180300288_0004_1780047826.png"
            },
            "role": "last_frame"
          }
        ],
        "resolution": "768P",
        "duration": 4,
        "ratio": "adaptive"
      }
    }'
    ```
  </Tab>

  <Tab title="视频与音频参考">
    ```bash theme={null}
    curl --location "https://api.mixroute.ai/v1/video/generations" \
      --header "Authorization: Bearer $MIXROUTE_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
      "model": "MiniMax-H3",
      "prompt": "Preserve the scene in the reference video and follow the reference audio.",
      "metadata": {
        "content": [
          {
            "type": "text",
            "text": "Preserve the scene in the reference video and follow the reference audio."
          },
          {
            "type": "video_url",
            "video_url": {
              "url": "https://example.com/reference.mp4"
            },
            "role": "reference_video"
          },
          {
            "type": "audio_url",
            "audio_url": {
              "url": "https://example.com/reference.mp3"
            },
            "role": "reference_audio"
          }
        ],
        "resolution": "2K",
        "duration": 4,
        "ratio": "adaptive"
      }
    }'
    ```
  </Tab>
</Tabs>

### Python

```python theme={null}
import json
import os
import requests

payload = json.loads(r'''
{
  "model": "MiniMax-H3",
  "prompt": "A blue circle gently pulses on a clean white background.",
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "A blue circle gently pulses on a clean white background."
      }
    ],
    "resolution": "768P",
    "duration": 4,
    "ratio": "9:16"
  }
}
''')
response = requests.post(
    "https://api.mixroute.ai/v1/video/generations",
    headers={"Authorization": "Bearer " + os.environ["MIXROUTE_API_KEY"]},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

## 任务结果

保存提交响应中的 MixRoute 任务 ID，并调用 [查询视频任务](/zh-hans/api-reference/endpoint/query-video-task)。提交成功表示任务已创建；任务完成后再读取生成结果。不同路由的响应封装和结果位置可能不同。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.