MiniMax Hailuo

Hailuo 是 MiniMax 的影片生成系列。同一個渠道提供兩代介面：MiniMax-H3 與 MiniMax-H3-Max 使用 MiniMax 的 /v2 介面，請求主體是 content 陣列，按秒結算；MiniMax-Hailuo-2.3 系列使用較舊的 /v1 介面，依任務固定價計費（見本頁最後一部分）。

任務透過通用影片端點提交、輪詢與下載，見建立任務與查詢任務。本頁說明這個廠商的適配器讀取哪些欄位、請求如何組裝，以及如何計費。

模型

模型 ID	解析度	時長（整數秒）	預設值	提示詞擴寫
`MiniMax-H3`	`768P`、`2K`	4–15	`768P`、5 秒	不支援
`MiniMax-H3-Max`	`480P`、`768P`	5–15	`768P`、5 秒	支援

模型 ID 區分大小寫，請按上表原樣填寫。帳戶只能用被路由到它的模型，單價也依帳戶而異；GET /v1/models 是目前金鑰的權威清單。
只有 MiniMax-H3-Max 接受 extra。對 MiniMax-H3 傳 extra 會回傳 400。
兩個模型都支援文生影片、首幀、首尾幀，以及參考圖／參考影片／參考音訊。

請求參數

欄位	型別	必填	預設值	說明
`model`	string	是	—	模型 ID，取自 `GET /v1/models`
`prompt`	string	是	—	提示詞，去除空白後為空會被拒絕，最長 7000 個字元
`resolution`	string	否	`768P`	不區分大小寫，必須是該模型支援的檔位
`duration`	integer	否	`5`	整數秒，必須在模型範圍內
`seconds`	string	否	—	時長的字串寫法，只在沒有 `duration`（或為 `0`）時生效
`ratio`	string	否	見下文	畫面比例
`images`	string[]	否	—	1 張作為首幀，2 張依序作為首幀與尾幀，最多 2 張
`image`	string	否	—	單張圖片，僅在 `images` 為空時使用
`metadata`	object	否	—	MiniMax 參數，見下一節

優先順序規則：

metadata.resolution、metadata.duration、metadata.ratio 會覆蓋同名的頂層欄位。
seconds 只在頂層 duration 缺失或為 0 時讀取，而 metadata.duration 的優先順序高於兩者。
metadata.duration 以數字解析，所以 5.5 會回報 invalid duration。與頂層 duration 不同，這裡寫 0 不算「未設定」，而是超出範圍。想保留預設值就不要寫這個鍵。
不支援 size。頂層 size 或 metadata.size 會回傳 MiniMax-H3 请使用 resolution(480P/768P/2K),不支持 size，請改用 resolution。
除 size 外，本廠商不讀取的頂層欄位（例如 generate_audio、input_reference）會被忽略，不會報錯。

metadata 參數

欄位	型別	說明
`content`	array	輸入素材，見 content 素材與限制。不能與頂層 `images` / `image` 同時傳送
`resolution`	string	覆蓋頂層 `resolution`
`duration`	number	覆蓋頂層 `duration` 與 `seconds`，必須是範圍內的整數
`ratio`	string	覆蓋頂層 `ratio`
`aigc_watermark`	boolean 或 string	`true` / `false`。也接受字串 `"true"` / `"false"`，multipart 表單送出的就是字串。不傳時由上游決定
`extra.prompt_expansion_mode`	string	`disabled`、`balanced`、`quality`，僅 `MiniMax-H3-Max` 支援
`size`	—	回傳 `400`

metadata 會解碼進強型別結構：上表欄位的 JSON 型別寫錯（例如 "duration": "abc"，或把 content 寫成物件）會回傳 400，錯誤訊息以 invalid metadata: 開頭，不扣費。不在表內的鍵（seed、callback_url 等）會被忽略，不會送到 MiniMax；RouteAPI 不送出回呼，請輪詢結果。

畫面比例 ratio

可選值：adaptive、21:9、16:9、4:3、1:1、3:4、9:16，不區分大小寫。

請求型態	不傳 `ratio` 時	規則
純文生影片（無首尾幀、無參考素材）	`16:9`	傳 `adaptive` 會回報 `text-to-video does not support ratio adaptive`
首幀，或首尾幀	`adaptive`	強制為 `adaptive`，你傳的值會被忽略，也不會被驗證
參考素材（參考圖／影片／音訊）	`adaptive`	七個值都可以用

