> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MiniMax H3（Hailuo）動画API：料金と使い方

> LaoZhang APIでMiniMax H3を呼び出し、テキスト、先頭・末尾フレーム、参照素材から動画タスクを作成してMP4を保存します。768Pと2Kの1秒あたり料金も確認できます。

MiniMax H3は、MiniMaxのオムニモーダル動画モデルです。テキスト・画像・動画・音声を1つのモデルで入力でき、BGMと効果音付きの動画を返します。

| 項目 | 内容 |
| - | - |
| モデルID | `MiniMax-H3`（大文字・小文字を区別する） |
| タスクの作成 | `POST /hailuo/v2/video_generation` |
| タスクの取得 | `GET /hailuo/v2/query/video_generation/{task_id}`。成功したら `task.content.url` からMP4をダウンロードする |
| トークングループ | `default`、`vip`、`svip`。課金方式は従量優先 |
| 料金 | 768Pは\$0.05/秒（公式より37.5%低い）、2Kは\$0.08/秒（公式より38%低い）。リクエストした長さで課金。詳細は下の「料金」を参照 |
| 出力 | 4〜15の整数秒、`768P` または `2K`、ステレオ音声付き |
| 保存期間 | 動画のリンクは7日間利用できる |
| ルート | MiniMaxが公開しているH3のオープンウェイトを独立したデプロイで動かしています。MiniMaxの公式APIは経由しないため、料金も独自に設定しています |

> [!WARNING]
>
> MiniMax H3は、上記のネイティブの `/hailuo/v2` エンドポイントでのみ利用できます。`/v1/videos` や `/v1/video/generations` に送ったリクエストは拒否され、課金されません。

