ナビゲーションにスキップ

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 倍です。

POST/v1/videos/tasks試してみる

このモデルをテスト画面で開きます。BeatAPI の API キーを入力するとタスクを作成できます。実際に呼び出され、ご自身の残高から課金されます。

モデル ID

5 つの MiniMax H3 モデルがこのエンドポイントを共有しますが、受け付ける入力は異なります。以下の値はゲートウェイの仕様から直接取得したものです。

モデル IDduration(秒)resolution参照画像の最大数参照動画の最大数参照音声の最大数選ぶ場面
minimax-h34–30480p, 768p, 1080p, 2K933標準レーンで単価を抑えたい場合。入力は minimax-h3-fast と同じです。
minimax-h3-fast4–30480p, 768p, 1080p, 2K933優先レーンでより速く出力したい場合。単価は minimax-h3 の 2 倍で、入力は同じです。
minimax-h3-normal5–15480p, 768p, 1080p41—価格を最優先し、待ち時間が長くても構わない場合。レンダリングは遅くなりますが、768p では minimax-h3 より 3 分の 1 安くなります。seed が加わる一方、参照素材は少なくなります(音声は使えません)。
minimax-h3-max5–15480P, 768P, 1080P———テキスト、または 1~2 枚のフレームから始め、480P、768P または 1080P と seed を使いたい場合。参照入力は受け付けず、aspect_ratio もありません。
minimax-h3-max-turbo5–15480P, 768P, 1080P———入力と解像度は minimax-h3-max と同じで、定価はその半額です。

エンドポイントと認証

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 の後の再試行は改めて実行されます。

リクエストの流れ

1

タスクを作成する

下記のパラメーターをエンドポイントに POST します。201 が返れば、タスクが受け付けられ、料金が残高から仮確保されたことを意味します。処理はバックグラウンドで実行されます。data.id を保存してください。

2

完了を待つ

GET /v1/tasks/{task_id} を呼び出し、status が succeeded または failed になるまで、呼び出しの間隔を data.poll_after_seconds(画像は 5 秒、動画は 8 秒)だけ空けてください。あるいは task.succeeded と task.failed のWebhookを登録することもできます。処理タイムアウトで停止したタスクはイベントを送信しないため、フォールバックとしてポーリングも続けてください。

3

結果を保存する

succeeded の場合は、すべての data.output.media[].url をダウンロードし、必要なファイルを保存してください。結果 URL がいつまで利用できるかは保証されません。failed の場合は、data.error_code と data.error_message を確認してください。仮確保された金額は残高に戻されます。data.retryable は、同じリクエストをもう一度送れば成功する可能性があるかどうかを示します。

入力モード

モード必須の入力備考
テキストから動画model、promptメディアの配列は送らないでください。aspect_ratio を adaptive にすると拒否されます。
開始フレームmodel、prompt、images(リンク 1 個)動画はその画像から始まり、画像のアスペクト比を引き継ぎます。
開始フレームと終了フレームmodel、prompt、images(リンク 2 個)images[0] が開始フレーム、images[1] が終了フレームです。
参照model、prompt、および reference_images・reference_videos・reference_audios のうち少なくとも 1 つ任意の組み合わせが可能ですが、音声には参照画像か参照動画が少なくとも 1 つ必要です。images とは併用できません。

リクエストパラメーター

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 で拒否します。課金はされません。

メディアタスク作成前に確認される上限
画像幅・高さとも 256~5760 px;アスペクト比(幅 ÷ 高さ)0.4~2.5
動画合計 15 秒以内;23.976~60 FPS
音声1 本あたり 2~15 秒
  • これらの制限は 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>。

リクエスト例

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3",
"prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "768P"
}'

テキストから動画

5 秒の 768P 横長クリップです。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3",
"prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "768P"
}'

開始フレーム

動画はその画像から始まり、画像の形状に従います。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3",
"prompt": "The performer turns toward the camera as neon light sweeps across the stage",
"images": [
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"duration": 5,
"resolution": "768P"
}'

開始フレームと終了フレーム

動画は 1 枚目の画像から 2 枚目へ移ります。出力は 2K です。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3",
"prompt": "The camera moves smoothly from the bottle on the table to the singer on a neon stage in one continuous shot",
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png",
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"duration": 6,
"resolution": "2K"
}'

画像と音声の参照

キャラクター画像と音楽クリップに沿ったパフォーマンスです(サンプルのクリップは約 12 秒です)。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3",
"prompt": "The singer from the first reference image performs on stage in time with the reference music, warm spotlights, slow orbiting camera",
"reference_images": [
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"reference_audios": [
"https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
],
"duration": 8,
"aspect_ratio": "16:9",
"resolution": "768P"
}'