content 素材與限制

metadata.content 是有序陣列。每個項目有一個 type、一個與之對應的酬載欄位，以及可選的 role：

`type`	酬載	可用 `role`	數量上限
`text`	`text`	無	1 筆，且必須與 `prompt` 一致
`image_url`	`image_url.url`	`first_frame`	1
`image_url`	`image_url.url`	`last_frame`	1，且必須同時有 `first_frame`
`image_url`	`image_url.url`	`reference_image`	9
`image_url`	`image_url.url`	無	僅當它是唯一素材時可用
`video_url`	`video_url.url`	`reference_video`（必填）	3
`audio_url`	`audio_url.url`	`reference_audio`（必填）	3

{ "type": "image_url", "role": "reference_image", "image_url": { "url": "https://..." } }
{ "type": "video_url", "role": "reference_video", "video_url": { "url": "https://..." } }
{ "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://..." } }

請求送出前會驗證以下規則：

一次請求的素材總數不超過 12 個，其中參考圖最多 9 張、參考影片最多 3 段、參考音訊最多 3 段。
首幀／尾幀與參考素材不能混用。reference_image、reference_video、reference_audio 之間可以自由組合。
不帶 role 的 image_url 只允許作為唯一的素材出現，此時視為首幀。
content 內沒有 text 項目時，RouteAPI 會用頂層 prompt 自動補一筆；若有，最多一筆，且內容必須等於去除前後空白後的 prompt，否則回傳 prompt 与 metadata.content 中的 text 冲突。
content 與頂層 images / image 互斥。
每個項目只轉送與其 type 對應的欄位，多餘的鍵會被丟棄。
素材 URL（包括頂層 images / image）只接受 http://、https:// 或 data: URI（如 data:image/png;base64,...），必須無需登入即可下載。不支援 MiniMax 的 mm_file:// 檔案 ID。MiniMax 在拒絕訊息中回顯的 URL 會被替換為 [url omitted]，帶簽章的素材位址不會出現在錯誤訊息中。
單一素材的格式、尺寸、時長與檔案大小限制以 MiniMax 為準，RouteAPI 不做驗證。不符合要求的素材可能在提交時被拒絕（400，不扣費），也可能在生成過程中被拒絕（任務判為 FAILURE，預扣額度退回）。

範例

文生影片

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "A paper boat drifting down a rain-soaked street, cinematic lighting",
    "resolution": "768P",
    "ratio": "16:9",
    "duration": 5
  }'

首幀

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "The camera slowly pushes in as the subject looks up and smiles",
    "images": ["https://cdn.example.com/first.jpg"],
    "resolution": "768P",
    "duration": 5
  }'

首尾幀

images 內的兩筆依序作為 first_frame 與 last_frame。ratio 會被強制為 adaptive。

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "The scene transitions from morning to sunset while the camera pans smoothly",
    "images": [
      "https://cdn.example.com/first.jpg",
      "https://cdn.example.com/last.jpg"
    ],
    "resolution": "768P",
    "duration": 5
  }'

參考圖 + 參考影片 + 參考音訊

