> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# MiniMax H3 影片生成 API 串接指南
> Minimax 整合指南 - Ace Data Cloud
本文介紹 MiniMax H3 影片生成 API 的串接與使用。該介面支援文字生成影片、首尾幀控制與多模態參考生成影片，使用統一的 V2 多模態 `content` 結構建立任務。
## 申請流程
要使用 MiniMax H3 影片生成 API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 取得您的 API Token，留作備用。
如果你尚未登入或註冊，會自動跳轉到登入頁面邀請你註冊和登入，完成後會自動返回目前頁面。
**一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 儲值通用餘額。
> 📘 完整文件：[MiniMax H3 影片生成 API →](https://platform.acedata.cloud/documents/minimax-videos-integration)
建議把 Token 儲存為環境變數，不要寫入原始碼或提交到版本庫：
```bash theme={null}
export ACEDATACLOUD_API_KEY="YOUR_API_KEY"
```
## 介面概覽
* **Base URL**：`https://api.acedata.cloud`
* **Endpoint**：`POST /minimax/videos`
* **驗證方式**：HTTP Header 中攜帶 `authorization: Bearer {token}`
* **請求標頭**：
* `accept: application/json`
* `content-type: application/json`
* **模型（model）**：`MiniMax-H3`
* **輸入結構**：透過 `content` 統一傳入文字、圖片、影片和音訊
* **輸出模式**：預設同步等待生成完成並返回完整 `task`；傳入 `async: true` 或 `callback_url` 時立即返回 `task_id` 與 `trace_id`
* **結果查詢**：透過 [MiniMax H3 任務查詢 API](https://platform.acedata.cloud/documents/minimax-tasks-integration) 取得狀態和成片
* **非同步回呼**：可選，透過 `callback_url` 接收最終任務結果
你不需要傳入 `action` 來選擇生成模式，介面會根據 `content` 中的素材類型和 `role` 自動判斷用途。
## 適合哪些情境
| 情境 | 輸入組合 | 常見用途 |
| - | - | - |
| 文字生成影片 | 文字 | 廣告創意、分鏡預演、短影片、氛圍鏡頭 |
| 首幀圖片生成影片 | 文字 + 首幀圖片 | 讓商品圖、海報、人物照片或插畫自然動起來 |
| 尾幀 / 首尾幀影片 | 文字 + 尾幀，或文字 + 首幀 + 尾幀 | 控制片頭與片尾、轉場、成長變化和前後對比 |
| 多模態參考生成影片 | 文字 + 參考圖片 / 影片 / 音訊 | 保持角色和產品一致，複刻動作、運鏡、音色或剪輯節奏 |
## 呼叫流程
預設不傳入 `async` 時，`/minimax/videos` 會等待生成完成並直接返回完整 `task`。需要立即釋放連線時，傳入 `async: true` 或 `callback_url`：
1. 儲存立即回應中的 `task_id` 和 `trace_id`。
2. 未設定回呼時，每隔約 10 秒呼叫 `/minimax/tasks` 查詢一次。
3. 當 `task.status` 變為 `succeeded` 時，從 `task.content.url` 取得影片。
4. 當狀態為 `failed` 或 `cancelled` 時停止輪詢，並讀取 `task.error`。
## 頂層請求參數
| 參數 | 類型 | 必填 | 預設值 | 說明 |
| - | - | - | - | - |
| `model` | string | 是 | - | 固定為 `MiniMax-H3` |
| `content` | object\[] | 是 | - | 多模態內容陣列，必須包含一個非空的 `text` 項目 |
| `resolution` | string | 是 | - | `768P` 或 `2K` |
| `duration` | integer | 是 | - | 生成時長，4-15 秒整數 |
| `ratio` | string | 條件必填 | `adaptive` | `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16` |
| `async` | boolean | 否 | `false` | `true` 時立即返回任務識別資訊，透過任務介面取得結果 |
| `callback_url` | string | 否 | - | 接收最終任務結果的公開回呼 URL；提供後自動啟用非同步模式 |
`ratio` 的規則取決於工作流程：
* **文字生成影片**：必填，且不能為 `adaptive`。
* **首幀、尾幀或首尾幀影片**：畫幅由輸入圖片決定，建議省略或傳入 `adaptive`。
* **多模態參考生成影片**：可省略，預設為 `adaptive`；也可以明確指定一個固定比例。
介面不接受舊版或相容欄位，例如 `prompt`、`image_urls`、`audio_urls`、`messages` 和 `first_frame_image`。收到這類參數錯誤時，請刪除舊欄位並遷移至 `content`；例如把 `"prompt": "一隻貓揮手"` 改為 `"content": [{"type": "text", "text": "一隻貓揮手"}]`。不要同時傳送新舊兩種格式。
## content 內容項目參數
每個內容項目都必須有 `type`，其餘欄位由類型決定：
| `type` | 資料欄位 | `role` | 說明 |
| - | - | - | - |
| `text` | `text` | 不傳 | 每個請求必須包含一個非空文字項目，最長 7000 字元 |
| `image_url` | `image_url.url` | `first_frame` | 首幀圖片；只有一張圖片且省略 `role` 時，也按首幀處理 |
| `image_url` | `image_url.url` | `last_frame` | 尾幀圖片；可單獨使用，也可與 `first_frame` 組合控制起點和終點 |
| `image_url` | `image_url.url` | `reference_image` | 參考主體、角色、產品、服裝、場景或風格 |
| `video_url` | `video_url.url` | `reference_video` | 參考動作、運鏡、表演或剪輯結構 |
| `audio_url` | `audio_url.url` | `reference_audio` | 參考音色、對白、音樂或節奏 |
媒體位址支援三種形式：
* 可公開存取的 HTTPS URL，建議用於大型檔案。
* `mm_file://{file_id}`，引用已上傳或已有結果的檔案。
* 對應媒體類型的 Base64 data URI。Base64 會使體積增加約三分之一，請確保整個請求本體不超過 64 MB。
## 素材規格與數量限制
| 素材 | 格式 | 單檔限制 | 尺寸 / 時長 | 數量限制 |
| - | - | - | - | - |
| 圖片 | 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 | 每段 2-15 秒，合計不超過 15 秒；寬高均為 256-5760 px；寬高比 0.4-2.5；23.976-60 fps | 最多 3 段參考影片 |
| 音訊 | WAV、MP3 | 不超過 15 MB | 每段 2-15 秒，合計不超過 15 秒 | 最多 3 段參考音訊 |
多模態參考場景中的圖片、影片和音訊合計最多 12 個檔案。首尾幀場景和參考素材場景互斥：一旦使用 `reference_image`、`reference_video` 或 `reference_audio`，就不能再使用 `first_frame` 或 `last_frame`，反之亦然。
## 生產級能力展示
下面不是概念圖或佔位素材，而是 MiniMax H3 官方生產級能力樣片的真實參考輸入與實際影片輸出。三組案例分別涵蓋品牌短片、真人敘事和時尚電商，適合評估模型在商業製作中最關鍵的能力。
| 能力 | 重點觀察 |
| - | - |
| 人物與人臉一致性 | 多鏡頭切換後五官、髮型、妝容和人物氣質是否穩定 |
| 臉部表演 | 近景中的眼神、微表情、情緒張力和自然頭部運動 |
| 商品結構保持 | 眼鏡、手袋等產品的輪廓、材質、佩戴關係和鏡面反射 |
| 品牌視覺執行 | 場景氛圍、電影顆粒、色彩、Logo 與剪輯節奏是否統一 |
| 電影化敘事 | 景別變化、人物調度、運鏡、節奏和聲音能否形成完整段落 |
這裡的「人臉能力」指影片生成中的人物外觀一致性、臉部細節和表演控制，不是身分識別、人臉比對或換臉介面。
### 高端品牌短片：人物、產品與品牌資產統一
**製作目標：** 16:9 高級時裝品牌片。以荒漠公路和復古汽車建立冷峻氛圍，保持女主角外觀與黑色手袋結構，並將品牌 Logo 自然納入結尾。這個案例重點檢驗跨鏡頭人物一致性、商品保持、電影質感和品牌收束能力。
| 氛圍與場景參考 | 人物參考 |
| - | - |
| 
| 
|
| 手袋產品參考 | 品牌 Logo 參考 |
| - | - |
| 
| 
|
[直接開啟或下載品牌短片](https://cdn.acedata.cloud/uploads/6845b11d-1a58-4478-afd8-29e7e117772a)
對應的 `content` 組織方式：
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "15 秒、16:9 高級時裝品牌片。荒漠公路旁停著復古汽車，女主從後車廂取出黑色手袋，與男主短暫對視後獨自離開。保持人物、手袋與品牌視覺一致；冷峻高級，電影顆粒，剪輯俐落，結尾自然呈現品牌 Logo。"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/6e65f865-f1c2-4f80-8b51-9a98d4d930b1" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/88d89cc3-e6cb-42b4-ab4c-1bbbf6c9f7c8" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/e91f7fff-f8e3-4da5-b882-87edbc3c9473" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/b68dac43-fb14-42b5-bf8b-fd4d65506520" },
"role": "reference_image"
}
],
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}
```
### 真人直式短劇：人臉一致性與情緒表演
**製作目標：** 15 秒、9:16 暗黑浪漫短劇預告。透過男女主角參考圖鎖定人物外觀，以古堡參考圖約束空間；使用中近景與面部特寫表現眼神對峙、恐懼、克制和危險感。這個案例適合觀察真人五官穩定性、微表情、視線關係和連續表演。
| 男女主角參考 | 古堡場景參考 |
| - | - |
| 
| 
|
[直接開啟或下載真人短劇](https://cdn.acedata.cloud/uploads/0f3e9bf2-5073-46f4-9a2d-7d8d912391cf)
提示詞應明確人物關係、情緒和景別，而不只是描述「男女對話」：
```text theme={null}
15 秒、9:16 真人暗黑浪漫短劇預告。女主誤入禁忌古堡，喚醒沉睡的吸血鬼貴族；
他危險而克制地靠近，她恐懼但不屈服。保持兩位角色的五官、髮型與服裝一致，
以中近景和面部特寫表現眼神對峙與情緒張力，暗色電影光線，節奏緊湊。
```
### 時尚眼鏡廣告：人臉細節與商品結構保持
**製作目標：** 9:16 高級時尚眼鏡廣告。人物全身圖負責身形與台步，人臉參考圖負責五官和妝容，產品圖負責環繞曲線、鏡片反射、鏡腳和貓眼輪廓。這個案例同時考驗臉部近景、多人一致性、佩戴關係和商品幾何結構。
| 模特兒與造型參考 | 人臉細節參考 | 眼鏡產品參考 |
| - | - | - |
| 
| 
| 
|
[直接開啟或下載時尚眼鏡廣告](https://cdn.acedata.cloud/uploads/55715089-b6bd-4ef6-a3c2-e762a672f751)
在商品廣告中，提示詞應把人物參考和產品參考的職責分開寫清楚：人物素材約束臉、妝容、身形和氣質；產品素材約束輪廓、材質、反射和佩戴位置。這樣比籠統地寫「生成一支眼鏡廣告」更穩定。
## 文生影片
只有一個文字項時即為文生影片。適合從創意、腳本或鏡頭描述直接生成畫面。提示詞可以按「主體 + 動作 + 場景 + 鏡頭 + 光線 + 聲音」的順序組織。
```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/videos' \
-H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "15 秒電影級香水廣告：清晨海岸的黑色礁石上，透明香水瓶被薄霧與海浪環繞。微距展現瓶身水珠和玻璃折射，鏡頭從產品特寫緩慢拉升到廣闊海面；銀藍色調，真實自然光，高級克制，結尾定格產品。"
}
],
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}'
```
預設同步模式會在生成完成後傳回完整任務：
```json theme={null}
{
"task": {
"id": "f5977217-ed2c-40da-adbe-93d08235618f",
"model": "MiniMax-H3",
"status": "succeeded",
"content": { "url": "https://cdn.acedata.cloud/minimax/f5977217.mp4" },
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}
}
```
若請求中加入 `"async": true`，介面立即傳回：
```json theme={null}
{
"task_id": "f5977217-ed2c-40da-adbe-93d08235618f",
"trace_id": "trace_7f8c2b1a"
}
```
## 首幀圖生影片
將圖片標記為 `first_frame`，模型會從該畫面開始生成。適合讓海報、商品圖、角色設定圖和攝影作品自然動起來。
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "人物自然呼吸並看向窗外，衣角被微風吹動，鏡頭緩慢推進"
},
{
"type": "image_url",
"image_url": {
"url": "https://cdn.acedata.cloud/b1c82e4937.png"
},
"role": "first_frame"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
## 尾幀和首尾幀影片
僅提供 `last_frame` 可以讓模型自然生成至指定畫面；同時提供 `first_frame` 與 `last_frame`，可以明確控制起點和終點。適合轉場、形態變化、成長過程或產品前後對比。
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "女孩从童年自然成长为青年，时间流逝平滑，人物始终位于画面中央"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_FIRST_FRAME_URL" },
"role": "first_frame"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_LAST_FRAME_URL" },
"role": "last_frame"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
首幀與尾幀的尺寸和寬高比應盡量一致，主體位置、構圖和光線差異不要過大，這樣更容易得到自然過渡。
## 多模態參考生影片
參考素材可以組合使用：參考圖片控制角色或產品外觀，參考影片控制動作和運鏡，參考音訊控制對白音色、音樂或剪輯節奏。提示詞中應明確說明每類素材要控制什麼，避免只上傳素材卻不給出關聯關係。
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "保持参考人物的五官、发型与服装一致，按照参考视频中的表演动作完成时尚短片；镜头节奏跟随参考音频，近景突出自然面部表情"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_CHARACTER_IMAGE_URL" },
"role": "reference_image"
},
{
"type": "video_url",
"video_url": { "url": "YOUR_PERFORMANCE_VIDEO_URL" },
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": { "url": "YOUR_AUDIO_URL" },
"role": "reference_audio"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
## 回呼通知
傳入 `callback_url` 會自動啟用非同步模式：建立介面立即返回 `task_id` 和 `trace_id`，並在任務完成後向該地址 POST 最終結果，結構與任務查詢回應一致。
回呼中的最終狀態為 `succeeded`、`failed` 或 `cancelled`。即使使用回呼，也建議儲存 `task_id`，以便主動查詢或補償遺漏的通知。
## 常見錯誤
| HTTP 狀態碼 | 含義 | 處理建議 |
| - | - | - |
| `400` | 參數錯誤或素材組合不合法 | 檢查必填欄位、`role`、素材數量和格式 |
| `401` | Token 缺失或無效 | 檢查 `Authorization: Bearer ...` |
| `402` | 餘額或額度不足 | 在控制台補充通用餘額 |
| `422` | 內容安全檢查未通過 | 調整提示詞或素材後重新提交 |
| `429` | 請求過於頻繁 | 指數退避後重試；任務輪詢建議間隔約 10 秒 |
| `500` | 服務暫時不可用 | 保留請求資訊，稍後重試 |
同步回應中的 `task.status: succeeded` 表示影片已生成；非同步確認只代表任務已進入佇列。只有任務最終成功時才會計費，查詢任務本身免費，不會重複扣費。
### H3 Max
`MiniMax-H3-Max` 支援 480P 或 768P、5–15 秒整數時長。音訊輸入不額外計費，前 2 張圖片免費，超出部分逐張計費；參考影片按實際輸入時長計費。該模型不支援 2K。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.