MiniMax Hailuo 2.3 API 連携：複雑な人体モーションを動画 API で生成する

対象モデル: MiniMax-Hailuo-2.3
推論エンドポイント: https://api.toapis.com/v1/videos/generations
関連記事: MiniMax H3 API ガイド · H3 のカメラワーク・プロンプト · 自動 R2V パイプライン

1. クイックスタートと性能概要 (TL;DR)

• 目的: ToAPIs の動画生成エンドポイントで、テキストから、またはファーストフレーム付きの画像から、キャラクターおよび人体モーションのクリップを投入します。
• 契約: MiniMax-Hailuo-2.3 は整数の尺 6 秒または 10 秒と、解像度 768P または 1080P を受け付けます。1080P は 6 秒のみです。現行の API リファレンスではプロンプトは 2,000 文字が上限です。
• ID: テキストおよび画像からの生成にはカタログ文字列 MiniMax-Hailuo-2.3 を使います。MiniMax-Hailuo-2.3-Fast は 画像から動画のみで、ファーストフレーム URL が必須です。どちらの ID も minimax-h3 とは互換ではありません。
• カメラ表現: ToAPIs の Hailuo 2.3 リファレンスには [Push in] や [Pan left, Pedestal up] のようなブラケット指示が文書化されています。下表は現行ドキュメントの語彙です。ショット文法をハードコードする前に、公開中のドキュメントで再確認してください。
• プロトコル: Bearer REST。送信レスポンスのタスク id を保存し、期限内に GET /v1/videos/generations/{task_id}（または GET /v1/tasks/{task_id}）をポーリングします。クライアント側のタイムアウトは、上流タスクの失敗を意味しません。

2. 複雑な人体モーションのプロンプトパターン

ToAPIs の公開カタログは、MiniMax Hailuo 2.3 を表現力のある物語やキャラクタークリップ向けの、キャラクターの動き・表情・スタイルの動画モデルとして位置づけています。これは製品上の説明であり、「肢体が絶対に崩れない」という独立ベンチマークではありません。本番では、一つの被写体と一つの主動作を力学的に書き、テイクを目視で確認してください。

役に立つ人体モーションのプロンプトは、スタイルの前に身体の力学を書きます。誰が動くか、どの肢が先行するか、重心がどう移るか、動作の始まりと終わりです。尺や解像度を A/B するときは、この中核を固定しておかないと、文言の差をモデル差と取り違えやすくなります。

ToAPIs Hailuo 2.3 API リファレンスは、次のカメラ指示をプロンプト文字列の中に置きます。独立したリクエストフィールドではありません。フロントエンドの契約も prompt をテキストとして検証します。同時の動きは一つの括弧に最大 3 指示まで、順序のある動きは文中に並べて書いてください。

図 1: 静止ポーズをファーストフレーム入力として扱い、続く動作をプロンプトに書いたうえで、ToAPIs ゲートウェイへ生成リクエストを一度だけ送ります。

検証しやすい短いテンプレート:

SUBJECT and PRIMARY ACTION (lead limb, weight shift, follow-through), ENVIRONMENT, [CAMERA], STYLE NOTES

例: A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs.

画像から動画にする場合は、公開到達可能なファーストフレーム URL を image_urls に 1 件入れます。画像が開始フレームで、プロンプトがそれに続く動きを説明します。現行ドキュメントの画像制限は、JPG / JPEG / PNG / WebP、20 MB 未満、短辺が 300 px 超、アスペクト比が 2:5 から 5:2 です。image_urls に base64 を入れず、ローカルファイルは先にアップロードしてください。

MiniMax-Hailuo-2.3-Fast はテキストからの生成を受け付けません。ファーストフレーム URL が必須です。Hailuo 2.3 には ラストフレームフィールドが文書化されていません。先頭から末尾への補間は MiniMax-Hailuo-02 の契約であり、この ID のものではありません。H3 の ratio や reference_videos をそのまま Hailuo 2.3 に載せないでください。

Playground の選択肢は小文字の 768p / 1080p を出すことがあります。現行の API 例は 768P と 1080P です。バッチを自動化する前に、アカウントが受け付ける値を確認してください。同じカメラの文言は MiniMax H3 でもプロンプトとして使えますが、尺・解像度・メディアモードの契約は別です。ID を切り替える前に、そのガイドを読み直してください。

3. 本番実装: cURL と Python

ステップ 1: cURL で投入

curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs",
    "duration": 6,
    "resolution": "768P"
  }'

ステップ 2: Python ヘルパーとポーリング

