MiniMax H3 API チュートリアル：テキストから動画、始点・終点フレーム、マルチモーダル参照

MiniMax H3 は MiniMax の汎用マルチモーダル動画生成モデルです。テキスト、画像、動画、音声の素材を理解し、ネイティブ音声付きのショート動画を生成できます。HiAPI 経由で接続する場合、モデル ID は minimax-h3 に固定され、画像・動画・音声モデルはすべて同じ非同期タスクインターフェースを利用します。

1 つのプロンプトからショート動画を作るだけであれば、prompt のみを渡せば十分です。商品の外観、ブランドの画面、あるいはカットの始点と終点がより重要な場合は、H3 の始点・終点フレームモードやマルチモーダル参照モードのほうが適しています。モデルは現在、4〜15 秒の出力、ネイティブ 2K、および 21:9、16:9、4:3、1:1、3:4、9:16 などのアスペクト比に対応しています。具体的に利用可能なオプションは MiniMax H3 モデルページ と API パラメータドキュメント を参照してください。

MiniMax H3 が解決するのに適した課題

画面、動作、音の関係を同時に制御する必要があるショート動画タスクに適しています。たとえば、商品ページ用にカメラワーク付きの紹介動画を作る、ブランド素材の視覚的な雰囲気を引き継ぐ、あるいは参照動画のリズム、参照画像の被写体、参照音声を新しいカットに一緒に取り込む、といった用途です。

EC、広告、製品チームにとって、H3 の価値は単に「画像を動かす」ことではありません。参照素材がある場合のポイントは、変えてはいけない内容を明確に書くことです。たとえば商品の形状、ロゴの位置、被写体のアイデンティティ、カメラアングル、光の当たり方などです。変化させたい内容は個別に記述します。たとえば動作、背景、カメラの寄り、セリフなどです。そうすることで、後の検収時にどの部分がずれたのかがわかります。

1 つのモデル、3 つの一般的なワークフロー

ワークフロー	適したシーン	主な入力
テキストから動画	脚本、絵コンテ、または一言のアイデアから新しい画面を生成する	prompt
始点・終点フレーム制御	カットの開始時と終了時の商品状態やシーンの変化を制御する	first_frame_image、任意で last_frame_image
マルチモーダル参照動画	商品、人物、カットのリズム、または音声素材を同時に参照する	image_urls、video_urls、audio_urls

始点・終点フレーム制御とマルチモーダル参照は異なるモードであり、1 回のリクエストで混在させることはできません。終点フレームを使用する場合は、必ず始点フレームも同時に提供する必要があります。マルチモーダル参照では最大 5 枚の画像、3 本の動画、3 本の音声を渡せます。音声を単独で入力することはできず、少なくとも参照画像または参照動画を同時に提供する必要があります。参照動画と音声は 1 本あたり 2〜15 秒で、合計 15 秒を超えてはいけません。

まずはテキストから動画で最小タスクを通す

以下は 5 秒、16:9 の商品カットの例です。タスクの作成が成功したことはサーバー側がリクエストを受け付けたことだけを意味し、レスポンスの data.taskId を使って以降のステータスを照会します。

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "input": {
      "prompt": "マットな濃紺のコーヒーカップが薄いグレーの石のテーブルに置かれている。カメラはミディアムショットからゆっくり寄り、朝の光が左側から差し込み、カップ本体は動かず、背景はぼけていて、文字はない。",
      "duration": 5,
      "resolution": "2K",
      "aspect_ratio": "16:9",
      "watermark": false
    }
  }'

ローカルでのデバッグには GET /v1/tasks/{taskId} で結果を照会できます。本番環境ではリクエストのトップレベルに callback.url を設定し、自社サービス側で taskId による冪等処理を行うのが適しています。タスクが終了状態になってから status を判定します。success の場合は output[].url をダウンロードし、fail の場合はエラーメッセージに基づいて入力を修正し、同じ無効なリクエストをむやみに再送しないでください。

