Hailuo API の使い方：MiniMax H3 を Python で呼び出し、3 つの動画モードを実測

Hailuo API は MiniMax の動画 API で、現行モデルは MiniMax H3（MiniMax-H3）、Hailuo 01 と 02 の次の世代です。呼び出しはすべて非同期で、タスクを作成し、ポーリングし、MP4 をダウンロードします。2026 年 10 月 26 日、5 秒 768P の動画は 3 つのモードすべてで 35 秒から 42 秒で返ってきて、いずれも音声付きでした。

先に結論

• モデル： MiniMax の API では MiniMax-H3（2026 年 7 月 31 日発表、リリースノート）。OmniaKey では minimax-h3 で、3 種類のタスクを 1 つの id で扱えます（動画ドキュメント）。
• 設定するもの： resolution（必須）に "768P" か "2K"、duration に 4 から 15 の整数秒、aspect_ratio（動画ドキュメント）。
• 料金： 768P で 1 秒 $0.08、5 秒で $0.40、2K で 1 秒 $0.13。MiniMax の定価です（料金、2026 年 10 月 26 日時点）。OmniaKey の料金は モデルページ にあります。
• 所要時間と音声： 1 本あたり 35 秒から 42 秒、いずれもステレオ音声付き。V2 の作成リファレンスに音声を切るスイッチはありません（作成リファレンス）。

公式の Hailuo API はある？

あります。MiniMax が platform.minimax.io で提供していて、現行モデルは MiniMax H3、id は MiniMax-H3 です（モデル一覧、2026 年 10 月 26 日時点）。

MiniMax の発表では、H3 は Hailuo 01 と Hailuo 02 の次の世代とされています（発表）。旧モデルも API に残っていて、MiniMax-Hailuo-2.3 と MiniMax-Hailuo-02 で呼べます（V1 リファレンス）。

名前はページによって変わります。MiniMax のドキュメントは「MiniMax H3」、API のモデル説明は「Hailuo-03」（作成リファレンス）、発表で試用を勧めている Hailuo AI アプリは「Hailuo 3.0」と書いています（アプリ）。「Hailuo 3」は公式名ではありません。

キーは Account > API Keys で作成し、課金は従量制です（API FAQ）。MiniMax の動画パッケージが対象にしているのは旧モデルで、H3 は含まれません（料金）。

MiniMax は H3 を 4 種類そろえています（作成リファレンス）。

MiniMax の API では、呼び出しは 3 ステップです（動画ガイド）。

• POST https://api.minimax.io/v2/video_generation が task_id を返します（作成リファレンス）。
• GET /v2/query/video_generation/{task_id} を succeeded になるまでポーリングし、content.url をダウンロードします（クエリリファレンス）。
• 問い合わせできるのは直近 7 日間のタスクだけで、ダウンロード URL がどのくらい有効かは MiniMax が公開していません（クエリリファレンス）。

V1（Hailuo 2.3 と 02）はタスク ID をパスではなく ?task_id= クエリパラメータで渡すので、2 つの流れは分けて考えます（V1 リファレンス）。

OmniaKey は MiniMax H3 の API アクセスを提供しているので、この例はその経路で実行しました。流れは同じです。POST https://api.omniakey.com/v1/media/tasks を Idempotency-Key ヘッダー付きで呼ぶと 202 と id が返り、GET /v1/media/tasks/{id} でポーリングします（メディア概要）。同じ流れは Grok Imagine Video API ガイド でも使っています。以下の価格はすべて MiniMax の定価です。

どのパラメータを設定できる？

• resolution は必須です。1080P と 4K は 400 model_price_error で失敗し（動画ドキュメント）、V2 に H3 向けの 1080P はありません（作成リファレンス）。3 つのモードはすべて 768P で実行し、2K は試していません。
• duration は 4 から 15 の整数秒です（動画ドキュメント）。MiniMax-H3-Max は 5 秒からで、4 を渡すと拒否されます（作成リファレンス）。
• aspect_ratio は adaptive、16:9、9:16、1:1、4:3、3:4、21:9 を受け付けます（動画ドキュメント）。MiniMax の API では、テキストから動画は固定の比率が必要で、画像から動画は画像の形に従います（作成リファレンス）。画像から動画では比率を指定せず、動画は元画像の形 1376×768 を保ちました。
• input.media[] は、画像から動画では first_frame と任意の last_frame、参照から動画では reference_image、reference_video、reference_audio を受け付けます。2 種類は混在できず、音声参照には画像か動画の参照を添えます（動画ドキュメント）。各要素は type と url で、公開 HTTPS リンクか data URI を指定します。OmniaKey はリクエスト全体を Base64 込みで 1 MiB までに制限しているので（メディア概要）、スクリプトは 1024 ピクセルの JPEG を送ります。
• プロンプトは input.prompt に書きます（動画ドキュメント）。7,000 文字までです（動画ガイド）。欲しい音もそこに書きます。

