MiniMax H3 API

ReachAPI 透過公開模型 ID minimax-h3 提供 MiniMax Hailuo-03，並使用統一的非同步影片任務介面。

提交任務：POST /v1/vids/create
查詢任務：GET /v1/tasks/{task_id}
執行方式：非同步任務；輪詢任務介面或提供 callback_url
模型 ID：minimax-h3

驗證

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: application/json

能力與價格

時長	解析度	比例	輸入模式
`4` 到 `15` 秒整數	`2K`、`768P`	`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive`	文字、首幀、首尾幀、多模態參考

必須明確傳入 input.content，且至少包含一個非空文字項目。閘道不會將舊欄位 prompt、image_url 或 image_urls 自動轉換為 content。

計費項目	2K	768P
輸出影片	$0.13 / 秒	$0.08 / 秒
參考影片輸入	$0.13 / 秒	$0.08 / 秒
輸入圖片	前 5 張免費，第 6 張起 $0.04 / 張	前 5 張免費，第 6 張起 $0.04 / 張
輸入音訊	免費	免費

任務成功後依實際用量結算；參考影片輸入使用請求輸出解析度對應的秒價。

提交任務

{
  "model": "minimax-h3",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "content": [
      {
        "type": "text",
        "text": "A paper boat drifts through a rainy street at night"
      }
    ],
    "duration_seconds": 6,
    "resolution": "2K",
    "aspect_ratio": "16:9"
  }
}

頂層參數

欄位	類型	必填	說明
`model`	string	是	固定為 `minimax-h3`
`callback_url`	string	否	任務終態 HTTPS 回呼位址，最長 2048 字元，禁止本機或內網目標
`input`	object	是	影片生成參數

`input` 參數

欄位	類型	必填	說明
`content`	object array	是	非空明確輸入，至少含一個非空文字項目
`resolution`	string	是	`2K` 或 `768P`
`duration_seconds`	integer	是	`4` 到 `15` 之間的整數
`aspect_ratio`	string	條件必填	純文字請求必填，規則見下文

位元率、幀率以及影音編碼由平台決定，無法設定。完整請求本文不得超過 64 MB。

比例規則

輸入模式	規則
純文字	必填且不能是 `adaptive`，只能使用六種固定比例
首幀或首尾幀	輸出始終跟隨輸入圖片比例；即使傳入 `aspect_ratio`，該值也會被忽略
多模態參考模式	可選；指定固定比例時會生效，省略或傳入 `adaptive` 時跟隨參考素材比例

`input.content`

類型	`role`	上限	說明
`text`	無	—	至少一個非空文字項目；每個文字項目最多 7000 個字元
`image_url`	`first_frame`	1	起始畫面；僅一張圖片且省略 role 時視為首幀
`image_url`	`last_frame`	1	結束畫面
`image_url`	`reference_image`	9	主體或風格參考
`video_url`	`reference_video`	3	動作或鏡頭參考
`audio_url`	`reference_audio`	3	音訊參考

URL 分別放在 image_url.url、video_url.url 或 audio_url.url。影片必須使用 reference_video，音訊必須使用 reference_audio。

同一請求不能混用首尾幀輸入與 reference_image、reference_video、reference_audio。

支援四種模式：

文生影片：text
首幀圖生影片：text + first_frame
首尾幀：text + first_frame + last_frame
多模態參考：text + 一個或多個 reference_*

多個素材依陣列順序在提示詞中引用為 Image 1、Image 2、Video 1、Audio 1，不要使用 Seedance 風格的 @ 引用。

輸入素材要求

輸入	格式	大小	其他限制
圖片	JPG、JPEG、PNG、WEBP、HEIC、HEIF	每張 ≤30 MB	每邊 256–5760 px，寬高比 0.4–2.5
參考影片	MP4、MOV	每個 ≤50 MB	寬和高均為 256–5760 px；寬高比 0.4–2.5；H.264/H.265；AAC/MP3；單個 2–15 秒；總計 ≤15 秒；23.976–60 fps
參考音訊	WAV、MP3	每個 ≤15 MB	單個 2–15 秒，總計 ≤15 秒

素材 URL 必須可由上游伺服器擷取。不支援 Base64、data: URI 或 mm_file:// 控制代碼。

請求範例

首幀圖生影片

{
  "model": "minimax-h3",
  "input": {
    "content": [
      { "type": "text", "text": "The camera slowly pulls back" },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": { "url": "https://cdn.example.com/start.jpg" }
      }
    ],
    "duration_seconds": 5,
    "resolution": "2K"
  }
}

首尾幀

{
  "model": "minimax-h3",
  "input": {
    "content": [
      {
        "type": "text",
        "text": "A smooth transition from close-up to wide shot"
      },
      {
        "type": "image_url",
        "role": "first_frame",
        "image_url": { "url": "https://cdn.example.com/start.jpg" }
      },
      {
        "type": "image_url",
        "role": "last_frame",
        "image_url": { "url": "https://cdn.example.com/end.jpg" }
      }
    ],
    "duration_seconds": 5,
    "resolution": "768P",
    "aspect_ratio": "adaptive"
  }
}

多模態參考

{
  "model": "minimax-h3",
  "input": {
    "content": [
      {
        "type": "text",
        "text": "Replace the person in Video 1 with Image 1 and synchronize the action to Audio 1"
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "https://cdn.example.com/person.png" }
      },
      {
        "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/beat.mp3" }
      }
    ],
    "duration_seconds": 5,
    "resolution": "2K"
  }
}

回應與輪詢

提交回應：

{
  "code": 200,
  "msg": "",
  "status": "queued",
  "task_id": "task_xxx",
  "data": []
}

輪詢 GET /v1/tasks/task_xxx，直到 status 為 success 或 failed。

{
  "code": 200,
  "status": "success",
  "task_id": "task_xxx",
  "data": [{ "url": "https://cdn.example.com/generated/video-1.mp4" }],
  "cost": { "spend": 0.52 },
  "billing": [
    {
      "metric": "VIDEO_SECONDS",
      "quantity": 4,
      "unit": 1,
      "price": 130000,
      "amount": 520000,
      "conditions": { "resolution": "2K" }
    }
  ]
}

cost.spend 以美元顯示，billing 是 credits 計費明細。結果 URL 可能過期，請儘快轉存。5 秒 / 2K 文生影片通常約需 3 分鐘，請據此設定輪詢。

錯誤

狀態碼	說明
400	欄位缺失或非法、模式衝突、素材超限
401	API Key 無效
402	餘額不足
422	內容安全攔截
429	限流，請退避重試
500 / 502	模型或上游服務暫時無法使用

失敗任務會回傳 status: "failed" 和 error_code；未產生費用時 cost.spend 為 0。

MiniMax H3 API

On this page