需要超過 2 張圖片，或需要參考影片／參考音訊時，使用 metadata.content。參考影片會計費，請把時長控制在 2–15 秒之間——見計費。

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "The character in the image dances to the rhythm of the reference audio, copying the motion of the reference video",
    "resolution": "768P",
    "ratio": "9:16",
    "duration": 8,
    "metadata": {
      "content": [
        { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://cdn.example.com/character.jpg" } },
        { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://cdn.example.com/motion.mp4" } },
        { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://cdn.example.com/music.mp3" } }
      ]
    }
  }'

H3-Max 提示詞擴寫與水印

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3-Max",
    "prompt": "A rainy city street at night, neon signs reflected in puddles",
    "resolution": "480P",
    "duration": 6,
    "metadata": {
      "aigc_watermark": false,
      "extra": { "prompt_expansion_mode": "quality" }
    }
  }'

任務狀態與結果

狀態對應

MiniMax `task.status`	`data.status`	`data.progress`
`queued`	`QUEUED`	`20%`
`running`	`IN_PROGRESS`	`50%`
`succeeded` 且帶 `content.url`	`SUCCESS`	`100%`
`succeeded` 但沒有 `content.url`	`FAILURE`	`100%`
`failed`、`cancelled`	`FAILURE`	`100%`
其它值	`IN_PROGRESS`	`30%`

succeeded 但沒有影片位址時，任務判為失敗，fail_reason 為 upstream succeeded without video url，預扣額度退回。failed 或 cancelled 時，fail_reason 取自 MiniMax 的 task.error.message（其中的 URL 會被替換為 [url omitted]）；MiniMax 沒有提供原因時分別是 task failed 與 task cancelled。

查詢回傳錯誤信封（{"type":"error","error":{...}}）時，這一輪輪詢記為失敗，下一輪繼續查詢。回應主體完全沒有任務物件時，會退回舊的 /v1 結構解析，結果為空，任務只是保持 IN_PROGRESS。一直無法進入終態的任務會由平台逾時判失敗——預設 24 小時——fail_reason 為 任务超时（1440分钟），預扣額度退回。

任務紀錄

GET /v1/video/generations/{task_id} 回傳 RouteAPI 的任務列，所有欄位見查詢任務。本廠商常用的欄位：

欄位	說明
`data.status` / `data.progress`	任務狀態與進度，取自上表
`data.result_url`	任務成功後的影片位址
`data.fail_reason`	失敗原因，成功時為空
`data.quota`	該任務扣除的額度
`data.properties.input`	RouteAPI 送到上游的請求快照，素材 URL 被替換為 `[omitted, N bytes]`，對帳時有用
`data.data`	MiniMax 最新的任務回應

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_FQvcRkHE9wjSWwyISDcrWCKoqCPNdkCx",
    "platform": "35",
    "group": "default",
    "action": "generate",
    "status": "SUCCESS",
    "progress": "100%",
    "fail_reason": "",
    "result_url": "https://cdn.minimax.example/video/424010985738629.mp4?Expires=...",
    "submit_time": 1792412645,
    "start_time": 1792412650,
    "finish_time": 1792412780,
    "data": {
      "task": {
        "id": "424010985738629",
        "status": "succeeded",
        "content": { "url": "https://cdn.minimax.example/video/424010985738629.mp4?Expires=..." },
        "resolution": "768P",
        "usage": {
          "output_seconds": 5,
          "input_seconds": 0,
          "input_image_count": 1
        }
      }
    }
  }
}

值得讀取的內層欄位：

欄位	說明
`data.data.task.id`	MiniMax 的任務 ID，與 RouteAPI 的 `task_id` 不同
`data.data.task.status`	`queued`、`running`、`succeeded`、`failed` 或 `cancelled`
`data.data.task.content.url`	成功時的影片位址，`result_url` 儲存的就是它
`data.data.task.resolution`	MiniMax 回報的解析度。計費依請求的解析度，不依這個
`data.data.task.usage.output_seconds`	實際輸出影片的秒數，用於結算
`data.data.task.usage.input_seconds`	輸入參考影片的秒數，用於結算
`data.data.task.usage.input_image_count`	MiniMax 回報的圖片張數；結算依提交時的張數
`data.data.task.error.code` / `.message`	MiniMax 提供失敗原因時的錯誤碼與訊息

第一次成功輪詢之前，data.data 是提交時的原始回應（{"task_id": "..."}），沒有 task 欄位。task.usage 只在 MiniMax 回傳時出現，通常是在任務成功時。判斷任務是否結束請一律看外層 data.status。

下載影片

data.result_url 直接指向 MiniMax 的 CDN。該位址會依 MiniMax 的策略過期，任務變成 SUCCESS 後請盡快下載。

CDN 直連：不要帶 Authorization 請求標頭，部分儲存服務會拒絕多餘的驗證標頭。
https://api.routeapi.ai/v1/videos/{task_id}/content：把同一個已儲存的位址經 RouteAPI 轉送，必須帶 Authorization: Bearer $ROUTEAPI_KEY。它每次重新抓取已儲存的位址，所以不會延長有效期。適合不想讓用戶端看到上游網域、或 CDN 拒絕直接存取的情境。任務不存在時回傳 404 Task not found，任務成功前回傳 400 Task is not completed yet, current status: ...。