Python から Hailuo API を呼ぶには？

Python 3 と requests が必要です。キーは環境変数に入れます。

pip install requests
export OMNIAKEY_API_KEY="your-key"
python hailuo_h3.py t2v   # or i2v (needs bicycle.jpg) or r2v (needs robot.jpg)

引数は t2v、i2v、r2v の 3 つだけです。画像が要る回は、同じフォルダーの bicycle.jpg か robot.jpg を読みます。

実行したスクリプトはこちらで、一字も変えていません。

import base64
import os
import sys
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

DRUMMER = (
    "A street drummer plays a fast rhythm on upturned plastic buckets on a rainy city sidewalk "
    "at night. Neon signs reflect in the puddles and a few people with umbrellas walk past "
    "behind him. The camera slowly pushes in from a medium shot to a close-up of his hands and "
    "drumsticks. Realistic, handheld documentary look, with the sound of rain and drumming."
)
BICYCLE = (
    "A gentle breeze moves the daisies in the basket and a few petals drift down to the "
    "cobblestones. The camera slowly pushes in toward the basket. The bicycle and the wall "
    "stay exactly as they are."
)
ROBOT = (
    "The small orange robot from the reference image waters potted plants on a sunny "
    "apartment balcony with a red watering can. Medium shot, slow sideways camera move, "
    "city rooftops in the background."
)


def data_uri(path):
    # A local JPEG sent inline. The whole request must stay under 1 MiB, so keep it small.
    with open(path, "rb") as f:
        return "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()


def make_video(operation, prompt, parameters, media, out):
    task_input = {"prompt": prompt}
    if media:
        task_input["media"] = media

    # 1. Create the task. Reuse the same Idempotency-Key only when retrying this exact request.
    resp = requests.post(
        API,
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={
            "model": "minimax-h3",
            "type": "video",
            "operation": operation,
            "input": task_input,
            "parameters": parameters,
        },
        timeout=60,
    )
    resp.raise_for_status()
    task = resp.json()
    print(operation, "task:", task["id"])

    # 2. Poll the same task. Slow is not failed: never resubmit, keep polling this id.
    deadline = time.time() + 15 * 60
    while task["status"] in ("queued", "processing"):
        if time.time() > deadline:
            raise SystemExit(f"still {task['status']}: poll {task['id']} again later")
        time.sleep(5)
        task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] != "succeeded":
        raise SystemExit(f"{operation} ended {task['status']}: {task.get('error')}")

    # 3. Download the clip now: the signed URL lasts about an hour.
    asset = task["assets"][0]
    with open(out, "wb") as f:
        f.write(requests.get(asset["url"], timeout=120).content)
    print("saved", out, asset["byte_size"], "bytes")


mode = sys.argv[1] if len(sys.argv) > 1 else "t2v"
if mode == "t2v":
    make_video(
        "text_to_video", DRUMMER,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        None, "drummer.mp4",
    )
elif mode == "i2v":
    make_video(
        "image_to_video", BICYCLE,
        {"resolution": "768P", "duration": 5},
        [{"type": "first_frame", "url": data_uri("bicycle.jpg")}], "bicycle.mp4",
    )
elif mode == "r2v":
    make_video(
        "reference_to_video", ROBOT,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        [{"type": "reference_image", "url": data_uri("robot.jpg")}], "robot.mp4",
    )

2026 年 10 月 27 日の出力です。

