MiniMax H3 Max API の使い方：テキストや画像から動画を生成する方法

MiniMax H3 Max は HiAPI 上で 2 つのモデル名に分かれています。テキストto動画は minimax-h3-max/text-to-video、画像to動画は minimax-h3-max/image-to-video で、0.92～15 秒の動画を生成します。480P は 1 秒あたり $0.072、768P は 1 秒あたり $0.115、1080P は 1 秒あたり $0.229 で、リクエストした秒数に応じて課金されます。まずは下記の紙のボートのプロンプトで 5 秒の横長ショート動画を生成しましょう。768P の予算は $0.575 です。API を組み込む際は、タスクを 1 回送信し、返却された taskId で動画を取得します。

MiniMax H3 Max は HiAPI で公開中です。このプロンプトで生成 →。プロンプトは自動で入力されるので、続けて 5 秒、768P、16:9 を手動で選択してください。

最初の一本：雨上がりの紙のボート

After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.

このプロンプトで生成 →

このプロンプトは動作とカメラワークを分けて記述しています。紙のボートは水に漂い、ローポジションのカメラが滑らかに並走し、音は遠くの鳥のさえずりで表現します。紙のボートを自分の被写体に置き換える際は、まず動作を 1 つとカメラワークを 1 つに絞ると、どこを調整すべきかが見えやすくなります。

オンラインでの試用と API 連携、どちらを選ぶ？

まず効果を確認したい場合は、テキストto動画モデルページを開き、プロンプトをコピーして長さと解像度を選び、生成を送信します。開始画面が既にある場合は画像to動画モデルページに切り替えて先頭フレーム画像をアップロードします。アプリへの組み込みを行う場合は、まず API Key ページ でキーを取得し、サーバー側のリクエストでタスクを作成して taskId を保存し、タスク成功後に動画の URL を読み取ります。

解像度は明示的に指定することをおすすめします。5 秒の場合、480P は $0.36、768P は $0.575、1080P は $1.145 です。まず低解像度で動作を確認し、納品要件に応じてグレードを選びましょう。詳しい予算は H3 と H3 Max の価格表をご覧ください。

cURL：タスクを作成し、結果を照会する

API Key をローカルの環境変数 HIAPI_API_KEY に設定したうえで、次のリクエストを実行します。

curl --fail-with-body --connect-timeout 10 --max-time 60 -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}'

POST がタイムアウトした場合、接続が中断された場合、または返却内容から作成結果を確認できない場合、送信状態は不明です。まずタスク記録を照会し、POST を直接再実行しないでください。レスポンスの code=200、data がオブジェクトであること、data.taskId が空でないことを確認したら、ID を保存して照会 URL の YOUR_TASK_ID を置き換えます。

curl --fail-with-body --connect-timeout 10 --max-time 60 "https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

待機中のタスクは同じ ID で照会を続けます。data.status が success の場合は、data.output から動画エントリの url を読み取ります。fail の場合はタスクのエラー情報を確認します。入力や認証のエラーの場合は該当する問題を先に修正し、タスク ID が既にある場合はそのタスクの照会を続けます。

Python：1 回だけ送信し、同じタスクを待つ

以下では Python 標準ライブラリを使用します。POST は 1 回だけ行い、レスポンスを検証します。送信結果が不明な場合は停止し、タスク記録を確認するよう促します。照会が一時的に失敗した場合はタスク ID を保持したまま GET を続け、600 秒がこの例の待機上限です。

import json
import os
import time
import urllib.error
import urllib.request

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer " + os.environ["HIAPI_API_KEY"],
    "Content-Type": "application/json",
}


def request(method, url, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data=data, headers=HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=30) as response:
        result = json.load(response)
    if not isinstance(result, dict) or result.get("code") != 200:
        raise ValueError(f"Unexpected API response: {result!r}")
    if not isinstance(result.get("data"), dict):
        raise ValueError("Missing data object")
    return result["data"]


payload = {
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}
try:
    created = request("POST", BASE, payload)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing taskId")
except (OSError, ValueError) as exc:
    raise SystemExit(
        f"Submission outcome is unconfirmed: {exc}. "
        "Check task history before another POST; do not blindly resubmit."
    )

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        task = request("GET", f"{BASE}/{task_id}")
    except urllib.error.HTTPError as exc:
        if exc.code in (400, 401, 403, 404):
            raise SystemExit(
                f"Query rejected ({exc.code}). Correct URL/auth, then GET existing task {task_id}."
            )
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    except (OSError, ValueError) as exc:
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    status = task.get("status")
    if status not in ("queued", "handling", "archiving", "success", "fail"):
        raise RuntimeError(f"Unexpected task status {status!r}; keep task ID {task_id}")
    if status == "success":
        output = task.get("output")
        if not isinstance(output, list):
            raise RuntimeError(f"Invalid output; keep task ID {task_id}")
        videos = [item["url"] for item in output
                  if isinstance(item, dict) and item.get("type") == "video"
                  and isinstance(item.get("url"), str) and item["url"]]
        if not videos:
            raise RuntimeError(f"No video URL; keep task ID {task_id}")
        print(videos[0])
        break
    if status == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task!r}")
    time.sleep(5)
