コンテンツにスキップ
RouteAPI RouteAPI

MiniMax Hailuo

Hailuo は MiniMax の動画生成シリーズです。同じチャネルが 2 世代の API を提供します。MiniMax-H3 と MiniMax-H3-Max は MiniMax の /v2 API を使い、リクエスト本文は content 配列で、秒単位で精算されます。MiniMax-Hailuo-2.3 系は古い /v1 API を使い、タスクごとの固定価格で課金されます（本ページ末尾）。

タスクの送信・ポーリング・ダウンロードは共通のエンドポイントを使います。タスクの作成とタスクの取得を参照してください。本ページでは、このベンダーのアダプターがどのフィールドを読み取るか、リクエストがどう組み立てられるか、そして課金方法を説明します。

モデル

Section titled “モデル”
モデル ID解像度長さ（整数秒）既定値プロンプト拡張
MiniMax-H3768P、2K4–15768P、5 秒非対応
MiniMax-H3-Max480P、768P5–15768P、5 秒対応
  • モデル ID は大文字小文字を区別します。上の表のとおりに入力してください。アカウントで使えるのはルーティングされたモデルだけで、価格もアカウントごとに異なります。GET /v1/models が現在のキーにとっての正式な一覧です。
  • extra を受け付けるのは MiniMax-H3-Max だけです。MiniMax-H3 に extra を送ると 400 を返します。
  • テキストから動画、最初のフレーム、最初と最後のフレーム、参照画像・参照動画・参照音声は、どちらのモデルもサポートします。

リクエストパラメータ

Section titled “リクエストパラメータ”
フィールド型必須既定値説明
modelstringはい—GET /v1/models のモデル ID
promptstringはい—プロンプト。空白を除いて空なら拒否。最大 7000 文字
resolutionstringいいえ768P大文字小文字を区別しない。そのモデルが対応する解像度のみ
durationintegerいいえ5整数秒。モデルの範囲内であること
secondsstringいいえ—長さの文字列表現。duration がない（または 0）ときだけ有効
ratiostringいいえ下記アスペクト比
imagesstring[]いいえ—1 枚なら最初のフレーム、2 枚なら最初と最後。最大 2 枚
imagestringいいえ—単一画像。images が空のときだけ使われる
metadataobjectいいえ—MiniMax のパラメータ。次の節を参照

優先順位のルール：

  • metadata.resolution、metadata.duration、metadata.ratio は同じ名前のトップレベル項目を上書きします。
  • seconds はトップレベルの duration がない、または 0 のときだけ読まれ、metadata.duration はその両方より優先されます。
  • metadata.duration は数値として解析されるため、5.5 は invalid duration になります。トップレベルの duration と違い、ここでの 0 は「未設定」ではなく範囲外です。既定値を使うならこのキー自体を省略してください。
  • size はサポートされません。トップレベルまたは metadata に size を送ると MiniMax-H3 请使用 resolution(480P/768P/2K),不支持 size を返します。resolution を使ってください。
  • size 以外の、このベンダーが読まないトップレベル項目（generate_audio、input_reference など）は無視され、エラーにはなりません。

metadata パラメータ

Section titled “metadata パラメータ”
フィールド型説明
contentarray入力素材。content の素材と制限を参照。トップレベルの images / image とは併用不可
resolutionstringトップレベルの resolution を上書き
durationnumberトップレベルの duration と seconds を上書き。範囲内の整数であること
ratiostringトップレベルの ratio を上書き
aigc_watermarkboolean または stringtrue / false。文字列 "true" / "false" も受け付けます（multipart フォームは文字列で送るため）。省略時は上流が判断
extra.prompt_expansion_modestringdisabled、balanced、quality。MiniMax-H3-Max のみ
size—400 を返す

metadata は型付き構造体にデコードされます。上のキーの JSON 型が違う場合（"duration": "abc"、content をオブジェクトにするなど）は 400 と invalid metadata: で始まるメッセージを返し、課金は発生しません。表にないキー（seed、callback_url など）は無視され、MiniMax には送られません。コールバックは送られないため、結果はポーリングしてください。

