mmx-h3-video

使用 MMX 生成 MiniMax-H3 影片

本 Skill 僅用於 MiniMax-H3 影片生成。請勿處理純文字、圖片生成、語音、音樂、搜尋、舊版海螺（Hailuo）模型或無關的 MMX 指令。

發起付費請求前，請先閱讀 references/h3-video.md，瞭解提示詞構建、媒體限制、等待行為及錯誤處理。

必須遵循的規則

1. 使用按量計費 / 儲值型（Pay-as-you-go/Credit）API Key。H3 不支援 OAuth 或 Token 訂閱方案（Token Plan）的 Key。
2. 若已有儲存的 MMX API Key，請直接複用。切勿在指令紀錄中印出、重複或放置明文 API Key。
3. 務必傳入 --model MiniMax-H3；切勿依賴設定檔中的預設模型。
4. 若要獲取完整影片，請直接執行單一阻塞式（blocking）mmx video generate 指令。請勿使用 Bash 包裝腳本或手寫輪詢迴圈（polling loop）。
5. 若終端機指令仍處於執行狀態，請持續等待該執行階段（session）。請勿執行 ps、擷取進程參數、反覆檢查輸出、強制結束進程或提交另一個任務。
6. 請將 Detecting region... cn 或 Detecting region... global 視為正常的 stderr 進度提示，而非任務提交失敗。
7. 切勿因終端機等待、狀態輪詢或下載中斷而重新提交替代的付費任務。
8. 僅在首次指令因區域檢測、端點（endpoint）或驗證路由問題導致在任務建立前顯著失敗時，才可重試切換備用區域（alternate region），且最多重試一次。
9. 僅在使用者明確要求只獲取 Task ID 而無需等待或下載時，才使用 --async。

定位與使用 CLI

在 minimax-cli 專案庫內部，建置變更並使用本地產物：

bun run build
node ./dist/mmx.mjs video generate --help

在專案庫外部，請使用已安裝的 mmx 可執行檔。除非使用者要求，否則請勿安裝或更新 MMX。

在以下指令中，測試本地專案庫建置時，請將 mmx 替換為 node ./dist/mmx.mjs。

解析與儲存 API Key

在發起首次付費 H3 請求前，請檢查當前憑證（切勿洩漏）：

mmx auth status --output json --quiet

• 若 method 為 api-key，請直接複用 MMX 設定。生成指令中請勿附加 --api-key。
• 若使用者已提供 Key 且執行階段已將其安全儲存為 MINIMAX_API_KEY，請寫入設定一次，隨後使用 MMX 設定：

mmx config set --key api_key --value "$MINIMAX_API_KEY" --quiet

• 儲存 api_key 會替換過期的 OAuth 憑證、清除快取的區域資訊，並將 Key 寫入 ~/.mmx/config.json（權限設為僅限所有者存取）。
• 切勿將先前提供的 Key 重組為可見的 shell 文字。若系統支援，請使用執行階段的機密/環境變數注入。
• 若既無儲存的 API Key 也無安全注入的變數，請請使用者執行 mmx auth login 並選擇 API Key。請勿要求使用者再次將 Key 貼到對話中。
• 儲存完成後，後續的 Agent 指令必須同時省略明文 Key 與 --api-key 參數。

預設影片生成與下載路徑

當使用者需要獲取最終影片檔案時，請使用此路徑：

mmx video generate \
  --model MiniMax-H3 \
  --prompt "<video prompt>" \
  --duration <4-15> \
  --download <output.mp4> \
  --poll-interval 10 \
  --timeout 1800 \
  --non-interactive

該 CLI 程序會提交正好一個任務，在內部進行狀態輪詢與等待，並下載完成的影片。當執行工具傳回正在執行的 session 或 cell ID 時，請持續在該 session 中等待直至其結束。

請勿在此指令中加入 --async。非同步模式（Async mode）會在下載處理完成前就直接傳回。

輸入模式

每次請求請僅使用一種模式。

文字生成影片（Text-to-Video）

mmx video generate \
  --model MiniMax-H3 \
  --prompt "A cinematic coastal sunset, slow dolly forward" \
  --duration 15 \
  --ratio 16:9 \
  --download ./result.mp4 \
  --poll-interval 10 \
  --timeout 1800 \
  --non-interactive

首尾幀影片（First/Last-Frame Video）

--image 代表首幀（第一幀）。可與一個 --last-frame（尾幀）搭配使用。

mmx video generate \
  --model MiniMax-H3 \
  --prompt "The subject walks naturally from the starting pose to the ending pose" \
  --image ./start.png \
  --last-frame ./end.png \
  --duration 15 \
  --download ./result.mp4 \
  --poll-interval 10 \
  --timeout 1800 \
  --non-interactive

新指令中請勿使用隱藏的相容性別名 --first-frame。

多模態參考影片（Multimodal Reference Video）

重複傳入各個參考標記（flag）以提供多個輸入。請勿使用逗號分隔路徑。

mmx video generate \
  --model MiniMax-H3 \
  --prompt "Preserve the referenced character, follow the motion and audio rhythm" \
  --reference-image ./character-1.png \
  --reference-image ./character-2.png \
  --reference-video ./motion.mp4 \
  --reference-audio ./rhythm.mp3 \
  --duration 15 \
  --download ./result.mp4 \
  --poll-interval 10 \
  --timeout 1800 \
  --non-interactive

幀模式（Frame mode）不可與參考模式（Reference mode）混用。使用參考音訊（Reference audio）時，至少需提供一張參考圖片或一段參考影片。

區域故障復原（Region Recovery）