# direct CDN link
curl -L -o out.mp4 "$RESULT_URL"
# RouteAPI proxy
curl -L -o out.mp4 -H "Authorization: Bearer $ROUTEAPI_KEY" \
  "https://api.routeapi.ai/v1/videos/$TASK_ID/content"

計費

帳戶為該模型設定了固定價（控制台模型詳情頁會顯示）時，H3 按秒計費。若模型只設定了模型倍率，則依常規的按任務預扣，完成後不做差額結算。按秒計費時，一個任務的費用由三項相加：

計費項	單價	提交時預扣	結算時
輸出影片	依請求解析度，每秒單價	請求的 `duration`	`min(usage.output_seconds, duration)`
參考影片輸入	依請求解析度，每秒單價	`content` 內有 `reference_video` 時按 15 秒	`usage.input_seconds`，僅在 2–15 秒內有效
圖片	超出免費張數後按張計價	組裝後 `content` 中的全部圖片，含首尾幀	依提交快照的同一張數

價格與免費圖片張數依帳戶設定；內建預設值是 MiniMax-H3 免費 5 張、MiniMax-H3-Max 免費 2 張，但以控制台為準。本頁不列出任何價格。

時機	輸出秒數	參考影片秒數
提交時預扣	請求的 `duration`	有參考影片時按 15 秒
成功後結算	`usage.output_seconds`，不超過請求的 `duration`	`usage.input_seconds`，須在 2–15 秒之間

規則：

結算只退不補：最終扣費取重算金額與預扣額度中的較小值。
結算使用提交時凍結的單價，任務進行中調整價格不影響已提交的任務。
沒有參考影片時完全沒有輸入秒數這一項，usage.input_seconds 會被忽略。
參考音訊不另外收費，圖片這一項在結算時不變。
因為有參考影片時會預扣 15 秒輸入，帳戶餘額必須能覆蓋這個最壞情況，即使影片本身更短。
上游沒有回傳 usage、output_seconds 為 0 或超過 15 秒，或有參考影片時 input_seconds 缺失／不在 2–15 秒之間，RouteAPI 會保留全部預扣額度，不退款。把參考影片控制在 2–15 秒可以避免這種情況。
失敗或逾時的任務退回全部預扣額度；參數驗證失敗（400）不扣費。
按秒計費時，提交回應的 X-New-Api-Other-Ratios 標頭會帶上作用於模型單價的倍率，鍵為 h3_units（5 秒 768P 任務為 {"h3_units": 5}）。2.3 系列、以及未設固定價的 H3 模型該標頭為 {}。

計算範例

以下價格僅用於示範算術：假設 MiniMax-H3 768P 輸出每秒 $0.10、參考影片每秒 $0.10、超出免費 5 張後每張 $0.04。請求 10 秒，帶 2 張參考圖與 1 段參考影片：

預扣：10 × 0.10（輸出）+ 15 × 0.10（參考影片依上限預扣）+ max(0, 2 − 5) × 0.04（圖片）= $2.50。
MiniMax 回傳 output_seconds: 8、input_seconds: 6：8 × 0.10 + 6 × 0.10 + 0 = $1.40。
差額 $1.10 退回餘額。

錯誤

提交前會先做完整驗證，所以 400 不扣費。MiniMax 的業務拒絕會包在 HTTP 200 回應內回傳，對應如下：

MiniMax `base_resp.status_code`	含義	回傳給你的狀態碼	`code`
`1026`	內容／安全審核拒絕	`400`	`1026`
`2013`	參數錯誤	`400`	`2013`
`1002`	觸發限流	`429`	`1002`
`1004`、`2049`	上游金鑰／驗證失敗	`401`，通常回傳 `503`	`1004` / `2049`，或 `get_channel_failed`
`1008`	上游帳戶餘額不足	`503`	`get_channel_failed`
其它業務碼	未知業務錯誤	`502`	數字錯誤碼
—（回應主體無法解析，或 `type: "error"` 信封）	提交回應格式異常	`502`	`invalid_response`
—（`task_id` 為空）	上游沒有回傳任務 ID	`502`	`upstream_task_id_missing`