アスペクト比 ratio

Section titled “アスペクト比 ratio”

指定できる値：adaptive、21:9、16:9、4:3、1:1、3:4、9:16。大文字小文字は区別しません。

リクエストの種類ratio 省略時ルール
テキストのみ（フレームも参照もなし）16:9adaptive を送ると text-to-video does not support ratio adaptive
最初のフレーム、または最初と最後adaptive強制的に adaptive。送った値は無視され、検証もされません
参照素材（参照画像・動画・音声）adaptive7 つの値すべて利用可

content の素材と制限

Section titled “content の素材と制限”

metadata.content は順序付きの配列です。各項目は type、その型に対応するペイロードフィールド、任意の role を持ちます。

typeペイロード利用できる role上限
texttextなし1 件。prompt と一致すること
image_urlimage_url.urlfirst_frame1
image_urlimage_url.urllast_frame1。first_frame が必須
image_urlimage_url.urlreference_image9
image_urlimage_url.urlなし唯一の素材であるときのみ
video_urlvideo_url.urlreference_video（必須）3
audio_urlaudio_url.urlreference_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://..." } }

送信前に次のルールが検証されます。

  • 1 リクエストの素材は合計 12 個まで。参照画像は 9 枚、参照動画は 3 本、参照音声は 3 本まで。
  • 最初・最後のフレームと参照素材は併用できません。reference_image、reference_video、reference_audio は自由に組み合わせられます。
  • role のない image_url は、それが唯一の素材であるときだけ許可され、最初のフレームとして扱われます。
  • content に text 項目がない場合、RouteAPI がトップレベルの prompt を持つ項目を先頭に追加します。ある場合は 1 件だけで、内容は前後の空白を除いた 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] に置き換えられるため、署名付きの素材 URL がエラーメッセージに出ることはありません。
  • 個々の素材の形式・サイズ・長さ・ファイルサイズの制限は MiniMax 側の仕様で、RouteAPI は検証しません。要件を満たさない素材は、送信時に拒否される（400、課金なし）か、生成中に拒否される（タスクが FAILURE になり予約額は返金）かのいずれかです。

例

Section titled “例”

テキストから動画

Section titled “テキストから動画”
Terminal window
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
  }'

最初のフレーム

Section titled “最初のフレーム”
Terminal window
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
  }'

最初と最後のフレーム

Section titled “最初と最後のフレーム”

images の 2 件が順に first_frame と last_frame になります。ratio は adaptive に固定されます。

Terminal window
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
  }'

参照画像・参照動画・参照音声

Section titled “参照画像・参照動画・参照音声”

2 枚を超える画像や参照動画・参照音声が必要なときは metadata.content を使います。参照動画は課金対象なので、長さは 2〜15 秒に収めてください。課金を参照。

Terminal window
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 のプロンプト拡張とウォーターマーク

Section titled “H3-Max のプロンプト拡張とウォーターマーク”
Terminal window
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" }
    }
  }'

タスクの状態と結果

Section titled “タスクの状態と結果”

ステータス対応

Section titled “ステータス対応”
MiniMax task.statusdata.statusdata.progress
queuedQUEUED20%
runningIN_PROGRESS50%
succeeded で content.url ありSUCCESS100%
succeeded だが content.url なしFAILURE100%
failed、cancelledFAILURE100%
その他の値IN_PROGRESS30%

succeeded でも動画 URL がない場合は失敗となり、fail_reason は upstream succeeded without video url になって予約額が返金されます。failed または cancelled の場合は MiniMax の task.error.message が fail_reason になります（含まれる URL は [url omitted] に置き換え）。MiniMax が理由を返さないときは task failed または task cancelled です。

ポーリング結果がエラー封筒（{"type":"error","error":{...}}）のとき、その回のポーリングは失敗として扱われ、次回また問い合わせます。タスクオブジェクトがまったくない本文は古い /v1 形式として解析され、空になるため、タスクは IN_PROGRESS のままです。終状態に到達しないタスクはプラットフォームのタイムアウト（既定 24 時間）で失敗し、fail_reason は 任务超时（1440分钟）、予約額は返金されます。