首次請求時請省略 --region，讓 MMX 自動使用或檢測 Key 所屬的區域。若該指令失敗，僅在滿足以下所有條件時，才可將相同的請求切換至備用區域重試一次：

1. 未傳回任何 taskId。
2. 未印出 [Model: MiniMax-H3]，表示 CLI 未確認任務已建立。
3. 錯誤訊息明確與區域檢測、區域端點或提交前的 401/403 驗證路由不匹配有關。

若在 cn 嘗試失敗，請改用 --region global；若在 global 嘗試失敗，請改用 --region cn。保持所有生成參數不變。若備用區域成功，請持久化儲存設定且不洩漏憑證：

mmx config set --key region --value <global-or-cn> --quiet

切勿因參數驗證錯誤、錯誤碼 2013、計費問題、速率限制（rate limit）、敏感內容、一般服務錯誤或不明確的逾時而進行區域降級（fallback）。在任務建立後、輪詢期間或下載期間，絕不可進行區域重試。

核心限制

• 提示詞（Prompt）：最多 7000 個字元。
• 輸出時長：4 到 15 秒的整數。
• 解析度：2K。
• 參考圖片：最多 9 張。
• 參考影片：最多 3 段。
• 參考音訊：最多 3 段。
• 混合參考項目：總計最多 12 個。
• 本地圖片：單檔最多 30 MB。
• 本地影片：MP4 格式，單檔最多 50 MB。
• 本地音訊：MP3 或 WAV 格式，單檔最多 15 MB。
• 完整的本地 Base64 請求主體（request body）：最多 64 MB。

對於較大或數量較多的資產，請使用 URL 或 mm_file://<file-id>。有關 CLI 未完全驗證的官方時長、編碼器（codec）、影格率（frame-rate）、尺寸與長寬比限制，請參閱 references/h3-video.md。

非同步 Task-ID 路徑

僅在使用者希望立即提交並獲取 Task ID 時使用此路徑：

mmx video generate \
  --model MiniMax-H3 \
  --prompt "<video prompt>" \
  --duration <4-15> \
  --async \
  --output json \
  --non-interactive

傳回並保留 taskId 後即停止。請勿自動監控或下載。MMX 未提供任務列表指令，亦不會保留本地任務歷史紀錄。

提示詞處理

保留使用者的意圖。請使用使用者的語言撰寫提示詞。當提示詞過短時，請參考以下要素補充擴充一次：

1. 時長、長寬比與使用場景。
2. 主體與參考資產對應。
3. 按時間順序排列的動作。
4. 場景、光影、天氣與背景。
5. 景別、鏡頭角度、運鏡（camera motion）、焦點與分鏡剪輯。
6. 風格、色彩、氛圍與節奏。
7. 對白、環境音、音樂與音訊同步。
8. 需要保留的元素與需要避免的瑕疵（artifacts）。

當提供兩張或以上有順序的參考圖片時，請使用結構化的分鏡腳本（storyboard）提示詞，而非單段散文描述：

1. 輸出規格與有序參考圖片數量。
2. 全局視覺風格與連貫性規則。
3. 鎖定的角色身份、服裝、位置與道具。
4. 連續的主時間軸，分別對應至 reference image 1、reference image 2 等。
5. 每個鏡頭內部的微時間軸：建立場景（establish）、預備（prepare）、執行（execute）、定格/維持（settle/hold）及最終狀態鎖定（end-state lock）。
6. 用於交接或精確動作的明確動作與物件狀態轉變。
7. 聲音需求與最終的反向約束區塊（negative-constraint block）。

請使用雙層時間軸架構。主時間軸將整段影片劃分為多個鏡頭（shots）；每個鏡頭再將其時間區間細分為帶有時間標記的微拍子（micro-beats）。一個鏡頭可包含多個階段，但必須構成一個具因果關係的動作拍子。每個鏡頭都必須載明其確切時間範圍、時長、參考圖片、初始狀態、運鏡行為、微拍子及鎖定的最終狀態。下一個鏡頭的初始狀態必須等於前一個鏡頭鎖定的最終狀態。

主時間軸與微時間軸區間必須無縫覆蓋其母時長，不可有空隙或重疊，且參考圖片編號必須與重複的 --reference-image 標記順序一致。確保動作可在 4 到 15 秒內合理完成。切勿擅自加入品牌、名人、對白、文字覆蓋（text overlays）或不安全內容。請使用 references/h3-video.md 中詳細的中英文範本。

若使用者已提供完整的結構化分鏡腳本提示詞，請勿摘要、縮短、翻譯或進行風格化重寫。僅需檢查是否超出 7000 字元限制、時長覆蓋範圍、參考圖片數量/順序、媒體模式相容性及矛盾的約束條件；除非需要修正，否則請保留原始字句。

錯誤處理

• 錯誤的 Token Plan / OAuth 憑證或 H3 錯誤 2013：停止執行，並要求提供相容的按量計費（Pay-as-you-go）API Key。
• 提交前明確的區域路由失敗：使用備用 --region 重試一次不變的指令；任務建立後絕不重試。
• 身份驗證、餘額不足或敏感內容錯誤：停止執行並回報確切錯誤，切勿重試或暗中修改請求。
• 正在執行的終端機 session：持續在同一 session 中等待；未傳回最終檔案路徑並不代表失敗。
• 終端機任務狀態為 failed、cancelled 或 expired：回報狀態與任務錯誤；再次發起付費提交前需取得確認許可。
• 輪詢逾時：若有 Task ID 請予以回報；切勿提交重複的任務。
• 任務成功後下載失敗：僅重試下載該結果檔案；絕不重新生成影片。

進行故障復原前，請參閱 references/h3-video.md 中的完整錯誤對應表（failure matrix）。