上游帳戶類失敗不會原樣透出：適配器把 1008 映射為 402、把 1004 / 2049 映射為 401，接著 RouteAPI 會將其判定為渠道故障，回傳 503 get_channel_failed 與通用的「上游服務暫時無法使用」文案，有其他渠道時先切換渠道重試。1008 的 402 同樣按此處理成 503。這些情況下 MiniMax 的 status_msg 不會傳給你。429 保留狀態碼，但文案會替換成通用的稍後重試提示。400 會帶上 MiniMax 的原始文案，前綴為 hailuo api error: 。

MiniMax 回傳非 200 的 HTTP 狀態碼時，回應主體不會被解析：你會拿到該狀態碼與錯誤碼 fail_to_fetch_task。查詢不存在或屬於其他帳戶的 task_id 回傳 400，錯誤碼 task_not_exist。

在請求到達 MiniMax 之前產生的錯誤遵循常見錯誤內的通用規則：缺少或無效的 API Key 回傳 401；餘額不足以覆蓋預扣（包括參考影片 15 秒的最壞情況）回傳 403 insufficient_user_quota；金鑰無權使用該模型回傳 403 與 This token has no access to model ...。

常見 400 提示（除特別註明外錯誤碼為 invalid_request）：

`message`	原因
`prompt is required`	`prompt` 缺失或為空
`seconds must be between 1 and 3600`（錯誤碼 `invalid_seconds`）	頂層 `duration` 為負或大於 3600
`invalid seconds: abc`	`seconds` 不是整數字串
`<model> 请使用 resolution(480P/768P/2K),不支持 size`	頂層或 `metadata` 內傳了 `size`；文案中的模型名是你請求的模型，括號內的檔位固定列出 480P/768P/2K
`invalid resolution: 1080P, MiniMax-H3 supports 768P, 2K`	解析度不在該模型支援範圍內
`invalid duration: 3, MiniMax-H3 supports integer 4-15`	時長低於模型下限、超過 15 秒，或不是整數
`invalid ratio: 2:1, supports adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16`	比例不在支援清單內
`text-to-video does not support ratio adaptive`	無首尾幀、無參考素材時傳了 `adaptive`
`at most 2 top-level images (first_frame, last_frame), got 3; use metadata.content for reference media`	`images` 超過 2 張
`images must not contain empty values`	`images` 內有空字串
`metadata.content cannot be combined with top-level images`	兩者同時傳送
`metadata.content must be a non-empty array`	`content` 是 `[]`
`prompt 与 metadata.content 中的 text 冲突`	`text` 項目與 `prompt` 不一致
`metadata.content accepts at most one text item`	`text` 項目多於一筆
`text exceeds 7000 characters`	提示詞超過 7000 個字元
`invalid content type "foo"`	`type` 不在支援清單內
`invalid role "foo" for image_url`	圖片的 `role` 不在支援清單內
`image_url without role is only allowed as the single input image`	不帶 `role` 的圖片與其它素材同時傳送
`last_frame requires first_frame`	只傳了尾幀
`at most one first_frame and one last_frame`	首幀或尾幀重複
`first/last frame images cannot be combined with reference media`	首尾幀與參考素材混用
`at most 9 reference images` / `at most 3 reference videos` / `at most 3 reference audios` / `at most 12 media items`	某一類或總素材數超限
`video_url requires role reference_video` / `audio_url requires role reference_audio`	該型別項目的 `role` 寫錯或沒寫
`image_url.url must be an http(s) URL or data URI`（`video_url` / `audio_url` 同理）	素材 URL 協定不支援，包括 `mm_file://`
`MiniMax-H3 does not support extra`	對非 Max 模型傳了 `metadata.extra`
`invalid extra.prompt_expansion_mode: balance, supports disabled, balanced, quality`	擴寫模式不在支援清單內
`invalid metadata: ...`	`metadata` 欄位的 JSON 型別不對

提交成功之後發生的失敗——內容審核、素材無法下載、任務被取消或逾時——不會以 HTTP 錯誤回傳。它們會以 FAILURE 連同 fail_reason 出現在任務紀錄中，預扣額度退回。

與 MiniMax 官方介面的差異

