跳轉到主要內容
本文介紹 MiniMax H3 影片生成 API 的串接與使用。該介面支援文字生成影片、首尾幀控制與多模態參考生成影片,使用統一的 V2 多模態 content 結構建立任務。

申請流程

要使用 MiniMax H3 影片生成 API,首先到 Ace Data Cloud 控制台 取得您的 API Token,留作備用。 如果你尚未登入或註冊,會自動跳轉到登入頁面邀請你註冊和登入,完成後會自動返回目前頁面。 一個 API Token 即可呼叫平台所有服務,無需為每個服務個別申請。 首次申請會贈送免費額度,可免費體驗;額度不足時可在 控制台 儲值通用餘額。
📘 完整文件:MiniMax H3 影片生成 API →
建議把 Token 儲存為環境變數,不要寫入原始碼或提交到版本庫:

介面概覽

  • 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 取得狀態和成片
  • 非同步回呼:可選,透過 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。

頂層請求參數

ratio 的規則取決於工作流程:
  • 文字生成影片:必填,且不能為 adaptive。
  • 首幀、尾幀或首尾幀影片:畫幅由輸入圖片決定,建議省略或傳入 adaptive。
  • 多模態參考生成影片:可省略,預設為 adaptive;也可以明確指定一個固定比例。
介面不接受舊版或相容欄位,例如 prompt、image_urls、audio_urls、messages 和 first_frame_image。收到這類參數錯誤時,請刪除舊欄位並遷移至 content;例如把 "prompt": "一隻貓揮手" 改為 "content": [{"type": "text", "text": "一隻貓揮手"}]。不要同時傳送新舊兩種格式。

content 內容項目參數

每個內容項目都必須有 type,其餘欄位由類型決定: 媒體位址支援三種形式:
  • 可公開存取的 HTTPS URL,建議用於大型檔案。
  • mm_file://{file_id},引用已上傳或已有結果的檔案。
  • 對應媒體類型的 Base64 data URI。Base64 會使體積增加約三分之一,請確保整個請求本體不超過 64 MB。

素材規格與數量限制

多模態參考場景中的圖片、影片和音訊合計最多 12 個檔案。首尾幀場景和參考素材場景互斥:一旦使用 reference_image、reference_video 或 reference_audio,就不能再使用 first_frame 或 last_frame,反之亦然。

生產級能力展示

下面不是概念圖或佔位素材,而是 MiniMax H3 官方生產級能力樣片的真實參考輸入與實際影片輸出。三組案例分別涵蓋品牌短片、真人敘事和時尚電商,適合評估模型在商業製作中最關鍵的能力。 這裡的「人臉能力」指影片生成中的人物外觀一致性、臉部細節和表演控制,不是身分識別、人臉比對或換臉介面。

高端品牌短片:人物、產品與品牌資產統一

製作目標: 16:9 高級時裝品牌片。以荒漠公路和復古汽車建立冷峻氛圍,保持女主角外觀與黑色手袋結構,並將品牌 Logo 自然納入結尾。這個案例重點檢驗跨鏡頭人物一致性、商品保持、電影質感和品牌收束能力。 直接開啟或下載品牌短片 對應的 content 組織方式:

真人直式短劇:人臉一致性與情緒表演

製作目標: 15 秒、9:16 暗黑浪漫短劇預告。透過男女主角參考圖鎖定人物外觀,以古堡參考圖約束空間;使用中近景與面部特寫表現眼神對峙、恐懼、克制和危險感。這個案例適合觀察真人五官穩定性、微表情、視線關係和連續表演。 直接開啟或下載真人短劇 提示詞應明確人物關係、情緒和景別,而不只是描述「男女對話」:

時尚眼鏡廣告:人臉細節與商品結構保持

製作目標: 9:16 高級時尚眼鏡廣告。人物全身圖負責身形與台步,人臉參考圖負責五官和妝容,產品圖負責環繞曲線、鏡片反射、鏡腳和貓眼輪廓。這個案例同時考驗臉部近景、多人一致性、佩戴關係和商品幾何結構。 直接開啟或下載時尚眼鏡廣告 在商品廣告中,提示詞應把人物參考和產品參考的職責分開寫清楚:人物素材約束臉、妝容、身形和氣質;產品素材約束輪廓、材質、反射和佩戴位置。這樣比籠統地寫「生成一支眼鏡廣告」更穩定。

文生影片

只有一個文字項時即為文生影片。適合從創意、腳本或鏡頭描述直接生成畫面。提示詞可以按「主體 + 動作 + 場景 + 鏡頭 + 光線 + 聲音」的順序組織。
預設同步模式會在生成完成後傳回完整任務:
若請求中加入 "async": true,介面立即傳回:

首幀圖生影片

將圖片標記為 first_frame,模型會從該畫面開始生成。適合讓海報、商品圖、角色設定圖和攝影作品自然動起來。

尾幀和首尾幀影片

僅提供 last_frame 可以讓模型自然生成至指定畫面;同時提供 first_frame 與 last_frame,可以明確控制起點和終點。適合轉場、形態變化、成長過程或產品前後對比。
首幀與尾幀的尺寸和寬高比應盡量一致,主體位置、構圖和光線差異不要過大,這樣更容易得到自然過渡。

多模態參考生影片

參考素材可以組合使用:參考圖片控制角色或產品外觀,參考影片控制動作和運鏡,參考音訊控制對白音色、音樂或剪輯節奏。提示詞中應明確說明每類素材要控制什麼,避免只上傳素材卻不給出關聯關係。

回呼通知

傳入 callback_url 會自動啟用非同步模式:建立介面立即返回 task_id 和 trace_id,並在任務完成後向該地址 POST 最終結果,結構與任務查詢回應一致。 回呼中的最終狀態為 succeeded、failed 或 cancelled。即使使用回呼,也建議儲存 task_id,以便主動查詢或補償遺漏的通知。

常見錯誤

同步回應中的 task.status: succeeded 表示影片已生成;非同步確認只代表任務已進入佇列。只有任務最終成功時才會計費,查詢任務本身免費,不會重複扣費。

H3 Max

MiniMax-H3-Max 支援 480P 或 768P、5–15 秒整數時長。音訊輸入不額外計費,前 2 張圖片免費,超出部分逐張計費;參考影片按實際輸入時長計費。該模型不支援 2K。