MiniMax Hailuo：動画生成 API

利用できるモデル

正確な ID MiniMax-H3 / MiniMax-H3-Max / MiniMax-H3-SelfHosted を使用してください。エイリアスはなく、未知のモデル名は拒否されます。H3-Max は高速生成版で、5 秒のクリップは通常数秒で生成されます。段階別の価格と詳細仕様はモデルカード MiniMax-H3、MiniMax-H3-Max を参照してください。

MiniMax-H3-SelfHosted は Hailuo H3 のセルフホスト版で、H3 と同等の品質をより低い価格で提供します。リクエスト仕様は MiniMax-H3 と同じで、違いは次のとおりです。解像度に 480P、1080P、4K が加わります(一覧は上の表)。参照動画と参照音声は公開 http(s) URL が必須で、data: の埋め込みは受け付けません(画像は埋め込み可)。1 本の生成には通常 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 は 3 つ目のプラン MiniMax Speech 公式から提供されます。使い方は音声合成 APIを参照してください。MiniMax-H3-SelfHosted はプラン MiniMax H3 セルフホストから提供され、MiniMax-H3-Max はプラン MiniMax H3 Max クラウドからも利用できます(同じ公式モデルで、価格が異なります)。

キーが到達できるのは、そのキーに含まれるプランのモデルだけです。H3 と H3-Max の両方が必要なら、両方のプランを 1 つのキーに追加してください。課金対象の処理を送信する前に、キーが到達できるモデルを GET /v1/models で確認してください。

リクエストパラメータ

HopBase は MiniMax 公式の v2 契約を通じて MiniMax Hailuo(海螺) H3 を提供します。ボディは MiniMax 公式の POST /v2/video_generation リクエストをそのまま反映しており、厳格にデコードされます。未知のフィールドと 2 つ目の JSON 値は、リクエストが送信される前に拒否されます。

受け付けるトップレベルのフィールドは下表のみです。それ以外(OpenAI の prompt / size / n / seconds / image を含む)は 400 を返します。

先頭/末尾フレームモードの ratio は有効な値をすべて受け付け、出力は常に adaptive(画像に従う)です。特定の比率が必要なら先にフレームをクロップしてください。すべてのリクエストは Authorization: Bearer sk-your-key と Content-Type: application/json を使用します。

content の要素

個数・role・組み合わせは送信時に検証し、ファイルサイズ・寸法・コーデック・長さは実行時に MiniMax が検証します。先頭/末尾フレームと reference_* 要素は同じリクエスト内で排他で、1 リクエストのメディアは合計 12 ファイルまでです。

メディアの url には公開された絶対 http(s) URL または data: URI(base64)を指定できます。mm_file:// は拒否されます。そのファイルはお客様自身の MiniMax アカウントに属し、ゲートウェイからはアクセスできないためです。MiniMax-H3-SelfHosted の video_url と audio_url は公開 http(s) URL が必須で、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 本のクリップは 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": "Aerial shot of snow mountains above clouds at sunrise"
    }],
    "resolution": "2K",
    "duration": 4,
    "ratio": "16:9"
  }'

# 2. 返された id でポーリング
curl https://api.hop-base.com/v1/video/tasks/mmt-your-task-id \
  -H "Authorization: Bearer sk-your-key"

画像から動画を生成する場合は、先頭フレームを content に入れます。

{
  "model": "MiniMax-H3",
  "content": [
    { "type": "text", "text": "The camera slowly pushes in, light drifting across the scene" },
    { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,..." }, "role": "first_frame" }
  ],
  "resolution": "768P",
  "duration": 4
}

注意事項

• role のない image_url は先頭フレーム扱いになるため、参照モードではすべての画像に "role": "reference_image" を指定してください。
• 作成から 2 時間経っても完了しないタスクは自動的に失敗扱いになり、MiniMax のタスクを取り消すことはできません。
• outputs は api.hop-base.com 上の署名付き URL で、タスク完了時点から 24 時間有効です。再度照会しても同じ URL が返るだけで有効期限は延長されず、期限切れの URL は 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            # 他ユーザーのキーでの照会もこれになる

1 つ目は参照モードで role を書き忘れた場合、2 つ目はトップレベルに prompt を送った場合によく出ます。プロンプトは content に入れてください。

失敗したタスクは error.message に応じて対処します。

課金

MiniMax はどちらのモデルについても、トークンではなく出力解像度に応じたレートで動画の秒数単位で課金します。

課金額 = usage.billed_seconds × usage.bucket のレート

• 参照動画は、その入力の長さに対して同じレートで別途課金されます(MiniMax 自身の input_seconds)。
• 参照画像には無料の割り当てがあり、usage.extra_input_images がその割り当てを超えた枚数を示します。
• H3-Max では、MiniMax は出力動画のみを課金対象とし、入力素材には課金しません。
• H3-SelfHosted では、参照動画の入力秒数は整数秒に切り上げられ、出力と同じ区分の単価で課金されます。5 枚を超える参照画像は 1 枚ごとに課金されます。

MiniMax のタスクを送信する際は、「利用可能残高 − 実行中タスクの見積もり額 − 今回のリクエストの見積もり額」で判定され、不足している場合は code が insufficient_balance の 402 が返ります。見積もり額はタスク終了時に自動的に解放されます。失敗したタスクは一切課金されません。タスク終了後は、照会レスポンスのルートの usage に cost_usd(このタスクで残高から実際に差し引かれた米ドル額。課金なしの失敗は 0)、cost(同じ課金額の人民元額)、currency(常に CNY)も含まれます。

公式のリスト価格は料金ページに掲載されています。実際の適用レートはログイン後のモデルカタログに表示され、各リクエストの実際の課金額は利用量レコードで確認できます。すべての動画ファミリーに共通するルールは動画の概要を参照してください。

次のステップ

• 動画の概要:動画ファミリーの比較と、共通の残高の仮押さえ、タイムアウト、結果 URL
• 音声合成 API:MiniMax Speech 2.8 とボイスクローン
• エラーコードと再試行:非同期タスクの失敗を含む
• 同時実行数、タイムアウト、課金