![MiniMax H3のテキストからの動画生成の例：夕暮れ、雨に濡れた屋根の上を歩くオレンジ色の猫と、背景の街の明かり](https://mintcdn.com/laozhangai-edd05f2c/McVdWQYpbAhpR0pV/images/samples/minimax-h3-en-t2v.jpg?fit=max\&auto=format\&n=McVdWQYpbAhpR0pV\&q=85\&s=30be48ac6cea982fc081d900634b5277)

下のテキストから動画を生成する例の出力：768P、5秒、16:9（プロンプトは出力例に対応するため英語のままです）

## トークンの作成

[トークン管理](https://api.laozhang.ai/token)で、次の設定でトークンを追加します。

| 設定 | 値 |
| - | - |
| グループ | `default`、`vip`、`svip`。3つとも料金は同じ |
| 課金方式 | 従量優先（推奨。コンソールの表示は「按量优先」）または従量課金（「按量计费」）。回数課金（「按次计费」）のトークンではこのモデルを呼び出せない |
| ヒント | 動画専用のトークンを作ると、呼び出しログで課金とタスクを照合しやすい |

MiniMaxのアカウントも、動画専用のグループも必要ありません。

## 料金

MiniMax H3は、動画の長さに応じて課金されます。2026年10月24日時点の料金です。

| 項目 | LaoZhang API | MiniMax公式API | 割引率 |
| - | -: | -: | -: |
| 768Pの出力 | \$0.05 / 秒 | \$0.08 / 秒 | 37.5% |
| 2Kの出力 | \$0.08 / 秒 | \$0.13 / 秒 | 38% |
| 参照動画 | 出力解像度の単価で秒数分 | 出力解像度の単価で秒数分 | 出力と同じ |
| 参照画像（最初の5枚は無料） | 6枚目から1枚あたり\$0.03 | 6枚目から1枚あたり\$0.04 | 25% |
| 参照音声 | 無料 | 無料 | — |

公式価格は[MiniMaxの従量課金料金](https://platform.minimax.io/docs/guides/pricing-paygo)（MiniMax-H3、2026年10月24日確認）によります。横向き、縦向き、正方形の動画の料金は同じで、解像度と秒数だけで決まります。

課金される秒数の数え方です。

* 出力：リクエストした `duration`。クリップは通常、リクエストより0.1〜0.5秒長くなりますが、追加料金はかかりません。
* 参照動画：その長さを、次の整数秒に切り上げた秒数。5.8秒のクリップは6秒として数えます。
* 参照画像：1つのタスクで最初の5枚を超える画像が、1枚ずつ課金されます。先頭フレームと末尾フレームの画像も、枚数に含まれます。

動画1本あたりの費用の例です。

* 768P、5秒のテキストからの動画：5 × \$0.05 = \$0.25
* 2K、10秒のテキストからの動画：10 × \$0.08 = \$0.80
* 768P、4秒の動画に6秒の参照動画を付ける：(4 + 6) × \$0.05 = \$0.50

タスクの作成時には、長さ × 単価と、6枚目以降の参照画像の分が、残高から確保されます。参照動画があるタスクでは、参照動画の秒数分がタスクの完了後に課金されるため、呼び出しログには2回目の精算の記録が現れます。

失敗したタスクは全額返金され、送信時に拒否されたリクエストは課金されません。再送すると新しいタスクが作成されて再び課金されるため、自社の業務IDと `task_id` の対応を保存してください。タスクごとの正確な課金額は、[呼び出しログ](https://api.laozhang.ai/log)で確認できます。

## 出力例

次のクリップは、編集していない `MiniMax-H3` の出力で、モデルが生成した音声がそのまま付いています。クリックすると再生されます。キャプションには、解像度、長さ、アスペクト比、プロンプトを載せています。

[Museの動画の出力例](https://docs.laozhang.ai/ja/api-capabilities/muse-video-generation.md)は同じプロンプトを使っているため、2つのモデルをシーンごとに比較できます。プロンプトは出力と対応させるため、英語のままです。

<video controls preload="none" poster="/images/samples/minimax-h3-sample-fox-768p-6s.jpg" src="https://media.laozhang.ai/samples/video/h3-fox-768p-6s.mp4" />

768P、6秒、16:9。プロンプト：A red fox walking through snowy forest at sunrise, cinematic

<video controls preload="none" poster="/images/samples/minimax-h3-sample-fox-2k-6s.jpg" src="https://media.laozhang.ai/samples/video/h3-fox-2k-6s.mp4" />

2K（2560×1440）、6秒、16:9。前のクリップと同じプロンプト

<video controls preload="none" poster="/images/samples/minimax-h3-sample-paper-boat-768p-10s.jpg" src="https://media.laozhang.ai/samples/video/h3-paper-boat-768p-10s.mp4" />

768P、10秒、16:9。プロンプト：A paper boat drifts down a rainy city gutter, then sails into a small sunny pond

<video controls preload="none" poster="/images/samples/minimax-h3-sample-hot-air-balloon-768p-10s.jpg" src="https://media.laozhang.ai/samples/video/h3-hot-air-balloon-768p-10s.mp4" />

768P、10秒、16:9。プロンプト：A hot air balloon rises over a valley at dawn, drifts over a river and a village, then lands in a meadow

<video controls preload="none" poster="/images/samples/minimax-h3-sample-cyclist-768p-10s-9x16.jpg" src="https://media.laozhang.ai/samples/video/h3-cyclist-768p-10s-9x16.mp4" />

768P、10秒、9:16の縦向き。プロンプト：A cyclist rides through a coastal town from morning to sunset: market, harbor, cliff road, lighthouse

## 仕組み

**1. タスクを作成する**

次の内容のJSON本文で、`POST /hailuo/v2/video_generation` を送ります。

* `model`：`MiniMax-H3`
* `content`：テキスト項目1つと、任意の画像・動画・音声の入力
* `resolution`、`duration`、`ratio`

レスポンスの `task_id` を保存してください。

**2. タスクをポーリングする**

10秒おきに `GET /hailuo/v2/query/video_generation/{task_id}` を呼び、`task.status` を読み取ります。4〜5秒の768Pの動画は、通常約1分で完了します。2Kと参照動画付きのタスクは、より時間がかかります。クライアント側の全体のタイムアウトは30分にしてください。

**3. 動画をダウンロードする**

`task.status` が `succeeded` になったら、`task.content.url` からMP4をダウンロードします。リンクは7日間利用でき、`Authorization` ヘッダーは不要です。

## 準備

cURLの例では、レスポンスのフィールドを読み取るために `jq` を使います（macOSでは `brew install jq` でインストールできます）。先にキーとベースURLを設定します。

```bash theme={null}
export LAOZHANG_API_KEY="your-laozhang-api-key"
export BASE_URL="https://api.laozhang.ai"
```

## テキストから動画を生成する

```bash theme={null}
curl -s -X POST "$BASE_URL/hailuo/v2/video_generation" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "At dusk, an orange cat walks slowly across a rain-soaked rooftop as the city lights come on, slow tracking shot, cinematic lighting"
      }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }' | tee h3-create.json

export TASK_ID=$(jq -r '.task_id' h3-create.json)
```

リクエストが成功すると、タスクIDだけが返ります。

```json theme={null}
{
  "task_id": "1792835118519344847"
}
```

テキストのみのリクエストでは、`ratio` を固定の値にする必要があります。画像がない場合、`adaptive` は受け付けられません。

## 先頭フレーム、または先頭と末尾のフレームから動かす

`first_frame` で最初のショットを指定し、`last_frame` を加えると最後のショットも指定できます。`ratio` を `adaptive` にすると、出力は先頭フレームのアスペクト比に従います。

```bash theme={null}
curl -s -X POST "$BASE_URL/hailuo/v2/video_generation" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "犬は浜辺を走り続け、カメラがそれを追いかける" },
      { "type": "image_url", "role": "first_frame", "image_url": { "url": "https://example.com/start.jpg" } },
      { "type": "image_url", "role": "last_frame", "image_url": { "url": "https://example.com/end.jpg" } }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "adaptive"
  }'
```

画像は、公開のHTTPS URL、または `data:image/jpeg;base64,...` のようなBase64のデータURLで渡します。先頭フレームだけを使うときは、`last_frame` の項目を外してください。

## 参照画像・動画・音声から生成する

参照を使うと、特定のキャラクターやオブジェクトをシーンに登場させたり、クリップの動きとカメラワークを再利用したり、音声のリズムに合わせたりできます。プロンプトでは、種類と順番で参照を指します。最初の参照画像は `<Picture 1>`、最初の参照動画は `<Video 1>`、最初の参照音声は `<Audio 1>` です。

```bash theme={null}
curl -s -X POST "$BASE_URL/hailuo/v2/video_generation" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "<Picture 1>のキャラクターが公園の小道を歩く。カメラワークは<Video 1>のように、テンポは<Audio 1>に合わせる" },
      { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://example.com/character.png" } },
      { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://example.com/camera-move.mp4" } },
      { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://example.com/beat.mp3" } }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9"
  }'
```

参照を組み合わせるときの注意点です。

* 参照画像・動画・音声は自由に組み合わせられますが、音声だけを参照にはできません。参照画像か参照動画を少なくとも1つ加えてください。
* 先頭・末尾フレームは、参照と同じリクエストでは使えません。
* 動画と音声の入力は、サービスが直接ダウンロードできる公開のHTTPSリンクにしてください。
* 参照動画は秒数に応じて課金されます。「料金」を参照してください。

## ポーリングとダウンロード

### タスクを取得する

```bash theme={null}
curl -s "$BASE_URL/hailuo/v2/query/video_generation/$TASK_ID" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -o h3-task.json
jq -r '.task.status' h3-task.json
```

`task.status` が `succeeded` か `failed` になるまで、10秒おきに実行します。成功時のレスポンスは次のようになります。

```json theme={null}
{
  "task": {
    "id": "1792835118519344847",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1792835121,
    "updated_at": 1792835146,
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video",
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "content": {
      "url": "https://media.laozhang.ai/videos/1792835118519344847-xxxxxxxxxxxxxxxx.mp4"
    }
  }
}
```

`usage` には、タスクで課金される秒数が入ります。`input_seconds` は参照動画、`output_seconds` は生成された動画の秒数です。

### 動画をダウンロードする

```bash theme={null}
VIDEO_URL=$(jq -r '.task.content.url // empty' h3-task.json)
curl -L -o h3-output.mp4 "$VIDEO_URL"
```

リンクは7日間利用できます。タスクが完了したら、早めにファイルを自社のストレージにコピーしてください。

## 最小のPythonクライアント

このスクリプトはPythonの標準ライブラリだけを使います。実行する前に `LAOZHANG_API_KEY` を設定してください。10秒おきにポーリングし、全体のタイムアウトは30分で、結果を `h3-output.mp4` として保存します。

```python theme={null}
import json
import os
import time
import urllib.request
from urllib.error import HTTPError

BASE_URL = "https://api.laozhang.ai"
API_KEY = os.environ["LAOZHANG_API_KEY"]
POLL_INTERVAL = 10  # 秒
TIMEOUT = 30 * 60  # 全体のタイムアウト（30分）


def request(method, path, body=None):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode("utf-8")
    req = urllib.request.Request(BASE_URL + path, data=data, method=method, headers=headers)
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            return json.loads(resp.read().decode("utf-8"))
    except HTTPError as exc:
        error_body = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"HTTP {exc.code}: {error_body}") from exc


created = request(
    "POST",
    "/hailuo/v2/video_generation",
    {
        "model": "MiniMax-H3",
        "content": [{"type": "text", "text": "At dusk, an orange cat walks slowly across a rain-soaked rooftop as the city lights come on"}],
        "resolution": "768P",
        "duration": 5,
        "ratio": "16:9",
    },
)
task_id = created["task_id"]
print("task_id:", task_id)

deadline = time.monotonic() + TIMEOUT
while True:
    task = request("GET", f"/hailuo/v2/query/video_generation/{task_id}")["task"]
    status = task["status"]
    print("status:", status)

    if status == "succeeded":
        # ダウンロードリンクにAuthorizationヘッダーは不要。User-Agentは付ける（PythonのデフォルトのUser-Agentを拒否するCDNがあるため）
        download = urllib.request.Request(task["content"]["url"], headers={"User-Agent": "h3-client/1.0"})
        with urllib.request.urlopen(download, timeout=300) as resp, open("h3-output.mp4", "wb") as f:
            f.write(resp.read())
        print("保存しました: h3-output.mp4")
        break
    if status == "failed":
        raise RuntimeError(f"タスクが失敗しました（課金は返金済み）: {json.dumps(task.get('error'))}")
    if time.monotonic() >= deadline:
        raise TimeoutError(f"タスク {task_id} は30分たってもまだ実行中です。同じtask_idのポーリングを続けてください")
    time.sleep(POLL_INTERVAL)
```

## APIリファレンス

### リクエストの基本

| 設定 | 値 |
| - | - |
| ベースURL | `https://api.laozhang.ai` |
| 認証 | `Authorization: Bearer $LAOZHANG_API_KEY` |
| リクエスト形式 | `application/json` |
| ポーリング間隔 | 10秒を推奨 |
| クライアントのタイムアウト | 30分を推奨 |

```text theme={null}
POST https://api.laozhang.ai/hailuo/v2/video_generation
GET  https://api.laozhang.ai/hailuo/v2/query/video_generation/{task_id}
```

### リクエスト本文

| フィールド | 型 | 必須 | 説明 |
| - | - | - | - |
| `model` | string | 必須 | 常に `MiniMax-H3` |
| `content` | array | 必須 | テキスト項目をちょうど1つと、任意の入力。次の表を参照 |
| `resolution` | string | 必須 | `768P` または `2K`（大文字） |
| `duration` | integer | 必須 | 4〜15の整数秒。文字列と小数は拒否される |
| `ratio` | string | 必須 | `21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`adaptive` |

`adaptive` は画像のアスペクト比に従い、テキストのみ、または音声のみのリクエストでは使えません。16:9のとき、768Pの出力は1344×768、2Kの出力は2560×1440です。

### `content[]` の入力

| `type` | `role` | リンクのフィールド | 上限 |
| - | - | - | - |
| `text` | — | `text`（最大7,000文字） | 1項目 |
| `image_url` | `first_frame`、`last_frame`、`reference_image` | `image_url.url` | 9枚 |
| `video_url` | `reference_video` | `video_url.url` | 3クリップ、合計15秒 |
| `audio_url` | `reference_audio` | `audio_url.url` | 3クリップ |

画像が1枚だけの場合は `role` を省略でき、先頭フレームとして扱われます。画像が2枚以上のときは、それぞれに `role` を指定してください。

### タスクの状態

| `task.status` | 最終状態か | 対応 |
| - | - | - |
| `queued` | いいえ | 開始待ち。ポーリングを続け、再送しない |
| `running` | いいえ | 生成中。ポーリングを続ける |
| `succeeded` | はい | `task.content.url` からMP4をダウンロードする |
| `failed` | はい | `task.error.message` を読む。課金は返金済み |

混雑時には、タスクがしばらく `queued` のままになることがあります。送信した順に自動で開始されます。30分たっても開始されないタスクは `failed` になり、返金されます。

## エラー

| レスポンス | 考えられる原因 | 対処 |
| - | - | - |
| 400 `分辨率必须为 768P 或 2K。` | `resolution` が `768P` でも `2K` でもない、または `768p` のように小文字になっている | `768P` か `2K` を使う |
| 400 `生成时长必须为 4 至 15 秒的整数。` | `duration` が範囲外、文字列、または小数 | 4〜15の整数を送る |
| 400 `参考音频不能单独使用` | リクエストがテキストと参照音声だけ | 参照画像か参照動画を加える |
| 400 `MiniMax-H3 only supports POST /hailuo/v2/video_generation.` | リクエストを `/v1/video/generations` に送った | このページのタスク作成エンドポイントを使う |
| `cannot download media URL` を伴う `failed` | 入力のリンクをインターネットから取得できない（404、ホットリンク防止、プライベートアドレス） | 直接ダウンロードできるHTTPSリンクで再送する |
| 503 `The video service is busy. Please retry later.` | サービスが一時的に混雑していて、タスクは作成されなかった | 少し待って再試行する。このリクエストは課金されない |
| `Current group ... has no available channels for model ...` | トークンが `default`、`vip`、`svip` のいずれにも属していない、またはモデルIDの大文字・小文字が違う | トークングループと、`MiniMax-H3` のスペルを確認する |
| `... under billing mode [pay-per-request]` | トークンの課金方式が回数課金になっている | トークンの課金方式を従量優先か従量課金に切り替える |

上のように、検証メッセージの一部は中国語で返ります。本番では、サポートへの連絡や課金の照合に備えて、作成時のレスポンスの `task_id` と、最終的なタスクの詳細を保存しておいてください。連絡先は [hi@laozhang.ai](mailto:hi@laozhang.ai) です。

## よくある質問

### 5秒の動画はいくらですか？

768Pは\$0.25、2Kは\$0.40です。費用は長さに比例するため、768Pの15秒なら\$0.75です。参照動画はその秒数が同じ単価で加算され、6枚目以降の参照画像は1枚あたり\$0.03が加算されます。「料金」を参照してください。

### 768Pと2Kのどちらを使うべきですか？

プロンプトと構図は、4〜5秒のクリップを768Pで試して調整し、最終版を2Kまたはより長い尺で生成してください。2Kは1秒あたり\$0.03高く、生成にも時間がかかるため、大画面向けの映像や、さらに編集する素材に使うのが向いています。

### OpenAI形式の `/v1/videos` で使えますか？

いいえ。先頭・末尾フレーム、複数の参照画像、参照動画、参照音声は、いずれも `content[]` の構造に依存します。そのためLaoZhang APIは、MiniMax H3をネイティブの `/hailuo/v2` エンドポイントでのみ提供しています。`/v1/videos` や `/v1/video/generations` へのリクエストは、課金されずに拒否されます。

### 動画に音声は付きますか？ オフにできますか？

どの動画にもステレオ音声が付き、BGMと効果音はプロンプトと参照音声に沿って作られます。無効にするパラメーターはありません。音声が不要なときは、ダウンロードしたあとで音声トラックを取り除いてください。

### タイムアウト後に再送してよいですか？

先にタスクを確認してください。クライアント側のタイムアウトは、タスクの失敗を意味しません。同じ `task_id` のポーリングを続けてください。再送すると新しいタスクが作成され、再び課金されます。`task.status` が `failed` になったあとだけ、リクエストを作り直してください。失敗したタスクはすでに返金されています。

### 動画のリンクはいつまで保存されますか？

7日間です。その後はリンクが使えなくなり、タスクを再ダウンロードすることもできません。タスクが完了したらすぐにファイルを保存してください。

## 関連ドキュメント

* [動画APIの比較と料金](https://docs.laozhang.ai/ja/api-capabilities/video-generation-guide.md)
* [Muse動画API](https://docs.laozhang.ai/ja/api-capabilities/muse-video-generation.md)
* [Wan 2.7・Wan 3.0動画生成API](https://docs.laozhang.ai/ja/api-capabilities/wan-video-generation.md)
* [Seedance 2.0動画生成API](https://docs.laozhang.ai/ja/api-capabilities/seedance2-video-generation.md)
* [モデルと料金](https://docs.laozhang.ai/ja/models.md)
* [呼び出しログ](https://docs.laozhang.ai/en/faq/call-logs.md)
* [MiniMaxの従量課金料金](https://platform.minimax.io/docs/guides/pricing-paygo)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.