タスクレコード

Section titled “タスクレコード”

GET /v1/video/generations/{task_id} は RouteAPI のタスク行を返します。全フィールドはタスクの取得に記載しています。このベンダーでよく使うのは次のとおりです。

フィールド説明
data.status / data.progress上の表によるタスク状態と進捗
data.result_url成功後の動画 URL
data.fail_reason失敗理由。成功時は空
data.quotaこのタスクで課金されたクォータ
data.properties.inputRouteAPI が上流に送ったリクエストのスナップショット。素材 URL は [omitted, N bytes] に置換され、請求の確認に使える
data.dataMiniMax の最新レスポンス
{
  "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.idMiniMax のタスク ID。RouteAPI の task_id とは異なる
data.data.task.statusqueued、running、succeeded、failed、cancelled
data.data.task.content.url成功時の動画 URL。result_url に入るのはこれ
data.data.task.resolutionMiniMax が報告する解像度。課金はリクエストの解像度を使う
data.data.task.usage.output_seconds実際に出力された秒数。精算に使われる
data.data.task.usage.input_seconds参照動画の秒数。精算に使われる
data.data.task.usage.input_image_countMiniMax が報告する画像枚数。精算は送信時の枚数を使う
data.data.task.error.code / .messageMiniMax が失敗理由を返したときのエラーコードとメッセージ

最初の成功ポーリングより前は、data.data は送信時の生のレスポンス（{"task_id": "..."}）で、task フィールドはありません。task.usage は MiniMax が返したときにだけ現れ、通常は成功時です。タスクが終わったかどうかは常に外側の data.status で判断してください。

動画のダウンロード

Section titled “動画のダウンロード”

data.result_url は MiniMax の CDN を直接指します。このリンクは MiniMax の都合で失効するため、SUCCESS になったらすぐにダウンロードしてください。

  • CDN の直リンク：Authorization ヘッダーを付けずに取得します。ストレージによっては余分な認証ヘッダーを拒否します。
  • https://api.routeapi.ai/v1/videos/{task_id}/content：保存済みの URL を RouteAPI 経由でストリームし、Authorization: Bearer $ROUTEAPI_KEY が必要です。毎回保存済みリンクを取得し直すだけなので、失効は延びません。クライアントに上流のホストを見せたくない場合や、CDN が直接アクセスを拒否する場合に使います。存在しないタスクには 404 Task not found、成功前には 400 Task is not completed yet, current status: ... を返します。
Terminal window
# 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"

課金

Section titled “課金”

アカウントでそのモデルに固定価格が設定されている場合（コンソールのモデル詳細ページに表示されます）、H3 は秒単位で課金されます。モデル倍率だけで価格設定されている場合は通常のタスク単位の事前課金になり、完了時の差額精算はありません。秒単位の課金では、1 タスクの費用は 3 つの要素の合計です。

要素単価送信時の予約精算時
出力動画リクエスト解像度ごとの秒単価リクエストの durationmin(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 モデルでは {} です。

計算例

Section titled “計算例”

次の価格は計算の説明のためだけの仮定です。MiniMax-H3 の 768P で出力 1 秒 $0.10、参照動画 1 秒 $0.10、無料 5 枚を超えた分 1 枚 $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 が残高に戻ります。

エラー

Section titled “エラー”

送信前にすべて検証されるため、400 では課金されません。MiniMax の業務上の拒否は HTTP 200 のレスポンス内で返り、次のように変換されます。

MiniMax base_resp.status_code意味返る HTTP ステータスcode
1026コンテンツ／安全審査での拒否4001026
2013パラメータエラー4002013
1002レート制限4291002
1004、2049上流キー／認証の失敗401（通常は 503 で返る）1004 / 2049、または get_channel_failed
1008上流アカウントの残高不足503get_channel_failed
その他の業務コード不明な業務エラー502数値のコード
—（本文が解析できない、または type: "error" 封筒）送信レスポンスの形式異常502invalid_response
—（task_id が空）上流がタスク ID を返さない502upstream_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 requiredprompt がない、または空
seconds must be between 1 and 3600（コード invalid_seconds）トップレベルの duration が負、または 3600 超
invalid seconds: abcseconds が整数の文字列でない
<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 mediaimages が 2 件を超えた
images must not contain empty valuesimages に空文字列がある
metadata.content cannot be combined with top-level images両方を同時に送った
metadata.content must be a non-empty arraycontent が []
prompt 与 metadata.content 中的 text 冲突text 項目が prompt と一致しない
metadata.content accepts at most one text itemtext 項目が複数ある
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 imagerole なしの画像を他の素材と併用した
last_frame requires first_frame最後のフレームだけを送った
at most one first_frame and one last_frameフレームの role が重複した
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 も同様）mm_file:// など未対応の URL スキーム
MiniMax-H3 does not support extraMax 以外のモデルに metadata.extra を送った
invalid extra.prompt_expansion_mode: balance, supports disabled, balanced, quality拡張モードが一覧にない
invalid metadata: ...metadata のキーの JSON 型が誤り

送信成功後に起きた失敗（コンテンツモデレーション、素材のダウンロード不可、キャンセル、タイムアウト）は HTTP エラーにはなりません。タスクレコードに FAILURE と fail_reason として現れ、予約額は返金されます。

MiniMax 公式 API との違い

Section titled “MiniMax 公式 API との違い”
  • パスは 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 より厳格です。MiniMax はその多くを生成段階に任せています。
  • 転送されるのは model、content、resolution、duration、ratio、aigc_watermark、extra だけです。callback_url を含む他の MiniMax パラメータは破棄されます。
  • 素材は公開 http(s) または data: URL である必要があり、MiniMax の mm_file:// ファイル ID は使えません。
  • resolution と duration を省略すると RouteAPI が 768P、5 秒で補うため、上流は常に明示的な値を受け取ります。
  • 成功時は MiniMax の content.url をそのまま result_url として保存するので、別途ファイル取得 API を呼ぶ必要はありません。

完全なポーリングスクリプト

Section titled “完全なポーリングスクリプト”

bash、curl、jq が必要です。5 秒のテキストから動画のタスクを送信し、15 秒間隔で最大 30 分ポーリングし、結果をダウンロードします（Authorization を付けるのは RouteAPI のプロキシ形式のときだけ）。最後に課金に関係する 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

Section titled “MiniMax-Hailuo-2.3”

MiniMax-Hailuo-2.3 と MiniMax-Hailuo-2.3-Fast は MiniMax の /v1/video_generation API を使い、秒単位ではなくタスク単位で課金されます。RouteAPI は送信後に /v1/query/video_generation をポーリングし、MiniMax の /v1/files/retrieve でダウンロード URL を取得して result_url に保存します。

モデル ID説明
MiniMax-Hailuo-2.3テキストから動画、画像から動画
MiniMax-Hailuo-2.3-Fast2.3 の高速・低価格版

どちらも既定は 768P と 6 秒です。共通の 0〜3600 秒の検証を除き、タスク API はこのシリーズの解像度や長さの範囲を検証しません。値はそのまま転送され、MiniMax が判断します。コンソールのプレイグラウンドでは 768P / 1080P と 6 秒または 10 秒を選べ、1080P は 6 秒に限られます。

リクエストの対応（2.3）

Section titled “リクエストの対応（2.3）”
封筒のフィールドアダプターの動作
promptprompt として送信。metadata.prompt があればそちらが優先
durationduration として送信。省略または 0 なら 6
size部分文字列で resolution に変換：1080 → 1080P、768 → 768P、720 → 720P、512 → 512P。それ以外はモデルの既定値
images / image読みません。 画像入力は metadata.first_frame_image で渡す必要があります
ratio、generate_audio、seconds読みません。 このシリーズにはアスペクト比やサウンドトラックのパラメータがありません
metadataMiniMax のフィールド名で MiniMax のフィールドにデコード

このシリーズはトップレベルの resolution を読みません。size か metadata.resolution を使ってください。

ベンダーパラメータ（2.3）

Section titled “ベンダーパラメータ（2.3）”

いずれも metadata の下に置きます。JSON 型が誤っていると（"duration": "abc" など）、変換に失敗して 400 ではなく 500 build_request_failed を返します。未知のキーは無視されます。

フィールド型説明
resolutionstring768P または 1080P。size から変換された値を上書き
durationinteger6 秒または 10 秒。トップレベルの duration を上書き
first_frame_imagestring画像から動画の最初のフレーム（公開 URL または base64 の data: URI）。そのまま転送
last_frame_imagestring最初と最後のフレームの最後のフレーム。そのまま転送
subject_referencearray被写体参照動画の参照：[{"type": "character", "image": ["<url>"]}]
prompt_optimizerbooleanMiniMax にプロンプトを書き換えさせる。明示的な false も転送
fast_pretreatmentbooleanMiniMax の高速前処理フラグ。送った値のまま転送
aigc_watermarkbooleanプロバイダの AIGC ウォーターマークを付与
callback_urlstringMiniMax に転送。RouteAPI はコールバックを登録も受信もしないため、結果はポーリングすること
promptstringトップレベルの prompt を上書き

metadata.model はチャネルの上流モデル名で上書きされるため、metadata 経由で別の（より高価な）モデルに切り替えることはできません。

画像から動画（2.3）

Section titled “画像から動画（2.3）”
Terminal window
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）

Section titled “ステータス対応（2.3）”

MiniMax v1 は Preparing、Queueing、Processing、Success、Fail を返します。

上流ステータスタスクレコードの状態進捗
Preparing、QueueingIN_PROGRESS30%
ProcessingIN_PROGRESS50%
SuccessSUCCESS100%
FailFAILURE100%

成功時、アダプターは返された file_id で MiniMax のファイル取得エンドポイントを呼び、得たダウンロード URL を result_url に保存します。この URL は MiniMax の都合で失効します。GET /v1/videos/{task_id}/content は保存済みの URL を RouteAPI 経由でストリームし、Authorization が必要です。

課金（2.3）

Section titled “課金（2.3）”

2.3 系はコンソールで設定されたタスク単価で課金されます。送った解像度や長さで金額は変わらず、完了時の差額精算もありません。失敗したタスクは予約額が返金されます。X-New-Api-Other-Ratios は {} です。

エラー（2.3）

Section titled “エラー（2.3）”
ステータスcode意味
400invalid_requestprompt の欠落・空、または JSON の形式エラー
400invalid_secondsduration / seconds が負、または 3600 超
400MiniMax の数値コードMiniMax がタスクを拒否。メッセージは status_msg
400task_not_existtask_id が不明、または他アカウントのもの
500build_request_failed、do_request_failedmetadata の変換失敗、または上流に到達できない
500unmarshal_response_body_failedMiniMax がアダプターの知らない形式で応答した
502upstream_task_id_missing送信レスポンスにタスク ID がなかった
上流ステータスfail_to_fetch_taskMiniMax が 200 以外の HTTP ステータスを返した

このシリーズでは MiniMax の業務上の拒否はレート制限も含めてすべて 400 で返ります。数値の code と status_msg がそのまま渡るので、HTTP ステータスではなく数値コードを見てください。例外は上流の残高不足です。MiniMax の status_msg が RouteAPI 内蔵の課金キーワード（残高不足など）に一致した場合は 503 get_channel_failed と汎用メッセージに置き換えられ、チャネルの障害として記録されます（自動無効化が有効で、そのチャネルが自動無効化を許可している場合にのみ自動的に無効化されます）。

送信後の失敗（モデレーション、プロバイダのタイムアウト）はタスクレコードに FAILURE と fail_reason として現れ、事前に課金された金額が返金されます。