MiniMax 海螺：影片生成 API

可用型號

請使用精確 ID MiniMax-H3 / MiniMax-H3-Max / MiniMax-H3-SelfHosted:沒有別名,未知模型名會被拒絕。H3-Max 為快速生成版,5 秒成片通常數秒即可生成。分檔價與完整規格見模型卡 MiniMax-H3、MiniMax-H3-Max。

MiniMax-H3-SelfHosted 是海螺 H3 的自部署版,效果對標 H3、價格更低。請求契約與 MiniMax-H3 相同,差異如下:解析度增加 480P、1080P、4K(完整列表見上表);參考影片與參考音訊必須是公網 http(s) 位址,不接受 data: 內嵌(圖片仍可內嵌);單條成片通常需要 3-6 分鐘。它由分組 MiniMax H3 自部署 提供,在控制台歸入「自部署」分類。規格與分檔價見模型卡 MiniMax-H3-SelfHosted。

MiniMax-H3 與 MiniMax-H3-Max 分屬兩個分組——MiniMax H3 官方直連與MiniMax H3 Max 官方直連;speech-2.8-hd / speech-2.8-turbo 屬於第三個分組 MiniMax 語音 官方直連,用法見語音合成 API。MiniMax-H3-SelfHosted 屬於分組 MiniMax H3 自部署;MiniMax-H3-Max 另可透過分組 MiniMax H3 Max 雲廠商 呼叫(同一官方模型,價格不同)。

密鑰只能調用它所含分組的模型；H3 與 H3-Max 都要用時，把兩個分組加進同一把密鑰即可。請在發起付費任務前用 GET /v1/models 確認密鑰能呼叫哪些模型。

請求參數

HopBase 按 MiniMax 官方 v2 介面接入海螺 H3。請求體鏡像 MiniMax 官方 POST /v2/video_generation,並做嚴格解碼:未知欄位與多餘 JSON 值會在請求送出前被拒絕。

頂層只接受下表欄位;其他欄位(包括 OpenAI 的 prompt / size / n / seconds / image)回傳 400。

首尾幀模式的 ratio 接受任意合法值,成片恆為 adaptive(跟隨圖片);需要特定比例請先裁剪幀圖。所有請求使用 Authorization: Bearer sk-your-key 與 Content-Type: application/json。

content 元素

數量、role 與組合在提交時校驗;檔案大小、尺寸、編碼與時長由 MiniMax 在執行時校驗。首尾幀與 reference_* 元素在同一請求內互斥,單一請求的媒體素材合計最多 12 個。

媒體 url 接受公網絕對 http(s) 位址或 data: URI(base64 內嵌)。mm_file:// 會被拒絕——該檔案歸屬你自己的 MiniMax 帳號,閘道無法代取。MiniMax-H3-SelfHosted 的 video_url 與 audio_url 必須是公網 http(s) 位址,data: 僅限圖片。

素材規格

輸出與請求體大小

• 輸出為 24 FPS,每條成片原生自帶雙聲道音訊。
• 對白與配音在模型內生成,TTS 涵蓋 11 種語言(中/英/日/韓/法/德/西等)。
• 2K 指 16:9~9:16 之間短邊 1440 像素;更寬比例保持約 370 萬總像素,如 21:9 → 2976×1248。
• 768P 同規則,短邊 768 / 約 100 萬像素。
• 整個 JSON 請求體上限 64 MiB,超出回傳 413。
• base64 會把資料放大約 4/3,改用 data: 內嵌也不會放寬數量與時長限制,大素材請用 URL。

回傳結果

MiniMax 任務的欄位在回應頂層,沒有 task 包裝。

提交回應

提交回傳 202 與 HopBase 任務 ID:

{
  "id": "mmt60x430684635582774",
  "object": "video.generation.task",
  "model": "MiniMax-H3",
  "status": "queued",
  "billing_bucket": "2k"
}

任務查詢欄位

只有 completed 與 failed 是終態,其他任何值都按進行中處理。單條成片通常 1.5-3 分鐘完成。

進行中

