MiniMax H3
テキスト、1~2 枚のフレーム、または最大 9 枚の画像・3 本の動画・3 件の音声を参照として使い、480p・768P・1080p・2K の 4~30 秒の動画(2K は最長 15 秒)を生成します。料金は秒単位です。
- 非同期です。作成の呼び出しはタスク ID を返し、動画はタスクが成功した時点で得られます。
- 入力方法は 4 通りです。テキストのみ、開始フレーム、開始フレームと終了フレーム、または参照画像・参照動画・参照音声です。
- 解像度は 480p、768P(デフォルト)、1080p、2K の 4 種類です。2K は最長 15 秒です。
- 動画の秒数に、選んだ解像度の単価を掛けて課金します。失敗したタスクには課金されません。
minimax-h3 はこのモデルの標準レーンです。minimax-h3-fast は同じモデル・同じ入力を優先レーンで動かし、より速く出力します。1 秒あたりの料金は 2 倍です。
このモデルをテスト画面で開きます。BeatAPI の API キーを入力するとタスクを作成できます。実際に呼び出され、ご自身の残高から課金されます。
モデル ID
5 つの MiniMax H3 モデルがこのエンドポイントを共有しますが、受け付ける入力は異なります。以下の値はゲートウェイの仕様から直接取得したものです。
エンドポイントと認証
POST https://api.beatapi.io/v1/videos/tasks
Authorization
string
必須
BeatAPI の API キーを Bearer <BEATAPI_API_KEY> の形式で送信します。キーはダッシュボードで作成できます。キーはサーバー側で保管し、ブラウザーやモバイルアプリに含めないでください。
ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値(255 文字以内)を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。
リクエストの流れ
タスクを作成する
下記のパラメーターをエンドポイントに POST します。201 が返れば、タスクが受け付けられ、料金が残高から仮確保されたことを意味します。処理はバックグラウンドで実行されます。data.id を保存してください。
完了を待つ
GET /v1/tasks/{task_id} を呼び出し、status が succeeded または failed になるまで、呼び出しの間隔を data.poll_after_seconds(画像は 5 秒、動画は 8 秒)だけ空けてください。あるいは task.succeeded と task.failed のWebhookを登録することもできます。処理タイムアウトで停止したタスクはイベントを送信しないため、フォールバックとしてポーリングも続けてください。
入力モード
リクエストパラメーター
model
string
必須
実行するモデルです。
値:minimax-h3
値が正しくない場合
- 指定がない:
"model" is required - 画像モデルをこのエンドポイントに送った:
"model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint
prompt
string
必須
動画で起こることを記述します。被写体、動き、カメラワーク、スタイルなどです。参照を使う場合は、それぞれの入力の役割を書いてください。
長さ:1–5000 文字
- 長さは文字数で数えます(CJK の文字も 1 文字です)。
- 入力は位置で参照します。たとえば「1 枚目の参照画像」のように書きます。
値が正しくない場合
- 指定がない:
"prompt" is required - 空、または上限を超えている:
"prompt" has an unsupported length
images
string[]
任意
開始フレーム、または開始フレームと終了フレームです。
要素数:1–2
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- リンク 1 個:動画はこの画像から始まります。リンク 2 個:
images[0]が開始フレーム、images[1]が終了フレームです。 - フレームを使う場合、動画の形状はフレームに従います。
aspect_ratioは適用されません。 - フレームではなく、動画を導くための画像には
reference_imagesを使ってください。
値が正しくない場合
- リンクが 3 個以上:
"images" accepts at most 2 items - いずれかの reference_* フィールドと併用した:
Cannot combine "images" with reference inputs in one task - https:// のリンクではない:
"images[0]" must be a public HTTPS URL
reference_images
string[]
任意
動画の内容、キャラクター、商品、スタイルを導く画像です。
要素数:1–9
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- プロンプトでは位置で参照します。
値が正しくない場合
- 上限を超えている:
"reference_images" accepts at most 9 items imagesと併用した:Cannot combine "images" with reference inputs in one task
reference_videos
string[]
任意
動き、カメラワーク、内容を取り入れるための動画です。
要素数:1–3
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- 参照動画の長さは合計で最大 15 秒、フレームレートは 23.976~60 フレーム毎秒です。下の制限も参照してください。
- 参照動画は秒単位で課金され、単価は選んだ解像度と長さの区分の出力単価と同じです(課金を参照)。
値が正しくない場合
- 上限を超えている:
"reference_videos" accepts at most 3 items - 合計が上限より長い:
The reference videos run 20 seconds in total; this model takes at most 15. - フレームレートが制限外:
reference_videos[0] runs at 12 frames per second; this model takes 23.976 to 60.
reference_audios
string[]
任意
従わせたい音楽、音声、サウンドです。
要素数:1–3
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- 音声には組み合わせが必要です。参照画像または参照動画を少なくとも 1 つ一緒に送ってください。
- 各クリップの長さは 2~15 秒にしてください。
値が正しくない場合
- 上限を超えている:
"reference_audios" accepts at most 3 items - 参照画像も参照動画もない音声:
minimax-h3 audio reference requires at least one reference image or video - クリップが 2~15 秒の範囲外:
reference_audios[0] is 1.5 seconds long; this model takes reference audio of 2 to 15 seconds.
duration
integer
任意デフォルト: 5
動画の長さを秒単位の整数で指定します。
デフォルト:5
範囲:4–30
- 4~30 秒で、2K は最長 15 秒です。
- 省略すると
5になります。 - 15 秒を超えると、すべての秒が 16~30 秒の単価で課金されます(課金を参照)。
値が正しくない場合
- 範囲外、または整数ではない:
"duration" is outside its supported range
aspect_ratio
string
任意
動画の形状を 幅:高さ で指定します。adaptive を指定すると、入力に基づいてモデルが選びます。
指定できる値:adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
- テキストから動画:省略すると
16:9になります。固定の比率を送ることもできます。adaptiveは、合わせる対象がないため拒否されます。 - 開始フレームまたは開始・終了フレーム:適用されません。動画はフレームの形状に従います。
- 参照:省略すると
adaptiveになります。固定の比率を送ることもできます。
値が正しくない場合
- 一覧にない値:
"aspect_ratio" must be one of: [adaptive 21:9 16:9 4:3 1:1 3:4 9:16] - テキストから動画で
adaptiveを指定した:MiniMax H3 text mode does not support aspect_ratio=adaptive
resolution
string
任意デフォルト: 768P
出力の解像度です。上の区分ほど 1 秒あたりの料金が高くなります。
指定できる値:480p, 768p, 1080p, 2K
デフォルト:768P
480p/480P、768p/768P、1080p/1080P、2K/2kは大文字・小文字どちらも同じ意味です。- 2K は最長 15 秒で、それより長い 2K のリクエストは課金前に拒否されます。4K は提供していません。
値が正しくない場合
- 一覧にない値(たとえば
720p、4K):"resolution" must be one of: [480p 480P 768p 768P 1080p 1080P 2K 2k]
ゲートウェイはタスク作成前に、次の組み合わせも確認します。
imagesと参照メディアのフィールドは同時に使用できません。- 480p・768P・1080p は 4〜30 秒、2K は最長 15 秒です。16〜30 秒の動画は 1 秒あたり 2 倍の単価で課金されます。minimax-h3-fast は同じモデルを優先レーンで動かし、単価は minimax-h3 の 2 倍です。
入力メディアの上限
ゲートウェイはタスク作成前にすべての入力を読み取り、次の上限を超えるものは、その入力を示す 400 bad_request で拒否します。課金はされません。
- これらの制限は
imagesとreference_images(画像)、reference_videos(動画)、reference_audios(音声)に適用されます。 - 入力は
images、reference_images、reference_videos、reference_audiosの順に 1 つずつ確認されます。1 つの入力については、長さ、辺の長さ、アスペクト比、フレームレートの順に確認され、すべての参照動画の合計の長さは最後に確認されます。メッセージには、フィールドのエラーと同じく 0 から数えた、リスト名と位置で入力が示されます:images[0] is 200x200 pixels; this model takes images 256 to 5760 pixels on each side. - 長さは 0.1 秒の許容誤差で測定されます。サイズは、ホストが情報を返した場合にのみ確認されます。
- リンクが作成時に拒否されるのは、そのホストが HTTP 4xx エラーを返すか、空のファイルを返した場合だけです。たとえば
reference_videos[0] could not be downloaded: the URL returned HTTP 404.です。入力のそれ以外の問題は送信後に判明し、タスクが失敗します(全額返金)。 - ローカルのファイルがある場合は、
POST /v1/filesでアップロードし、返されたdata.urlを渡してください。
このモデルが受け付けないフィールド
次のフィールドを送ると、無視されるのではなく、課金の前に拒否されます。
seed、generate_audio、watermark、quality、sound、およびほかの動画モデルのフィールド →field "seed" is not supported by model minimax-h3(送ったフィールド名が入ります)。- それ以外の未知のフィールド →
unknown field: <name>。
リクエスト例
テキストから動画
5 秒の 768P 横長クリップです。
開始フレーム
動画はその画像から始まり、画像の形状に従います。
開始フレームと終了フレーム
動画は 1 枚目の画像から 2 枚目へ移ります。出力は 2K です。
画像と音声の参照
キャラクター画像と音楽クリップに沿ったパフォーマンスです(サンプルのクリップは約 12 秒です)。
画像と動画の参照
動画のリンクは、15 秒以内で 23.976~60 フレーム毎秒の、ご自身の MP4 または MOV に置き換えてください。
レスポンス
タスクの作成(201)
タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。
完了したタスク
GET /v1/tasks/{task_id} は HTTP 200 と status: "succeeded" を返し、結果は data.output に入ります。
出力フィールド
失敗したタスク
失敗したタスクも、GET /v1/tasks/{task_id} では HTTP 200 になります。失敗はボディに示されます。仮確保された金額は全額戻されるため、課金されません。
完全なコード例
タスクを作成し、サーバーが示すポーリング間隔で完了を待ち、結果の URL を出力します。環境変数に BEATAPI_API_KEY を設定し、requests をインストールしてください。
課金
- 動画の秒数で課金します。リクエストした
durationに選んだ解像度の単価を掛けます。15 秒までは 1 秒あたり 480p 0.03、1080p 0.05、16~30 秒ではすべての秒が 0.06、$0.094(480p、768P、1080p)です。 - 参照動画は参照動画の秒数で課金され、単価は選んだ解像度と長さの区分の出力単価と同じです。たとえば 768P は 1 秒あたり 0.06 です。
- フレームと参照画像の枚数、参照音声、アスペクト比は料金に影響しません。
- 料金はタスクの作成時に確保されます。タスクの
usage.billable_duration_secondsに、課金された秒数が表示されます。 - 失敗したタスクは、送信後にモデレーションで拒否されたものも含め、全額返金されます。
現在の定価です。料金ページと同じ金額です。割引を個別に契約しているアカウントでは、より低い金額になります。実際に課金された金額は、タスクの data.usage で確認できます。
よくあるエラー
HTTP エラー早見表
タスクが作られる前のエラーは、2xx 以外のレスポンスで返されます。課金はされません。error.code または error.retryable で処理を分岐してください。message には問題の内容が示されます。全一覧と再試行のルールはエラーにあります。
認証
API キーを Authorization: Bearer <BEATAPI_API_KEY> として送信してください。
ヘッダー
ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値(255 文字以内)を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。
リクエスト
実行するモデルです。
値:minimax-h3
値が正しくない場合
- 指定がない:
"model" is required - 画像モデルをこのエンドポイントに送った:
"model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint
動画で起こることを記述します。被写体、動き、カメラワーク、スタイルなどです。参照を使う場合は、それぞれの入力の役割を書いてください。
長さ:1–5000 文字
- 長さは文字数で数えます(CJK の文字も 1 文字です)。
- 入力は位置で参照します。たとえば「1 枚目の参照画像」のように書きます。
値が正しくない場合
- 指定がない:
"prompt" is required - 空、または上限を超えている:
"prompt" has an unsupported length
動画の形状を 幅:高さ で指定します。adaptive を指定すると、入力に基づいてモデルが選びます。
指定できる値:adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
- テキストから動画:省略すると
16:9になります。固定の比率を送ることもできます。adaptiveは、合わせる対象がないため拒否されます。 - 開始フレームまたは開始・終了フレーム:適用されません。動画はフレームの形状に従います。
- 参照:省略すると
adaptiveになります。固定の比率を送ることもできます。
値が正しくない場合
- 一覧にない値:
"aspect_ratio" must be one of: [adaptive 21:9 16:9 4:3 1:1 3:4 9:16] - テキストから動画で
adaptiveを指定した:MiniMax H3 text mode does not support aspect_ratio=adaptive
動画の長さを秒単位の整数で指定します。
デフォルト:5
範囲:4–30
- 4~30 秒で、2K は最長 15 秒です。
- 省略すると
5になります。 - 15 秒を超えると、すべての秒が 16~30 秒の単価で課金されます(課金を参照)。
値が正しくない場合
- 範囲外、または整数ではない:
"duration" is outside its supported range
開始フレーム、または開始フレームと終了フレームです。
要素数:1–2
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- リンク 1 個:動画はこの画像から始まります。リンク 2 個:
images[0]が開始フレーム、images[1]が終了フレームです。 - フレームを使う場合、動画の形状はフレームに従います。
aspect_ratioは適用されません。 - フレームではなく、動画を導くための画像には
reference_imagesを使ってください。
値が正しくない場合
- リンクが 3 個以上:
"images" accepts at most 2 items - いずれかの reference_* フィールドと併用した:
Cannot combine "images" with reference inputs in one task - https:// のリンクではない:
"images[0]" must be a public HTTPS URL
従わせたい音楽、音声、サウンドです。
要素数:1–3
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- 音声には組み合わせが必要です。参照画像または参照動画を少なくとも 1 つ一緒に送ってください。
- 各クリップの長さは 2~15 秒にしてください。
値が正しくない場合
- 上限を超えている:
"reference_audios" accepts at most 3 items - 参照画像も参照動画もない音声:
minimax-h3 audio reference requires at least one reference image or video - クリップが 2~15 秒の範囲外:
reference_audios[0] is 1.5 seconds long; this model takes reference audio of 2 to 15 seconds.
動画の内容、キャラクター、商品、スタイルを導く画像です。
要素数:1–9
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- プロンプトでは位置で参照します。
値が正しくない場合
- 上限を超えている:
"reference_images" accepts at most 9 items imagesと併用した:Cannot combine "images" with reference inputs in one task
動き、カメラワーク、内容を取り入れるための動画です。
要素数:1–3
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。
- 参照動画の長さは合計で最大 15 秒、フレームレートは 23.976~60 フレーム毎秒です。下の制限も参照してください。
- 参照動画は秒単位で課金され、単価は選んだ解像度と長さの区分の出力単価と同じです(課金を参照)。
値が正しくない場合
- 上限を超えている:
"reference_videos" accepts at most 3 items - 合計が上限より長い:
The reference videos run 20 seconds in total; this model takes at most 15. - フレームレートが制限外:
reference_videos[0] runs at 12 frames per second; this model takes 23.976 to 60.
出力の解像度です。上の区分ほど 1 秒あたりの料金が高くなります。
指定できる値:480p, 768p, 1080p, 2K
デフォルト:768p
480p/480P、768p/768P、1080p/1080P、2K/2kは大文字・小文字どちらも同じ意味です。- 2K は最長 15 秒で、それより長い 2K のリクエストは課金前に拒否されます。4K は提供していません。
値が正しくない場合
- 一覧にない値(たとえば
720p、4K):"resolution" must be one of: [480p 480P 768p 768P 1080p 1080P 2K 2k]
レスポンス
タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

