MiniMax H3 プロンプトガイド：API で映画的なカメラワークを作る

対象モデル: minimax-h3
推論エンドポイント: https://api.toapis.com/v1/videos/generations
関連記事: MiniMax H3 API ガイド · H3 と Turbo の選び方 · 自動 R2V パイプライン

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

• 目的: ショットリストを、被写体・動作・カメラパス・レンズ・照明を含む再利用可能な MiniMax H3 プロンプトに落とし、ToAPIs の generations エンドポイントへ送る。
• 書き方: カメラ意図を先に、被写体を後に。方向のフレーズを焦点距離（例: 35mm と 85mm）と照明の手がかりと組み合わせる。
• 契約: ベース minimax-h3 は整数 4–15 秒 を受け付ける。ratio（16:9、9:16、および後述の値）を使う。これはフロントエンドのリクエスト契約であり、レイテンシや品質のベンチマークではない。
• 構文の注意: ブラケットタグはプロンプト補助。上流のモデル文書が明示しない限り、[Pan Left] を文書化されたネイティブコマンドとして扱わない。
• プロトコル: Bearer REST。一度だけ送信し、タスク識別子を保存し、期限付きで文書化されているタスク状態エンドポイントをポーリングする。

2. カメラワークのプロンプトパターン

有用な H3 プロンプトは、カメラやスタイルを足す前に 1つのシーンと1つの主動作 を書きます。モデルや duration を比較するときはこれらの部分を固定してください。そうしないと、文言変更が結果差の原因になります。

下表のタグは プロンプト補助 であり、保証されたコマンド文法ではありません。ToAPIs フロントエンド契約はプロンプトをテキストとして検証するだけで（最大 7,000 Unicode 文字）、[Pan Left] が H3 のネイティブコマンドであることは示しません。テンプレート内の統一語彙として使い、出力を確認してください。

図 1: パン、ティルト、ドリー、オービットを同一被写体の周りのプロンプト空間上の軌跡として扱い、ToAPIs ゲートウェイへ生成リクエストを一度だけ送ります。

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

[CAMERA] SUBJECT and ACTION, LIGHTING, shot on LENS, STYLE NOTES

例: [Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur.

ファーストフレーム（R2V）ジョブでも、同じプロンプト文言でアンカー画像の周囲や離れる動きを記述します。リクエストフィールドは R2V パイプラインのチュートリアル を参照してください。フレーム入力と参照メディアは引き続き排他モードです。

現行フロントエンドが受け付ける ratio は adaptive、21:9、16:9、4:3、1:1、3:4、9:16 です。フレーム入力がある場合は adaptive に固定されます。aspect_ratio は送らず、契約上のフィールド名 ratio を使います。

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-h3",
    "prompt": "[Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur",
    "duration": 6,
    "ratio": "16:9"
  }'

ステップ 2: Python のプロンプト補助とポーラー

フィールド名とレスポンスの形は、アカウント向け API リファレンスに合わせてください。次の例は他の ToAPIs 動画ガイドと同じタスク状態パスを使います。出荷前に task_id、status、video_url を確認してください。

import os
import time
import requests

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


def build_cinematic_prompt(
    subject: str,
    camera_move: str,
    lighting: str,
    lens: str = "35mm anamorphic",
) -> str:
    return (
        f"[{camera_move}] {subject}, {lighting}, "
        f"shot on {lens}, photorealistic, cinematic motion blur."
    )


def dispatch_camera_shot(prompt: str, duration: int = 6, ratio: str = "16:9") -> str:
    payload = {
        "model": "minimax-h3",
        "prompt": prompt,
        "duration": duration,
        "ratio": ratio,
    }
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("task_id") or data.get("id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_task(task_id: str, deadline_s: int = 180) -> str:
    poll_url = f"https://api.toapis.com/v1/videos/tasks/{task_id}"
    interval = 3.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status in {"succeeded", "success"}:
            return data["video_url"]
        if status in {"failed", "error"}:
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 8.0)
    raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")


if __name__ == "__main__":
    prompt = build_cinematic_prompt(
        subject="Matte black mechanical wristwatch resting on volcanic stone",
        camera_move="Orbit 180 + Slow Dolly In",
        lighting="Moody low-key rim lighting, subtle steam haze",
        lens="85mm macro lens",
    )
    task_id = dispatch_camera_shot(prompt)
    print("Task:", task_id)
    print("Video:", poll_task(task_id))

プロンプトテンプレートのバージョンをタスク記録と一緒に保存すると、モデル変更と文言変更を切り分けられます。クライアント側のタイムアウトは上流タスクの失敗を証明しません。課金対象の再送信の前に状態を確認してください。

ベース H3 の duration は 4〜15 秒の整数です。Max 系 ID は 5 秒からで、解像度リストも異なります。Turbo は参照メディアを受け付けません。ID を切り替える前に API ガイド を確認してください。

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

以下の分類は診断の出発点であり、ToAPIs の正確なエラーコードを保証するものではありません。

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

5. 料金と FinOps ROI

$\text{Estimated cost} = \text{successful output seconds} \times \text{current account rate per second}$

• 計画草案の単価を再利用しないでください。 秒単価、課金単位、失敗タスクの扱いはモデル、ルート、アカウントで変わります。ショットリストを見積もる前に、現行の ToAPIs カタログとアカウント見積を確認してください。
• 公式ベンダー契約 には年次コミット、席数枠、前払い下限が付くことがあります。ToAPIs は通常従量課金です。現行条件はアカウントで確認してください。
• プロンプト層で支出を制御する: バージョン付きテンプレートを使い、一度に一つの変数だけ変え、クライアントタイムアウトのあとは状態確認してから再送信を判断します。
• ベース H3、canonical Max、Turbo の使い分けは、未検証の速度や品質スコアではなく 選定ガイド を参照してください。

6. よくある質問

構造化 FAQ は frontmatter を参照してください。要約: プロンプトはカメラ意図から始める、複合カメラ表現はプロンプト文言であり保証された文法ではない、同じ書き方はファーストフレームモードでも使える、ブラケットタグは公式 API パラメータではない。

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

• ToAPIs Developer Portal でキーを発行する。
• minimax-h3、ratio: "16:9"、6 秒 duration で cURL 例をスモークテストする。
• プロンプト補助を取り込み、テンプレート版を保存し、180 秒の期限でポーリングする。
• 次に H3 API リクエスト契約 と 自動 R2V パイプライン を読む。