画像と動画の参照

動画のリンクは、15 秒以内で 23.976~60 フレーム毎秒の、ご自身の MP4 または MOV に置き換えてください。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "minimax-h3",
"prompt": "A product film: the bottle from the first reference image on a turntable, camera movement like the first reference video",
"reference_images": [
"https://cdn.beatapi.io/samples/smart-bottle.png"
],
"reference_videos": [
"https://your-cdn.example.com/clips/source.mp4"
],
"duration": 8,
"resolution": "768P"
}'

レスポンス

タスクの作成(201)

タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "minimax-h3",
"capability_version": 1,
"media_type": "video",
"model": "minimax-h3",
"status": "queued",
"stage": "queued",
"created_at": 1791993600,
"updated_at": 1791993600,
"completed_at": null,
"poll_after_seconds": 8,
"output": null,
"usage": {
"credits_reserved": 0.15,
"credits_settled": 0,
"credits_refunded": 0,
"credits_charged": 0.15,
"billable_duration_seconds": 5
},
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": null,
"error_message": null
}
}
フィールド型説明
data.idstringタスク ID です。task_ の後に英数字 32 文字が続きます。ポーリングや Webhook イベントとの照合に使います。
data.objectstring常に task です。
data.task_kindstringimage または video です。
data.capability_idstring送信したモデル ID です。
data.capability_versionintegerモデルの仕様バージョンです。現在は 1 です。
data.media_typestringimage または video です。
data.modelstring送信したモデル ID です(capability_id と同じ)。
data.statusstringqueued、processing、succeeded、failed のいずれかです。最終状態は後ろの 2 つだけです。
data.stagestringstatus と同じ値です。古いクライアント向けに残されています。
data.created_atintegerタスクの作成日時(Unix 秒)です。
data.updated_atinteger最終更新日時(Unix 秒)です。
data.completed_atinteger | nullタスクの完了日時(Unix 秒)です。実行中は null です。
data.poll_after_secondsinteger実行中のみ。次のポーリングまでに待つ秒数です(画像は 5、動画は 8)。
data.typical_secondsobject実行中のみ、直近のタスクが十分にある場合に含まれます。直近 window の samples 件のタスクについて、完了までの時間(秒)の p50 と p90 を示します。
data.outputobject | null結果です。status が succeeded になるまでは null です。下の出力フィールドを参照してください。
data.usage.credits_reservednumberタスク作成時に残高から仮確保された金額(USD)です。
data.usage.credits_chargednumberこのタスクの料金(USD)です。失敗したタスクでは 0 です。
data.usage.credits_settlednumber最終的に差し引かれた金額(USD)です。タスクが成功した時点で設定され、それ以外では 0 です。
data.usage.credits_refundednumber残高に戻された金額(USD)です。失敗したタスクでは、返金が記録された時点で仮確保した金額と一致します。
data.usage.billable_duration_secondsinteger動画のみ。料金の算定に使われた秒数です。モデルが長さを報告しない場合は含まれません。
data.request_idstringリクエスト ID です。サポートに問い合わせる際に添えてください。
data.error_codestring | null失敗コードです。タスクが失敗した場合以外は null です。
data.error_messagestring | null何が問題で、何を変更すればよいかを示します。タスクが失敗した場合以外は null です。

完了したタスク

GET /v1/tasks/{task_id} は HTTP 200 と status: "succeeded" を返し、結果は data.output に入ります。

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "minimax-h3",
"capability_version": 1,
"media_type": "video",
"model": "minimax-h3",
"status": "succeeded",
"stage": "succeeded",
"created_at": 1791993600,
"updated_at": 1791993690,
"completed_at": 1791993690,
"output": {
"media": [
{
"type": "video",
"url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
"mime_type": "video/mp4"
}
],
"r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
},
"usage": {
"credits_reserved": 0.15,
"credits_settled": 0.15,
"credits_refunded": 0,
"credits_charged": 0.15,
"billable_duration_seconds": 5
},
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": null,
"error_message": null
}
}

出力フィールド

フィールド型説明
output.mediaobject[]生成されたファイルです。このモデルでは動画 1 本です。
output.media[].typestring常に video です。
output.media[].urlstring保存された動画への HTTPS リンクです。ダウンロードして保管してください。保存期間は保証されません。
output.media[].mime_typestringファイルの種類です。たとえば video/mp4 です。
output.r2_urlstring古いクライアント向けに、動画の URL をもう一度返すものです。代わりに media を読んでください。

