MiniMax H3 Python API: セットアップガイドと非同期ワークフロー

MiniMax H3 は、自然言語プロンプトと対応する参照素材を受け付けるマルチモーダル AI 動画生成モデルです。Python API は、動画ジョブの送信、レンダリング進行状況の監視、そして生成プロセス全体でリクエストを開き続けなくても完了済みファイルを取得したいアプリケーション向けに設計されています。

標準的なワークフローは非同期です。アプリケーションは動画生成リクエストを送信し、task_id を受け取り、一定間隔でタスク状態を確認し、タスクが Success に到達した後に出力を取得します。この構成は、Web アプリケーション、社内ツール、コンテンツパイプライン、バッチ生成システムに適しています。

MiniMax H3 の公式ワークフローは、時間と解像度を設定できる短尺動画生成をサポートしています。選択したエンドポイントやアカウント設定によっては、利用可能な制御項目にテキストプロンプト、画像参照、動画参照、音声指示、アスペクト比、出力解像度が含まれる場合があります。

統合の実装を始める前に、Python 環境を準備し、HTTP クライアントをインストールし、MiniMax API キーをアプリケーションコードの外に保存してください。この方法により、リポジトリ、ログ、スクリーンショット、クライアント側バンドルへのキーの意図しない露出を抑えられます。

以下の例では Python と requests パッケージを使用します。アプリケーションで使う環境にインストールしてください。

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install requests

スクリプトを実行する前に、API キーを環境変数として設定します。

export MINIMAX_API_KEY="YOUR_API_KEY"

Windows PowerShell では次を使用します。

$env:MINIMAX_API_KEY="YOUR_API_KEY"

基本的な MiniMax H3 Python API 統合では、次の 4 段階の手順に従ってください。重要な設計原則は、タスク送信とタスク監視を分離することです。本番サービスは、同じ生成を再送信せずにポーリングを再開できる必要があります。

簡潔な Python 実装は次のようになります。

import os
import time
import requests

API_KEY = os.environ["MINIMAX_API_KEY"]
BASE_URL = "https://api.minimax.io/v1"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "MiniMax-H3",
    "prompt": (
        "A premium perfume bottle rotating on black glass, "
        "dramatic studio lighting, synchronized ambient sound."
    ),
    "duration": 6,
    "resolution": "768P",
}

create_response = requests.post(
    f"{BASE_URL}/video_generation",
    headers=HEADERS,
    json=payload,
    timeout=60,
)
create_response.raise_for_status()

task_id = create_response.json()["task_id"]
print("Created task:", task_id)

while True:
    query_response = requests.get(
        f"{BASE_URL}/query/video_generation",
        headers=HEADERS,
        params={"task_id": task_id},
        timeout=30,
    )
    query_response.raise_for_status()

    task = query_response.json()
    status = task.get("status")
    print("Current status:", status)

    if status == "Success":
        file_id = task["file_id"]
        print("Completed file:", file_id)
        break

    if status == "Fail":
        message = task.get("error_message", "Video generation failed")
        raise RuntimeError(message)

    time.sleep(10)

完了したタスクについては、返された ID を使ってファイル情報を取得します。

file_id = "FILE_ID_FROM_SUCCESS_RESPONSE"

file_response = requests.get(
    f"{BASE_URL}/files/retrieve",
    headers=HEADERS,
    params={"file_id": file_id},
    timeout=30,
)
file_response.raise_for_status()

file_data = file_response.json()
download_url = file_data.get("file", {}).get("download_url")
if not download_url:
    download_url = file_data.get("download_url")

print("Download URL:", download_url)

正確なレスポンス形状はエンドポイントのバージョンによって異なる場合があります。統合時には JSON レスポンスを確認し、現在の MiniMax video generation API documentation に従ってください。

シンプルなスクリプトでは HTTP リクエスト失敗時に例外を送出できますが、本番向け統合にはより多くの構造が必要です。クライアントエラーと一時的なサービスエラーを分離し、回数制限付きリトライを使い、元のタスク識別子を保持してください。

一時的な失敗に対しては、直ちに再試行するのではなく指数バックオフを使用してください。

import time

def wait_with_backoff(attempt, base_delay=5, max_delay=60):
    delay = min(base_delay * (2 ** attempt), max_delay)
    time.sleep(delay)

ポーリングでは、ワーカーが無期限に稼働し続けないよう最大待機時間を設定します。

started_at = time.time()
max_wait_seconds = 30 * 60

while time.time() - started_at < max_wait_seconds:
    # Query the task here.
    # Break on Success or Fail.
    time.sleep(10)

raise TimeoutError("The MiniMax H3 task exceeded the polling limit.")

ローカルテストを超えて運用する際は、次のベストプラクティスを適用してください。

• プロンプトとペイロードを再現可能に保つ。 プロンプト、モデル、時間、解像度、参照ファイル識別子を保存します。
• バックグラウンドワーカーを使う。 Web リクエストはジョブを作成するだけで、動画レンダリングの完了を待つべきではありません。
• 重複送信を防ぐ。 create エンドポイントを呼び出す前に内部リクエスト ID を割り当てます。
• 入力を早期に検証する。 API 送信前に、欠落ファイル、未対応形式、競合する設定を拒否します。
• 出力 URL を保護する。 返されたダウンロードリンクはアプリケーションデータとして扱い、重要なファイルは管理されたストレージへコピーします。
• 利用状況を監視する。 成功タスク、失敗タスク、リトライ回数、総生成秒数を追跡します。

最も安全な開始点は、短い H3 タスクを 1 つ作成し、タイムアウト付きでポーリングし、結果を取得し、デバッグに必要な各レスポンスを記録する小さなバックエンドスクリプトです。その経路が機能したら、キュー、永続ストレージ、リトライポリシー、アプリケーションレベルのリクエスト追跡を追加してください。