参照素材を意味のある形で使うには

始点・終点フレームは「カットが A から B へ進む」タスクに適しています。たとえば新製品発表の動画で、明かりの消えた台灯から始まり、暖かい光が机を照らす状態で終わる場合です。このとき始点フレームが開始点を固定し、終点フレームが終着点を固定し、プロンプトは途中で起こる動作、カメラワーク、光の変化だけを説明すればよくなります。

マルチモーダル参照は、継続的なブランドやキャラクターの制御に適しています。商品のメイン画像は image_urls に、カットのリズムの参照は video_urls に、音楽や雰囲気の参照は audio_urls に置けます。プロンプトには各素材の役割を明記する必要があります。たとえば「参照画像のバッグの外観と金属金具の位置を保ち、参照動画の横方向の寄りのリズムを踏襲して、静かな商品紹介動画を生成する」といった具合です。

すべての素材を詰め込まないでください。参照を 1 つ増やすごとに、モデルが理解すべき制約が増えます。まず 1 枚の被写体画像で外観の保持を検証し、その後でカットや音声の参照を追加すると、問題の切り分けが容易になります。

プロンプトに書くべき情報

再利用可能な動画プロンプトは通常 4 つの部分からなります。被写体、動作、カメラ、音声または環境です。被写体では変えてはいけない視覚情報を明確にし、動作では起こる出来事を述べ、カメラではポジションと動きを記述し、音声ではセリフ、環境音、音楽の雰囲気の有無を説明します。

たとえば商品広告を作る場合は、次のように書けます。「参照画像の白いイヤホンケース、オレンジの外殻、NOMA のマークを変えずに保つ。カメラはテーブルのミディアムショットからゆっくり寄り、イヤホンケースが開き、2 つのイヤホンは元の位置にとどまる。窓辺の自然光、低い環境音、ナレーションなし、余分な文字なし。」これは「かっこいいイヤホン広告を作る」とだけ書くより検収が容易です。

H3 を本番ワークフローに組み込む前に

まず 3 つのケースで小規模な検証を行うことをお勧めします。純粋なテキストから動画、始点・終点フレーム制御、マルチモーダル参照動画の 3 つです。それぞれ入力素材、出力時間、ステータス遷移、失敗情報、成果物 URL、最終請求を記録します。各モードが自社製品で安定して動作することを確認してから、バッチ生成に拡張してください。

価格は出力秒数と現在の料金帯に基づいて計算され、ページに固定の単価は記載されていません。送信前に MiniMax H3 リアルタイムモデルページ で現在の価格を確認してください。稼働後はタスク記録とアカウントの請求を基準にしてください。非同期タスク、コールバック、エラー調査の詳細は MiniMax H3 接続チュートリアル を引き続き参照してください。

よくある質問

MiniMax H3 はどのような入力に対応していますか？

テキストのみからの動画生成に加え、始点フレーム、始点・終点フレーム、または参照画像・動画・音声による制御が可能です。始点・終点フレームとマルチモーダル参照のフィールドは混在できません。

MiniMax H3 は音声を生成できますか？

MiniMax H3 はネイティブ音声付きの動画生成に対応しており、マルチモーダル参照モードで音声素材を使うこともできます。音声参照には参照画像または参照動画を併用する必要があります。

1 本の動画は最大どのくらいの長さですか？

現在の出力時間は 4〜15 秒です。長い動画は通常、複数のカットに分けて生成し、自社のワークフローで編集・結合する必要があります。

ポーリングと callback のどちらを使うべきですか？

ローカルでのデバッグや低頻度のタスクではポーリングで構いません。本番環境では callback.url で終了状態の通知を受け取り、コールバック失敗時の補償機構としてタスク詳細の照会を残しておくことをお勧めします。

MiniMax H3 を見る、API パラメータドキュメントを読む、または API Key を取得する。