失敗したタスク

失敗したタスクも、GET /v1/tasks/{task_id} では HTTP 200 になります。失敗はボディに示されます。仮確保された金額は全額戻されるため、課金されません。

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "minimax-h3",
"capability_version": 1,
"media_type": "video",
"model": "minimax-h3",
"status": "failed",
"stage": "failed",
"created_at": 1791993600,
"updated_at": 1791993690,
"completed_at": 1791993690,
"output": null,
"usage": {
"credits_reserved": 0.15,
"credits_settled": 0,
"credits_refunded": 0.15,
"credits_charged": 0,
"billable_duration_seconds": 5
},
"retryable": true,
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": "processing_failed",
"error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
}
}
フィールド型説明
data.error_codestringbad_request と content_policy_violation(リクエストを修正してください)、または processing_unavailable、processing_timeout、processing_failed、result_transfer_failed(時間をおいて再試行してください)のいずれかです。エラーを参照してください。
data.error_messagestring問題と対処方法を示す文です。
data.retryableboolean失敗したタスクにのみ含まれます。同じリクエストをもう一度送れば成功する可能性がある場合は true です。
data.usageobject返金が記録された時点(通常はタスクが失敗した瞬間)で、credits_charged と credits_settled は 0 になり、credits_refunded は credits_reserved と一致します。

完全なコード例

タスクを作成し、サーバーが示すポーリング間隔で完了を待ち、結果の URL を出力します。環境変数に BEATAPI_API_KEY を設定し、requests をインストールしてください。

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
# One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
for attempt in range(3):
response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
if response.status_code in (429, 503) and attempt < 2:
time.sleep(int(response.headers.get("Retry-After", 10)))
continue
break
try:
payload = response.json()
except ValueError: # an edge error page is not JSON
response.raise_for_status()
raise
if not response.ok:
error = payload["error"]
raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
deadline = time.monotonic() + timeout_seconds
while time.monotonic() < deadline:
response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
if response.status_code == 429 or response.status_code >= 500:
time.sleep(int(response.headers.get("Retry-After", 10)))
continue
response.raise_for_status()
task = response.json()["data"]
if task["status"] in ("succeeded", "failed"):
return task
time.sleep(task.get("poll_after_seconds", 5))
raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
"model": "minimax-h3",
"prompt": "A slow cinematic push through a misty mountain village at dawn, smoke rising from the chimneys",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "768P"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
print(item["url"])

課金

  • 動画の秒数で課金します。リクエストした duration に選んだ解像度の単価を掛けます。15 秒までは 1 秒あたり 480p 0.02、768P0.02、768P 0.03、1080p 0.047、2K0.047、2K 0.05、16~30 秒ではすべての秒が 0.04、0.04、0.06、$0.094(480p、768P、1080p)です。
  • 参照動画は参照動画の秒数で課金され、単価は選んだ解像度と長さの区分の出力単価と同じです。たとえば 768P は 1 秒あたり 0.03、16~30秒の区分では0.03、16~30 秒の区分では 0.06 です。
  • フレームと参照画像の枚数、参照音声、アスペクト比は料金に影響しません。
  • 料金はタスクの作成時に確保されます。タスクの usage.billable_duration_seconds に、課金された秒数が表示されます。
  • 失敗したタスクは、送信後にモデレーションで拒否されたものも含め、全額返金されます。

現在の定価です。料金ページと同じ金額です。割引を個別に契約しているアカウントでは、より低い金額になります。実際に課金された金額は、タスクの data.usage で確認できます。

オプション定価(USD)
8 秒 · 480p$0.16
8 秒 · 768P$0.24
8 秒 · 1080p$0.376
8 秒 · 2K$0.4

よくあるエラー

