> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/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/;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/;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`，並將媒體佔位值替換為可訪問的素材。請求被接受後會建立計費任務；提交超時後不要自動重複提交。
```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"
}
}'
```
```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"
}
}'
```
```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"
}
}'
```
### 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，並呼叫 [查詢影片任務](/docs/zh-hant/api-reference/endpoint/query-video-task)。提交成功表示任務已建立；任務完成後再讀取生成結果。不同路由的響應封裝和結果位置可能不同。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.