$ python hailuo_h3.py t2v
text_to_video task: task_V5TXAJG7n3ny42imJNqgTXRL4L8PGStd
saved drummer.mp4 4612510 bytes
$ python hailuo_h3.py i2v
image_to_video task: task_c4m3wHmF79Cmq7ZhDrTnCyt8SmIaW1ls
saved bicycle.mp4 4705286 bytes
$ python hailuo_h3.py r2v
reference_to_video task: task_dqx1TYA7u0znN5PFTl9tbfdWgtbBUbKd
saved robot.mp4 5630121 bytes

各回とも、開始から保存まで 47 秒から 60 秒でした。

タスク ID は残しておきます。遅いタスクは失敗ではないので、再送信せず同じ ID をポーリングし続けます（メディア概要）。署名付きダウンロード URL は約 1 時間、タスク記録は 24 時間有効なので、すぐ保存するか、ポーリングし直して新しい URL を取ります。ダウンロード自体に API キーは要りません。

3 つのモードで返ってきたもの

3 本の動画は、2026 年 10 月 26 日の 3 つのタスクから、スクリプトと同じリクエストボディで生成しました。

どの動画も MP4、H.264、24 fps、5.17 秒で、32 kHz のステレオ AAC 音声が付いていました。usage は output_seconds: 5 でした。

テキストから動画：街のドラマー

プロンプトはスクリプトの DRUMMER です。

見えたこと：

• 夜の濡れた歩道に赤と青のネオンが映り、路上駐車の車があり、黒いフード付きジャケットのドラマーが逆さにした青いバケツに向かってかがんでいます。フードは最後まで顔を隠していました。
• カメラは引きの画から、手元、動くスティック、バケツの天面のアップへ寄っていきます。背後では傘を差した人が通り過ぎます。
• ネオン看板の文字は意味のある単語になっていません。ドラムの音は終盤に向けて強くなりますが、雨音は音声では判別できません。

変えるなら：顔が見たいときは「hood down, face visible」を足します。雨音を聞かせたいときは、雨だけの音の一文を書きます。

画像から動画：最初のフレームはそのまま

最初のフレームは Nano Banana 2.1 で作った静止画で、プロンプトは BICYCLE、動きだけを書いています。

見えたこと：

• 最初のフレームは元画像と同じです。赤い自転車、黄色い漆喰の壁、シャッター、鉢植え、石畳がそろっています。
• カメラが寄っていき、白いデイジーのバスケットが画面いっぱいになります。自転車と壁は最後まで形を保ちます。
• 確認したコマでは花びらが落ちる様子は見えませんでした。音声はゆっくりのピアノ独奏で、プロンプトには音も音楽も書いていません。

変えるなら：見た目は静止画で決まるので、動きと音だけを書きます。そして、動画に欲しい形で静止画を作っておきます。

参照から動画：1 枚の画像がキャラクターを保つ

参照は Nano Banana 2.1 で作った小さなオレンジ色のロボットの画像 1 枚で、プロンプトは ROBOT です。

見えたこと：

• 同じロボットです。オレンジ色の丸い体、丸い青いガラスの目、先に玉の付いた短いアンテナ、頭の横の円盤。舞台は花やハーブの鉢が並ぶ日当たりのよいバルコニーになりました。
• 赤いじょうろから水を注ぎ、水流は 1 秒あたりから見え、カメラは少し横に流れます。
• 音声は流れる水と跳ねる水の音で、水流が出る直前に始まり、音楽はありません。

変えるなら：キャラクターに直すところはありませんでした。複数の動画で同じキャラクターを保つには、毎回同じ参照画像を使います。

音声：自分で書くか、H3 に選ばせるか

プロンプトに音の指定がないとき、H3 が自分で選びました。ロボットには水やりに合う水音、自転車にはピアノです。必要な音はプロンプトに書きます。V2 の作成リファレンスに音を消すスイッチはないので（作成リファレンス）、無音の動画が欲しいときは後から音声トラックを外します。

ffmpeg -i drummer.mp4 -an -c copy drummer-silent.mp4

これで H.264 の映像だけのコピーができます。長さは 5.17 秒のままで、再エンコードはありません。

どんなエラーが出る？

エラーは OmniaKey のタスク API から、MiniMax を直接呼ぶときは MiniMax 側から返ります。