路徑是 RouteAPI 的：POST /v1/video/generations 與 GET /v1/video/generations/{task_id}。不提供 MiniMax 的 /v2/video_generation 與 /v2/query/video_generation/{id}，所以官方 SDK 只改 Base URL 無法接入。
提示詞寫在頂層 prompt，MiniMax 的 content 陣列寫在 metadata.content。上游的 content（含 text 項目）由 RouteAPI 組裝；用頂層 images 傳首幀／首尾幀的寫法 MiniMax 沒有。
你拿到的 task_id 是 RouteAPI 的。MiniMax 自己的任務 ID 只出現在 data.data.task.id。
RouteAPI 會在轉送前驗證項目型別、role、數量與 URL 協定，比 MiniMax 更嚴格，後者大多留到生成階段再判斷。
只會轉送 model、content、resolution、duration、ratio、aigc_watermark 與 extra。其它 MiniMax 參數（包括 callback_url）一律丟棄。
素材必須是公網 http(s) 或 data: URL，不能使用 MiniMax 的 mm_file:// 檔案 ID。
省略 resolution 與 duration 時 RouteAPI 會補成 768P、5 秒，所以上游總是收到明確的值。
成功時 RouteAPI 直接把 MiniMax 的 content.url 存為 result_url，不需要再呼叫個別的檔案查詢介面。

完整輪詢腳本

需要 bash、curl 與 jq。腳本提交一個 5 秒的文生影片任務，每 15 秒查詢一次、最多 30 分鐘，然後下載結果（只有 RouteAPI 代理位址才帶 Authorization），並列印計費相關的 usage。

#!/usr/bin/env bash
set -euo pipefail

: "${ROUTEAPI_KEY:?export ROUTEAPI_KEY first}"
BASE="${ROUTEAPI_BASE:-https://api.routeapi.ai}"
AUTH="Authorization: Bearer $ROUTEAPI_KEY"

TASK_ID=$(curl -sS -X POST "$BASE/v1/video/generations" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "A paper boat drifting down a rain-soaked street, cinematic lighting",
    "resolution": "768P",
    "ratio": "16:9",
    "duration": 5
  }' | jq -er '.task_id')

echo "task: $TASK_ID"

for _ in $(seq 1 120); do
  RESP=$(curl -sS "$BASE/v1/video/generations/$TASK_ID" -H "$AUTH")
  STATUS=$(jq -r '.data.status // empty' <<<"$RESP")
  echo "status: ${STATUS:-unknown} $(jq -r '.data.progress // ""' <<<"$RESP")"

  case "$STATUS" in
    SUCCESS)
      URL=$(jq -r '.data.result_url' <<<"$RESP")
      OUT="$TASK_ID.mp4"
      if [[ "$URL" == *"/v1/videos/"*"/content" ]]; then
        curl -sSL -o "$OUT" -H "$AUTH" "$URL"
      else
        curl -sSL -o "$OUT" "$URL"
      fi
      echo "saved: $OUT"
      jq -r '.data.data.task.usage // {}' <<<"$RESP"
      exit 0
      ;;
    FAILURE)
      echo "failed: $(jq -r '.data.fail_reason' <<<"$RESP")" >&2
      exit 1
      ;;
  esac

  sleep 15
done

echo "gave up after 30 minutes" >&2
exit 1

MiniMax-Hailuo-2.3

MiniMax-Hailuo-2.3 與 MiniMax-Hailuo-2.3-Fast 使用 MiniMax 的 /v1/video_generation 介面，按任務計價而不是按秒。RouteAPI 提交後輪詢 /v1/query/video_generation，再透過 MiniMax 的 /v1/files/retrieve 換取下載位址，存進 result_url。

模型 ID	說明
`MiniMax-Hailuo-2.3`	文生影片與圖生影片
`MiniMax-Hailuo-2.3-Fast`	2.3 的更快、更便宜的版本

兩者預設 768P 與 6 秒。除通用的 0–3600 秒驗證外，任務 API 不對這個系列做解析度或時長範圍驗證：值會原樣轉送，由 MiniMax 決定接受或拒絕。控制台操練場提供 768P / 1080P 與 6 或 10 秒，其中 1080P 僅限 6 秒。

請求如何對應（2.3）

信封欄位	適配器的處理
`prompt`	作為 `prompt` 送出；存在 `metadata.prompt` 時以它為準
`duration`	作為 `duration` 送出；缺失或為 `0` 時變為 `6`
`size`	依子字串轉換成 `resolution`：含 `1080` → `1080P`，`768` → `768P`，`720` → `720P`，`512` → `512P`；其它值退回模型預設
`images` / `image`	不讀取。圖片輸入必須透過 `metadata.first_frame_image` 傳入
`ratio`、`generate_audio`、`seconds`	不讀取。這個系列沒有畫面比例或配樂參數
`metadata`	依 MiniMax 的欄位名解碼成 MiniMax 的欄位