エラーまたは症状原因対処
400 "resolution" must be one of: [480p 480P 768p 768P 1080p 1080P 2K 2k]4K など一覧にない値を送っています。480p、768P、1080p、2K のいずれかを送ってください。
400 "duration" is outside its supported range4~30 の整数(2K は 4~15)ではない、または文字列として送っています。5 のような整数を送ってください。
400 Cannot combine "images" with reference inputs in one task同じリクエストでフレームと reference_* を併用しています。フレームか参照のどちらかを使ってください。複数の画像を使う場合は、すべて reference_images に入れます。
400 MiniMax H3 text mode does not support aspect_ratio=adaptive画像も参照入力もないのに adaptive を指定しています。16:9 のような固定の比率を送るか、aspect_ratio を省略してください。
400 minimax-h3 audio reference requires at least one reference image or videoreference_audios だけを送っています。参照画像または参照動画を追加するか、音声を外してください。
400 The reference videos run 20 seconds in total; this model takes at most 15.参照クリップの合計が長すぎます。クリップを短くするか、外してください。
400 field "seed" is not supported by model minimax-h3このモデルが受け付けないフィールドを送っています(seed は minimax-h3-normal、minimax-h3-max、minimax-h3-max-turbo のみで使えます)。そのフィールドを削除してください。
タスクが failed になり、content_policy_violation が返るプロンプト、入力、または結果がモデレーションで拒否されました。プロンプトや入力を変更してください。同じ内容で再試行しても再び失敗します。課金はされません。
402 insufficient_credits残高が、リクエストで確保する料金に足りていません。チャージするか、duration または resolution を下げてください。

HTTP エラー早見表

タスクが作られる前のエラーは、2xx 以外のレスポンスで返されます。課金はされません。error.code または error.retryable で処理を分岐してください。message には問題の内容が示されます。全一覧と再試行のルールはエラーにあります。

{
"error": {
"code": "bad_request",
"message": "\"prompt\" is required",
"retryable": false,
"request_id": "req_5f0c2a9e4b7d4e31"
}
}
HTTP ステータスerror.code対処方法
400bad_request, content_policy_violationリクエストを修正してください。メッセージにフィールド名が示されます。そのまま再試行しないでください。
401missing_api_key, invalid_api_key(古いクライアントでは unauthorized が返ることがあります)有効なキーを Authorization: Bearer <key> で送信してください。
402insufficient_credits残高をチャージするか、キーのクォータを引き上げてから、再度送信してください。
403forbiddenこのキーまたはアカウントでは、このモデルを利用できない可能性があります(たとえば、無料クレジットは一部のモデルにのみ使えます)。そのまま再試行しないでください。
404not_foundGET /v1/tasks/{task_id} の場合:このキーのアカウントに該当するタスクが存在しません。ID を確認してください。
409idempotency_conflict新しい Idempotency-Key を使うか、同じキーの最初のリクエストが完了するまで待ってください。
429rate_limit_exceededRetry-After の秒数(error.retry_after_seconds にも含まれます)だけ待ってから再試行してください。
500internal_errorバックオフを入れて再試行してください。解消しない場合は、request_id を添えてサポートにお問い合わせください。
503processing_unavailable, processing_timeout, processing_failed, result_transfer_failed課金はされていません。指数バックオフで再試行してください。

認証

AuthorizationBearer

API キーを Authorization: Bearer <BEATAPI_API_KEY> として送信してください。

ヘッダー

Idempotency-Keystringオプション<=255 characters

ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値(255 文字以内)を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。

リクエスト

This endpoint expects an object.
modelenum必須

実行するモデルです。

値:minimax-h3

値が正しくない場合

  • 指定がない:"model" is required
  • 画像モデルをこのエンドポイントに送った:"model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint
許可された値:
promptstring必須1-5000 characters

動画で起こることを記述します。被写体、動き、カメラワーク、スタイルなどです。参照を使う場合は、それぞれの入力の役割を書いてください。

長さ:1–5000 文字

  • 長さは文字数で数えます(CJK の文字も 1 文字です)。
  • 入力は位置で参照します。たとえば「1 枚目の参照画像」のように書きます。

値が正しくない場合

  • 指定がない:"prompt" is required
  • 空、または上限を超えている:"prompt" has an unsupported length
aspect_ratioenumオプション

動画の形状を 幅:高さ で指定します。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
durationintegerオプション4-30デフォルト値 5

動画の長さを秒単位の整数で指定します。

デフォルト:5

範囲:4–30

  • 4~30 秒で、2K は最長 15 秒です。
  • 省略すると 5 になります。
  • 15 秒を超えると、すべての秒が 16~30 秒の単価で課金されます(課金を参照)。

値が正しくない場合

  • 範囲外、または整数ではない:"duration" is outside its supported range
imageslist of stringsオプション

開始フレーム、または開始フレームと終了フレームです。

要素数: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_audioslist of stringsオプション

従わせたい音楽、音声、サウンドです。

要素数: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.
reference_imageslist of stringsオプション

動画の内容、キャラクター、商品、スタイルを導く画像です。

要素数: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_videoslist of stringsオプション

動き、カメラワーク、内容を取り入れるための動画です。

要素数: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.
resolutionenumオプションデフォルト値 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]
許可された値:

レスポンス

タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

エラー

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error