公式ドキュメントが現在示している公開オリジンは https://toapis.com です（中国本土では https://toapis.cn）。本シリーズの他ガイドは https://api.toapis.com を使います。ベース URL は一つに揃えてください。次の例は、文書化されたタスク照会パスと completed / failed ステータスに従います。出荷前に、アカウントの API リファレンスで id、result.data[0].url、レスポンスの形を確認してください。

import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def dispatch_motion_clip(
    prompt: str,
    duration: int = 6,
    resolution: str = "768P",
    image_url: str | None = None,
    model: str = "MiniMax-Hailuo-2.3",
) -> str:
    if resolution == "1080P" and duration != 6:
        raise ValueError("1080P currently supports a 6-second duration only")
    payload = {
        "model": model,
        "prompt": prompt,
        "duration": duration,
        "resolution": resolution,
        "metadata": {"prompt_optimizer": True, "aigc_watermark": False},
    }
    if image_url:
        payload["image_urls"] = [image_url]
    elif model == "MiniMax-Hailuo-2.3-Fast":
        raise ValueError("MiniMax-Hailuo-2.3-Fast requires a first-frame image_urls value")
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("id") or data.get("task_id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_task(task_id: str, deadline_s: int = 300) -> str:
    poll_url = f"{BASE}/v1/videos/generations/{task_id}"
    interval = 5.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        if poll.status_code == 429:
            retry_after = poll.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else min(interval * 2, 30))
            continue
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status == "completed":
            return data["result"]["data"][0]["url"]
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 10.0)
    raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")


if __name__ == "__main__":
    prompt = (
        "A contemporary dancer in a black practice leotard plants the left foot, "
        "then uncoils a slow 360-degree turn with the right arm leading and the "
        "torso stacked over the standing leg, warehouse skylight, [Tracking shot], "
        "photorealistic, no morphing limbs"
    )
    task_id = dispatch_motion_clip(prompt)
    print("Task:", task_id)
    print("Video:", poll_task(task_id))

プロンプトテンプレートの版とタスク記録を一緒に残すと、モデル変更と文言変更を切り分けできます。ファーストフレームジョブでは dispatch_motion_clip に image_url= を渡します。Fast SKU ではこの引数が必須です。

Hailuo 2.3 の基本尺は 6 秒または 10 秒です。1080P と duration: 10 は一緒に送らないでください。4–15 秒の連続尺、参照メディア、ラストフレームが必要なら別契約です。H3 API ガイド と R2V パイプライン を参照してください。

4. エラー処理とステータスマトリクス

次の分類は切り分けの出発点であり、ToAPIs の正確なエラーコードを保証するものではありません。HTTP 照会が成功しても、タスクの status は必ず読んでください。

$\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)$

5. 料金と FinOps ROI

$\text{Estimated cost} = \text{successful billable jobs} \times \text{current account rate for that model, duration, and resolution}$

• 企画ドラフトの単価を再利用しないでください。 秒単価や本数単価、課金単位、失敗タスクの扱い切は、モデル・解像度・尺・経路・アカウントで変わります。ToAPIs 料金ページの公式ベンダー参考行は表示用であり、アカウント請求額と一致するとは限りません。ショットリストを見積もる前に、現行カタログとアカウント見積を読んでください。
• Fast は別 SKU であり、同じ ID の無料な速度スイッチではありません。MiniMax-Hailuo-2.3-Fast は画像から動画のみと文書化されています。料金は別に確認してください。
• コストはプロンプト層で抑える: まず 768P と 6 秒で試し、版管理したテンプレートを使い、一度に一つの変数だけ変え、クライアントタイムアウトのあとは状態確認なしに再投入しない。
• 公式ベンダー契約には年次コミット、座席、前払い下限が付くことがあります。ToAPIs の課金は通常従量制です。有効な条件はアカウントで確認してください。

6. よくある質問

構造化 FAQ は frontmatter を参照してください。要約: リクエストのモデル文字列は MiniMax-Hailuo-2.3 であり、ハイフン付きスラッグでも H3 の ID でもない。1080P は 6 秒のみ。Fast にはファーストフレーム URL が必要で、テキストからの生成はできない。文書化されたカメラ指示はプロンプト内にあり、独立フィールドではない。Hailuo 2.3 にラストフレーム入力はない。

7. アクションチェックリスト

• ToAPIs 開発者ポータル でキーを作成する。
• MiniMax-Hailuo-2.3、resolution: "768P"、6 秒で上記の cURL をスモークテストする。
• アカウントが 768P と 768p のどちらを期待するかを確認し、GET /v1/videos/generations/{id} を期限付きでポーリングする。
• 次に: 別の尺やメディア契約が必要なら H3 カメラワークガイド。カタログの現状は Hailuo 2.3 モデルガイド。