MiniMax H3 API 指南：文生影片與參考素材串接

若用戶端把所有 MiniMax H3 型號都視為同一套規格，生成請求很容易失敗。模型 ID 會影響時長與解析度驗證；輸入模式則決定首尾影格、參考圖片、影片與音訊能否同時提交。

本文依據截至 2026 年 10 月 22 日 ToAPIs 前端中的請求契約整理，是串接指南，不是上游效能測試或目前帳戶報價。正式呼叫前，請先確認帳戶已開通對應型號。

快速開始

ToAPIs API 範例使用 POST /v1/videos/generations 提交影片生成任務。請求需要 Bearer API Key、已啟用的模型 ID、提示詞、時長與畫面比例：

curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
    "duration": 5,
    "ratio": "16:9"
  }'

生成採非同步任務。請讀取帳戶 API 回應中的任務識別碼，並使用帳戶文件指定的狀態介面查詢。除非文件明確說明，否則不要假設任務 ID 一定位於固定 JSON 路徑。

import os
import requests

BASE_URL = "https://api.toapis.com/v1"
headers = {"Authorization": f"Bearer {os.environ['TOAPIS_API_KEY']}"}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json={
        "model": "minimax-h3",
        "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
        "duration": 5,
        "ratio": "16:9",
    },
    timeout=30,
)
response.raise_for_status()
print("Submission response:", response.json())

範例先列印回應，不猜測任務 ID 或影片連結欄位。請依帳戶文件中的回應格式撰寫解析邏輯，避免介面外層結構變更時，把尚未完成的任務誤判為成功。

使用正確的模型 ID

前端將 minimax-h3 與 minimax-h3-global 識別為基礎型號，也識別包含 minimax-h3-max 的型號。例如 Turbo 型號 ID 是 minimax-h3-max-turbo。請使用模型目錄顯示的完整 ID，不要自行縮寫或猜測別名。

目前前端驗證的規格如下：

以上是前端驗證限制，不代表所有帳戶或上游路由都提供相同能力。目前用戶端只為精確 ID minimax-h3-max 增加 1080P，不要推斷 Turbo、-global 別名或所有 H3 型號都支援 1080P。

兩種素材模式擇一

H3 表單支援兩種互斥流程：

1. 首尾影格模式：最多提供一個 first_frame_image 和一個 last_frame_image。有影格素材時，用戶端會使用自適應畫面比例。
2. 參考素材模式：提交參考圖片、影片及／或音訊，不要同時提交首尾影格。此模式使用所選畫面比例。

首影格請求範例：

{
  "model": "minimax-h3",
  "prompt": "The subject turns toward the camera as the camera gently moves forward",
  "duration": 5,
  "ratio": "16:9",
  "first_frame_image": ["https://example.com/starting-frame.jpg"]
}

參考素材請求範例：

{
  "model": "minimax-h3",
  "prompt": "Use the supplied references to guide the scene and motion",
  "duration": 5,
  "ratio": "16:9",
  "media_mode": "reference",
  "reference_images": ["https://example.com/character-reference.jpg"],
  "reference_videos": ["https://example.com/motion-reference.mp4"]
}

上傳素材的實際值格式取決於閘道的素材上傳流程。這裡展示的是請求欄位，不代表每條路由都接受任意公開 URL。請使用上傳流程回傳的 URL 或素材 ID。

目前前端限制包括：最多 9 張參考圖、3 段參考影片和 3 段參考音訊；參考素材總數不得超過 12。每段參考影片需為 2–15 秒，影片總時長不得超過 15 秒。音訊參考必須同時包含至少一項視覺素材。Turbo 不接受參考素材。

提交前應先完成模式、數量與時長驗證。輸入模式混用、數量超限或缺少視覺參考時，前端會拒絕請求。

提示詞、畫面比例與選用參數

提示詞為必填，目前前端限制為 7,000 個 Unicode 字元。建議用一般文字描述主體、場景、動作與視覺目標。除非上游文件明確定義特殊語法，否則應將 [Pan Left] 等字串視為一般提示詞；前端契約無法證明它們是 H3 原生指令。

請求建構器會依型號路由處理 prompt_optimizer、watermark 和 seed 等選用項目。不要假設這些欄位在所有上游渠道都相同。切換型號時，也要清除舊型號留下且新型號不支援的欄位。

前端接受 adaptive、21:9、16:9、4:3、1:1、3:4 和 9:16。首尾影格輸入會強制使用 adaptive；文生影片選擇 adaptive 時會正規化為 16:9，參考素材模式則保留所選的支援比例。

解析度與畫面比例是不同參數：比例決定畫面形狀，解析度由型號路由決定。不同型號的選項大小寫也可能不同（例如 768p 和 768P），不要在全域邏輯中擅自統一大小寫。

輪詢、錯誤與重試

提交任務後，請保存任務識別碼，並查詢帳戶文件指定的狀態端點。輪詢應採用有上限的退避策略，設定總時限，並區分任務失敗與用戶端等待逾時。等待逾時不代表上游任務已失敗；重試可能計費的生成請求前，應先查詢原任務，以免重複生成。

用戶端至少應檢查 HTTP 狀態、依文件解析回應、在記錄的終態停止輪詢，並限制重試次數與總耗時。日誌可以保存請求或任務識別碼，但不要記錄 API Key 或私人素材 URL。

以上是通用診斷類別，不保證與 ToAPIs 每條路由的錯誤碼完全一致。

定價、隱私與上線檢查

價格、可用性、退款與 SLA 可能因型號、路由和帳戶而異。本文不引用每秒價格或可用性承諾。估算成本前，請查閱目前的模型目錄與帳戶報價。不要把規劃稿價格當成正式報價。

參考素材屬於使用者資料。上傳前請驗證檔案類型、大小與數量，只處理使用者有權使用的素材，並依產品資料保留規則管理圖片、影片和音訊。不要為了示範方便而將私人素材放到公開 URL，也不要把暫時素材連結寫入長期日誌。

上線前，至少為帳戶啟用的每個型號測試一個有效請求，並為小數時長、不支援的解析度、素材超量、模式混用和 Turbo 參考素材編寫負向測試。切換型號後，確認介面會清除不相容值。請使用本機測試資料或經核准的測試帳戶驗證回應欄位與任務狀態；本文未呼叫線上介面驗證服務行為。

相關入口

• 瀏覽影片模型
• 在 Playground 開啟 MiniMax H3
• 在 Playground 開啟 MiniMax H3 Max Turbo