Hailuo（MiniMax）系列

MiniMax 的海螺影片生成模型，共兩款，透過 OfoxAI 影片介面 POST /v1/videos 呼叫。任務以非同步方式執行：建立任務後取得任務 ID，再透過該 ID 查詢結果。

模型選擇

重點需要 2K 輸出時選用 Hailuo 3；需要 480p 時選用 Hailuo 3 Max。兩款皆不支援 720p 與 1080p。

模型	解析度（預設）	時長	畫面比例
Hailuo 3	`768p` `2k`（`768p`）	4–15 秒	`21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive`
Hailuo 3 Max	`480p` `768p`（`768p`）	5–15 秒	同上

兩款皆支援文生影片、圖生影片與影片參考，並可生成同步音軌（generate_audio 預設為 true）。adaptive 表示沿用輸入圖片的比例。

模型 ID（呼叫時原樣複製）

Hailuo 3minimax/hailuo-3768p、2K

Hailuo 3 Maxminimax/hailuo-3-max480p、768p，最短 5 秒

上表與 Models API 返回的 video_attributes 一致；模型能力如有調整，以介面返回為準。按秒計費，實際費用以任務結果中的 usage.video_cost 為準，價格請參閱模型頁。

呼叫範例

以下範例只展示建立任務的請求。建立後查詢狀態、下載結果的完整流程見 Video API · 快速開始。

文生影片

僅傳 prompt。

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/hailuo-3",
    "prompt": "寬銀幕鏡頭：沙漠公路上一輛復古汽車駛向落日",
    "duration": 6,
    "resolution": "768p",
    "aspect_ratio": "21:9"
  }'

圖生影片

frame_images 傳入 1 張 first_frame，影片以該圖片作為首幀。

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/hailuo-3",
    "prompt": "畫面中的人物轉身走向遠處",
    "duration": 5,
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/first.jpg" }, "frame_type": "first_frame" }
    ]
  }'

影片參考

input_references 傳入 1 段影片作為參考。以影片為輸入時，計費秒數可能包含輸入影片的時長。

Terminal


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/hailuo-3",
    "prompt": "保持鏡頭運動，將畫面改為水墨動畫風格",
    "duration": 5,
    "input_references": [
      { "type": "video_url", "video_url": { "url": "https://example.com/source.mp4" } }
    ]
  }'

frame_images 與 input_references 不可同時傳入，同時傳入返回 400 references_conflict。
不需要音軌時傳入 "generate_audio": false。
欄位結構的完整說明見建立影片任務。

解析度寫法

海螺的解析度級距與其他系列不同，為 768p 與 2k（小寫 k）。傳入其他系列常用的 720p、1080p 會返回 400。

常見錯誤

重點參數校驗錯誤在建立時即返回，不會建立任務，也不產生費用。錯誤訊息中會列出允許的取值。

HTTP · code	錯誤原文	原因	處理方法
400 `unsupported_parameter`	`resolution "1080p" not supported; allowed: [768p 2k]`	海螺不支援 1080p	Hailuo 3 請使用 `768p` 或 `2k`
400 `unsupported_parameter`	`duration 4 out of range [5, 15]`	Hailuo 3 Max 最短為 5 秒	改為 5 秒以上，或改用 Hailuo 3
400 `references_conflict`	`frame_images and input_references are mutually exclusive`	同時傳入了兩種素材欄位	兩者只能擇一
404 `model_not_found`	`model not found`	模型 ID 拼寫錯誤	從本頁複製模型 ID

完整錯誤碼見 Video API 錯誤碼。

官方文件

常見問題

海螺 Hailuo 3 支援 1080p 嗎？

不支援。Hailuo 3 的解析度是 768p 和 2k，Hailuo 3 Max 是 480p 和 768p。傳入 720p 或 1080p 會返回 400 resolution not supported。

Hailuo 3 Max 報錯 duration 4 out of range [5, 15]？

Hailuo 3 Max 單個任務最短 5 秒，最長 15 秒。需要 4 秒的影片請使用 Hailuo 3。

海螺影片支援 21:9 嗎？

支援。Hailuo 3 和 Hailuo 3 Max 都支援 21:9、16:9、4:3、1:1、3:4、9:16 和 adaptive。