• 400 missing_idempotency_key：Idempotency-Key ヘッダーがない。付ける。
• 409 idempotency_key_reused：同じキーで別のボディ。タスクごとに新しいキー。
• 400 model_price_error：1080P か 4K。768P か 2K にする。
• 400 invalid_request：ボディかパラメータが不正。パラメータを確認。
• 403 model_not_allowed：キーにこのモデルの権限がない。キーの権限を確認。
• 503 no_available_channel：モデルが一時的に使えない。後で再試行。
• provider_submit_uncertain：送信の段階で拒否された。input.prompt を使い、素材を確認。
• タスク failed：生成に失敗。error を読む。

失敗したタスクとキャンセルしたタスクは返金されます（メディア概要）。MiniMax の API を直接呼ぶときはこうです（エラーコード、2026 年 10 月 26 日時点）。

• MiniMax は各コードに対応する HTTP ステータスも返します。たとえば 1004 なら 401、2013 なら 400 です（作成リファレンス）。
• V2 の H3 は 1 分あたり 300 リクエスト、同時 30 タスクまでです（レート制限）。

Hailuo API はいくらかかる？

MiniMax は H3 を出力動画の秒数で課金します。単価はモデルと解像度で変わります（料金ページ、2026 年 10 月 26 日時点）。

この単価だと、768P の 5 秒が $0.40、2K の 10 秒が $1.30、2K の 15 秒が $1.95 です。

• 入力画像はタスクごとに最初の 5 枚まで無料（Max は 2 枚）で、それ以降は H3 で 1 枚 $0.04、音声入力は無料です。入力動画は秒単位で課金され、Max では入力 1 秒（768P で $0.143）が出力 1 秒より高くなります。同じモデルと同じ解像度なら、3 種類のタスクは同じ料金です。
• H3 は従量課金だけで、MiniMax の動画パッケージには含まれません。Hailuo AI アプリのプランにある秒あたりの数字はアプリのクレジットで、API の価格ではありません（アプリ）。
• MiniMax の中国版プラットフォームは人民元の独自の価格表を持っているので、片方から他方へ換算はしません（中国版の料金、2026 年 10 月 26 日時点）。
• OmniaKey では、動画タスクの作成時に出力秒数で課金され、失敗またはキャンセルしたタスクは返金されます（メディア概要）。

OmniaKey の現在の料金は MiniMax H3 モデルページ に、リクエストの形は 動画 API ドキュメント にあります。

よくある質問

Hailuo API は無料？

MiniMax の API では無料ではありません。料金ページ、クイックスタート、FAQ のどこにも H3 の無料トライアルやクレジットはありません（2026 年 10 月 26 日時点）。無料なのはタスクごとの最初の 5 枚の入力画像と音声入力だけで（料金）、Hailuo AI アプリのクレジットは API のクレジットとしては使えません。

Hailuo 2.3 と MiniMax H3 の違いは？

Hailuo 2.3 は V1 で、6 秒か 10 秒、最大 1080P、動画 1 本ごとの課金です。MiniMax の定価は 768P の 6 秒で $0.28（料金、V1 リファレンス）。H3 は V2 で、4 から 15 秒、768P か 2K、秒単位の課金、ステレオ音声付きです（作成リファレンス、モデル一覧）。どちらも今も提供されています（モデル FAQ）。

MiniMax H3 Max とは？

MiniMax と fal.ai の共同リリースで、fal.ai が H3 を速度向けに追加学習したモデルです（動画ガイド）。480P か 768P で 5 から 15 秒の動画を作り、extra.prompt_expansion_mode は disabled、balanced（既定）、quality を受け付けます（作成リファレンス）。参照素材に対応するかどうかは MiniMax のページで説明が分かれていて、動画ガイドとモデル FAQ はテキストから動画と画像から動画だけを挙げ、作成リファレンスと料金ページは参照から動画も挙げています。

MiniMax H3 は自分で動かせる？

動かせますが、地域によって制限があります。重みは Hugging Face（MiniMaxAI/MiniMax-H3）と GitHub（MiniMax-AI/MiniMax-H3）にあり、ライセンスは MiniMax H3 Community License Agreement という独自ライセンスです（Hugging Face、GitHub）。2026 年 8 月 26 日に確認した版のライセンスでは、米国、EU、英国、韓国が除外地域で、別途ライセンスが必要です（ローカルデプロイガイド）。

更新履歴

2026 年 10 月 27 日：初版。動画は 2026 年 10 月 26 日に生成しました。