MiniMax H3 API ガイド：動画生成と参照素材の統合

MiniMax H3 の全モデルを同じ仕様として扱うと、リクエストが失敗しやすくなります。モデル ID によって長さと解像度の検証条件が変わり、入力モードによって開始／終了フレーム、参照画像、動画、音声を同時に送れるかどうかが決まります。

この記事は、2026 年 10 月 22 日時点の ToAPIs フロントエンドに実装されたリクエスト契約に基づいています。上流の性能試験や現在のアカウント価格を示すものではありません。本番リクエストの前に、アカウントで対象モデルが有効か確認してください。

クイックスタート

ToAPIs API の例では、POST /v1/videos/generations で動画生成タスクを送信します。Bearer API Key、有効なモデル ID、プロンプト、長さ、比率を指定します。

curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
    "duration": 5,
    "ratio": "16:9"
  }'

生成は非同期タスクです。アカウント API のレスポンスに含まれるタスク ID を読み取り、アカウント向けドキュメントに記載されたステータス API で確認してください。ドキュメントに明記されていないレスポンス階層を決めつけないでください。

import os
import requests

BASE_URL = "https://api.toapis.com/v1"
headers = {"Authorization": f"Bearer {os.environ['TOAPIS_API_KEY']}"}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json={
        "model": "minimax-h3",
        "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
        "duration": 5,
        "ratio": "16:9",
    },
    timeout=30,
)
response.raise_for_status()
print("Submission response:", response.json())

この例ではタスク ID や動画 URL の場所を推測せず、レスポンスを表示します。レスポンスの解析は、アカウント向け API 仕様に合わせて実装してください。

正確なモデル ID を指定する

フロントエンドは基本モデルとして minimax-h3 と minimax-h3-global を認識し、minimax-h3-max を含む ID も認識します。Turbo のモデル ID は minimax-h3-max-turbo です。モデルカタログに表示された完全な ID を使い、省略形や推測した別名は使わないでください。

現在のフロントエンドが検証する仕様は次のとおりです。

これはフロントエンドの検証条件であり、すべてのアカウントや上流ルートで同じ機能を利用できる保証ではありません。現在のクライアントで 1080P が追加されるのは、正確な ID が minimax-h3-max の場合のみです。Turbo、-global 別名、すべての H3 モデルが 1080P に対応すると推測しないでください。

2 種類の入力モードから選ぶ

H3 フォームには、相互に併用できない 2 つのワークフローがあります。

1. フレーム方式: first_frame_image は最大 1 件、last_frame_image も最大 1 件です。フレームがある場合、クライアントは比率を adaptive にします。
2. 参照素材方式: 開始／終了フレームを送らず、参照画像、動画、音声を指定します。この方式では選択した比率を使います。

開始フレームの例:

{
  "model": "minimax-h3",
  "prompt": "The subject turns toward the camera as the camera gently moves forward",
  "duration": 5,
  "ratio": "16:9",
  "first_frame_image": ["https://example.com/starting-frame.jpg"]
}

参照素材の例:

{
  "model": "minimax-h3",
  "prompt": "Use the supplied references to guide the scene and motion",
  "duration": 5,
  "ratio": "16:9",
  "media_mode": "reference",
  "reference_images": ["https://example.com/character-reference.jpg"],
  "reference_videos": ["https://example.com/motion-reference.mp4"]
}

アップロード素材の値の形式は、ゲートウェイのアップロード手順によって異なります。ここではフィールドを示していますが、すべてのルートが任意の公開 URL を受け付けるという意味ではありません。文書化されたアップロード手順から返された URL または素材 ID を使ってください。

現在のフロントエンド制限は、参照画像最大 9 件、参照動画最大 3 件、参照音声最大 3 件、参照素材合計最大 12 件です。各参照動画は 2～15 秒で、合計時間も 15 秒を超えてはいけません。音声参照には視覚素材が少なくとも 1 件必要です。Turbo は参照素材を受け付けません。

送信前にモード、件数、長さを検証してください。入力モードの混在、件数超過、視覚素材の不足があると、フロントエンドがリクエストを拒否します。

プロンプト、比率、オプション

プロンプトは必須で、現在のフロントエンドでは Unicode 文字数 7,000 文字までです。被写体、場面、動作、見た目の意図を自然な文章で記述してください。上流ドキュメントに特殊構文の定義がない限り、[Pan Left] などは通常のプロンプト文字列として扱います。フロントエンド契約から、それらが H3 のネイティブ命令だとは確認できません。

リクエストビルダーはモデルルートに応じて prompt_optimizer、watermark、seed などのオプションを処理します。すべての上流チャネルで同じフィールドが使えるとは限りません。モデル変更時には、前のモデルから残った非対応フィールドも消してください。

フロントエンドが受け付ける比率は adaptive、21:9、16:9、4:3、1:1、3:4、9:16 です。フレーム入力では adaptive が強制されます。Text-to-Video で adaptive を選ぶと 16:9 に正規化され、参照素材方式では選択した対応比率が維持されます。

比率は画面形状、解像度はモデルルートで選べる出力サイズです。モデルによって値の大文字・小文字も異なります（768p と 768P など）。モデルごとの API 契約にない全体的な変換は避けてください。

ポーリング、エラー、再試行

タスク送信後はタスク ID を保存し、アカウントドキュメントにあるステータス API を確認します。上限付きのバックオフと全体の期限を設定し、タスク失敗とクライアント側の待機タイムアウトを区別します。待機のタイムアウトだけでは上流タスクの失敗を意味しません。課金対象の生成を再送する前に、元のタスクを確認してください。

クライアントでは HTTP ステータスの確認、仕様に沿ったレスポンス解析、文書化された終端状態でのポーリング停止、再試行回数と経過時間の上限設定を行います。ログにリクエスト ID やタスク ID を記録しても、API Key や非公開素材 URL は記録しないでください。

これらは一般的な診断カテゴリであり、ToAPIs のすべてのルートで同じエラーコードが返ることを保証するものではありません。

価格、プライバシー、リリース前確認

価格、稼働率、返金条件、SLA はモデル、ルート、アカウントによって異なる場合があります。この記事では秒単価や稼働率を保証しません。現在のモデルカタログとアカウント価格を確認し、企画書の価格を本番見積もりとして使用しないでください。

参照素材はユーザーデータとして扱います。アップロード前にファイル種別、サイズ、件数を検証し、ユーザーに権利のある素材だけを処理してください。個人素材をデモ用に公開 URL へ置かず、一時的な素材リンクを長期ログへ書き込まないでください。

リリース前には、アカウントで有効な各モデルの正常リクエストをテストし、小数の長さ、未対応解像度、素材数超過、モード混在、Turbo への参照素材を負のテストに含めます。モデル切替時に非対応値が消えることも確認します。応答フィールドとタスク状態はローカルフィクスチャまたは承認済みテストアカウントで確認してください。この記事では本番 API を呼び出していません。

関連リンク

• 動画モデルを確認
• Playground で MiniMax H3 を開く
• Playground で MiniMax H3 Max Turbo を開く