這個系列不讀取頂層的 resolution：請用 size 或 metadata.resolution。

廠商參數（2.3）

以下欄位都放在 metadata 下。JSON 型別錯誤（例如 "duration": "abc"）會讓轉換失敗並回傳 500 build_request_failed，而不是 400；未知鍵會被忽略。

欄位	型別	說明
`resolution`	string	`768P` 或 `1080P`；覆蓋由 `size` 換算出的值
`duration`	integer	6 或 10 秒；覆蓋頂層 `duration`
`first_frame_image`	string	首幀圖片（公網 URL 或 base64 的 `data:` URI），原樣轉送
`last_frame_image`	string	首尾幀生影片的尾幀圖片，原樣轉送
`subject_reference`	array	主體參考生影片的主體參考：`[{"type": "character", "image": ["<url>"]}]`
`prompt_optimizer`	boolean	是否讓 MiniMax 改寫 prompt；顯式 `false` 也會轉送
`fast_pretreatment`	boolean	MiniMax 快速前處理開關，依送出值轉送
`aigc_watermark`	boolean	是否加上供應商 AIGC 水印
`callback_url`	string	轉送給 MiniMax。RouteAPI 不註冊也不接收回呼，請輪詢結果
`prompt`	string	覆蓋頂層 `prompt`

metadata.model 會被覆蓋成渠道的上游模型名，因此無法透過 metadata 切換到其它（例如更貴的）模型。

圖生影片（2.3）

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "The camera slowly pushes in as the subject looks up and smiles",
    "duration": 6,
    "metadata": {
      "resolution": "1080P",
      "first_frame_image": "https://cdn.example.com/first.jpg"
    }
  }'

狀態對應（2.3）

MiniMax v1 回傳 Preparing、Queueing、Processing、Success 與 Fail。

上游狀態	任務紀錄狀態	進度
`Preparing`、`Queueing`	`IN_PROGRESS`	`30%`
`Processing`	`IN_PROGRESS`	`50%`
`Success`	`SUCCESS`	`100%`
`Fail`	`FAILURE`	`100%`

成功時適配器會用回傳的 file_id 呼叫 MiniMax 的檔案查詢介面，把取得的下載位址存進 result_url。該位址會依 MiniMax 的策略過期；GET /v1/videos/{task_id}/content 會把已儲存的位址經 RouteAPI 轉送，需要帶 Authorization。

計費（2.3）

2.3 系列依控制台設定的任務單價計費。你送出的解析度與時長不影響扣費，完成時也沒有差額結算；失敗的任務退回預扣額度。X-New-Api-Other-Ratios 為 {}。

錯誤（2.3）

狀態碼	`code`	含義
400	`invalid_request`	`prompt` 缺失或為空，或 JSON 格式錯誤
400	`invalid_seconds`	`duration` / `seconds` 為負或大於 3600
400	MiniMax 的數字業務碼	MiniMax 拒絕了任務，文案是其 `status_msg`
400	`task_not_exist`	`task_id` 未知或屬於其它帳戶
500	`build_request_failed`、`do_request_failed`	metadata 轉換失敗，或上游不可達
500	`unmarshal_response_body_failed`	MiniMax 回傳了適配器無法辨識的結構
502	`upstream_task_id_missing`	提交回應內沒有任務 ID
上游狀態碼	`fail_to_fetch_task`	MiniMax 回傳了非 200 的 HTTP 狀態碼

這個系列的所有 MiniMax 業務拒絕都回傳 400，包括限流；數字 code 與 status_msg 會原樣透出，所以請看數字錯誤碼而不是 HTTP 狀態碼。例外是上游餘額不足：當 MiniMax 的 status_msg 命中 RouteAPI 內建的計費關鍵詞（餘額不足等）時，回應會被清洗為 503 get_channel_failed 並給出通用文案，同時記為渠道故障（只有在開啟自動停用、且該渠道允許自動停用時才會自動停用該渠道）。

提交之後發生的失敗（審核不通過、供應商逾時）會以 FAILURE 連同 fail_reason 出現在任務紀錄中，預扣金額退回。