else:
    raise TimeoutError(f"Keep querying existing task {task_id}; do not POST again")

画像で先頭フレームまたは末尾フレームを制御する

自分の商品画像から動画を始めたい場合は、モデル名を minimax-h3-max/image-to-video に変更し、input に first_frame_image を追加します。終わりを指定したい場合は last_frame_image を追加します。末尾フレームのみを渡すことも、先頭と末尾の両方を同時に渡すこともできます。画像to動画には aspect_ratio フィールドはなく、画面比率は画像に従います。

フィールド	使い方
prompt	必須。最大 50000 文字で、動作・カメラワーク・音を記述
duration	0.92～15 秒。小数可。デフォルトは 5 秒
resolution	480P、768P、または 1080P。デフォルトは 768P
aspect_ratio	テキストto動画のみ：21:9、16:9、4:3、1:1、3:4、9:16。デフォルトは 16:9
first_frame_image	画像to動画：先頭フレームの公開画像 URL
last_frame_image	画像to動画：末尾フレームの公開画像 URL
target_audio_url	任意。自分の音声で音声トラックを置き換え。最低 2 秒
prompt_expansion_mode	任意。disabled / balanced（デフォルト）/ quality

以下は先頭・末尾フレームの完全なリクエストボディです。画像 URL はご自身の公開アクセス可能なアドレスのプレースホルダーで、画像が開始と終了の構図を担います。

{
  "model": "minimax-h3-max/image-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "first_frame_image": "https://your-domain.com/images/paperboat-first.jpg",
    "last_frame_image": "https://your-domain.com/images/paperboat-last.jpg"
  }
}

末尾フレームのみを制御したい場合は、first_frame_image を削除し last_frame_image を残します。カメラの動きだけをプロンプトに書き、被写体と初期構図は画像に担わせます。マルチショットはプロンプトに各切り替えを明記できます。リクエストのフィールドはこの表のとおりにし、camera_angle、mode、watermark は追加しないでください。

縦長のショート動画にしたい場合、テキストto動画では "aspect_ratio": "9:16" を直接指定します。画像to動画では縦版の先頭フレーム画像を用意し、画面比率は画像に従います。

アプリに組み込む際は、コールバックをリクエストのトップレベルに置く

作成リクエストのトップレベルに、model、input と並べて任意のコールバックを追加します。

{
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

この部分を完全なリクエストに組み込みます。受信側では taskId で重複排除し、成功と失敗を分けて処理します。漏れた通知はタスク照会で補います。タスク ID を取得したら再送信しないでください。HTTP エラーが発生した場合はまずレスポンス内容を読み、認証の問題かパラメータの問題かを切り分けます。

連携後に確認する 4 項目

1. 空でない data.taskId を保存し、照会で異常が発生しても引き続き使用する。
2. 終態が success または fail であることを確認し、待機上限をモデルの処理時間とみなさない。
3. 成功したタスクの data.output で type=video の動画 URL を探す。
4. 生成物をダウンロードし、実際のサイズ・長さ・映像が納品要件を満たすか確認する。

よくある質問

H3 Max は参照動画や音声を使えますか？ H3 Max は target_audio_url で音声トラックを置き換えますが、参照動画には対応していません。画像・動画・音声のマルチモーダル参照が必要な場合は MiniMax H3 を選んでください。

H3 と比べて Max は高いですか？ H3 の 2K は 1 秒あたり $0.1189、Max は 768P が 1 秒あたり $0.115、1080P が 1 秒あたり $0.229 です。まず必要な解像度と参照素材でモデルを選び、その後で長さから予算を計算しましょう。

縦長のショート動画はどう始めればよいですか？ テキストto動画では "aspect_ratio": "9:16" を指定します。画像to動画では縦版の先頭フレーム画像を用意し、画面比率は画像に従います。

紙のボートのプロンプトをコピーしてこのプロンプトで生成 →し、まず 5 秒のショート動画を作りましょう。動作やカメラワークの書き方の詳細は4 本の実動画と完全なプロンプト、フィールドの詳細はテキストto動画パラメータドキュメントと画像to動画パラメータドキュメントをご覧ください。