{
  "id": "mmt60x430684635582774",
  "status": "processing"
}

成功

{
  "id": "mmt60x430684635582774",
  "status": "completed",
  "outputs": ["https://api.hop-base.com/..."],
  "usage": { "bucket": "2k", "billed_seconds": 4, "input_seconds": 0, "extra_input_images": 0, "cost": 3.4, "cost_usd": 0.5, "currency": "CNY" }
}

失敗

失敗任務沒有錯誤碼,只能看 error.message(非同步任務失敗):

{ "id": "mmt60x...", "status": "failed", "error": { "message": "..." } }

最小範例

# 1. 提交,文生影片必須帶 ratio
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [{
      "type": "text",
      "text": "無人機空拍視角,清晨的雪山山脈,雲海翻湧,金色陽光灑在山峰上"
    }],
    "resolution": "2K",
    "duration": 4,
    "ratio": "16:9"
  }'

# 2. 用回傳的 id 輪詢
curl https://api.hop-base.com/v1/video/tasks/mmt你的任務ID \
  -H "Authorization: Bearer sk-your-key"

圖生影片把首幀圖放進 content:

{
  "model": "MiniMax-H3",
  "content": [
    { "type": "text", "text": "鏡頭緩緩向前推近,畫面中的光影微微流動" },
    { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,..." }, "role": "first_frame" }
  ],
  "resolution": "768P",
  "duration": 4
}

注意事項

• image_url 不寫 role 時按首幀處理,參考模式下每張圖都要寫 "role": "reference_image"。
• 建立超過 2 小時仍未結束的任務會被自動判為失敗,MiniMax 任務不支援取消。
• outputs 是 api.hop-base.com 網域下的簽名位址,自任務完成起 24 小時有效。再次查詢返回同一位址、不會延長,過期存取回傳 410,請在有效期內下載保存。

常見報錯 → 改法

閘道自身校驗回傳 {"error":{"message":…,"type":"invalid_request_error"}},不帶 code,以 message 為準。

常見的 400 與 413 / 404 原文:

400 first/last-frame image-to-video and multimodal reference generation are mutually exclusive: ...
400 {"error":{"message":"request body does not match the JSON contract: json: unknown field \"prompt\"","type":"invalid_request_error"}}
400 callback_url is not supported yet; poll /v1/video/tasks/{id} for task progress
request body exceeds the 64 MiB limit (got N bytes)
invalid task ID format
task not found            # 用其他使用者的密鑰查詢也是這條

第一條通常是參考模式下漏寫了 role;第二條是傳了頂層 prompt,提示詞請放進 content。

任務失敗時按 error.message 處理:

計費

兩個模型 MiniMax 都按秒計費,單價隨輸出解析度走,不按 token 計量:

本次扣費 = usage.billed_seconds × usage.bucket 檔的單價

• 參考影片按輸入時長以同檔單價另計,即 MiniMax 自己的 input_seconds。
• 參考圖有免費額度,usage.extra_input_images 是超額張數。
• H3-Max 官方口徑是僅輸出影片計費,輸入素材不計費。
• H3-SelfHosted 的參考影片輸入時長向上取整到整秒,按輸出檔位同價計費;超出 5 張的參考圖按張計費。

提交 MiniMax 任務時按「可用餘額 − 進行中任務的預估費用 − 本次預估費用」判斷,不足回傳 402,code 為 insufficient_balance,任務結束後預估自動釋放。失敗的任務一律不計費。任務結束後,查詢回應根物件的 usage 還會帶 cost_usd（本任務從餘額實際扣除的美元金額，未扣費的失敗為 0）、cost（同一筆的人民幣金額）與 currency（恆為 CNY）。

官方牌價見價格頁。你的實際單價以登入後的模型廣場為準,每次請求的實際扣費見用量記錄。影片任務通用規則詳見影片總覽。

下一步

• 影片總覽——各影片系列對比與共用的餘額預占、逾時與結果位址規則
• 語音合成 API——MiniMax Speech 2.8 與聲音複製
• 錯誤碼與重試——含非同步任務失敗
• 並行、逾時與計費