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

# MiniMax-H3 動画生成

> MiniMax H3 (Hailuo 3.0) 動画生成ガイド：テキスト、最初/最後のフレーム、参照画像/動画/音声からの動画生成を1つのエンドポイントで対応、ネイティブステレオ音声、768P、4〜15秒、1秒あたり$0.03で課金。

## 概要

MiniMax H3 (Hailuo 3.0) は、MiniMax が 2026-07-31 (UTC+8) にリリースしたオムニモーダル動画モデルです。単一のモデルでテキスト、画像、動画、音声を入力として受け取り、**ステレオ音声を伴う**動画を出力します。APIYI では、オープンウェイトのセルフホスト環境から `MiniMax-H3` を提供しており、768P、1 クリップあたり 4〜15 秒、秒単位で課金されます。

<Note>
  **主な特徴**: 1 つのエンドポイントで、テキストからの動画生成、先頭フレーム／末尾フレーム／先頭・末尾フレーム指定動画生成、ならびに最大 9 枚の画像、3 本の動画、3 件の音声クリップを用いた混合リファレンス生成に対応しています。すべてのクリップに音楽と効果音が付与されます。**1 秒あたり \$0.03**（MiniMax 公式 API では \$0.08）のため、10 秒のクリップは \$0.30 となり、失敗したタスクは自動的に返金されます。
</Note>

<CardGroup cols={2}>
  <Card title="動画生成 API リファレンス" icon="video" href="/ja/api-capabilities/minimax-h3/video-generation">
    タスクを作成し、task\_id で照会。Python / cURL / Node.js のサンプルコードとライブ Playground を提供
  </Card>

  <Card title="チャージボーナス" icon="gift" href="/ja/faq/recharge-promotions">
    チャージボーナスにより、実質価格をさらに引き下げることができます
  </Card>
</CardGroup>

## AIエージェントに統合を任せる

<Note>
  Codex / Claude Code / Cursor を使用して構築する場合は、以下の prompt をそこにコピーしてください。エージェントはまずこのページのプレーンテキスト版を取得し（任意のドキュメント URL に `.md` を追加）、お使いのスタックに合わせたコードを作成します。よくある誤りはすでに対策されています：パスには `/hailuo` が必要であること、結果は `task` の中に存在すること、そして `duration` は4〜15の整数でなければならないことなどです。
</Note>

<Prompt description="コーディングエージェントにMiniMax-H3の動画生成を統合またはデバッグさせます。Codex、Claude Code、Cursorなどのツールにコピー＆ペーストしてください。" icon="bot" actions={["copy"]}>
  このプロジェクトでMiniMax-H3の動画生成（text-to-video / 最初と最後のフレームによる動画 / 参照動画）を統合またはデバッグしてください。

  コードを書く前にドキュメントを読んでください：このページのプレーンテキスト版については [https://docs.apiyi.com/en/api-capabilities/minimax-h3/overview.md](https://docs.apiyi.com/en/api-capabilities/minimax-h3/overview.md) を取得してください。パラメータとコードサンプルは [https://docs.apiyi.com/en/api-capabilities/minimax-h3/video-generation.md](https://docs.apiyi.com/en/api-capabilities/minimax-h3/video-generation.md) にあります。

  要件：

  1. エンドポイント：`POST https://api.apiyi.com/hailuo/v2/video_generation` で送信し、`GET https://api.apiyi.com/hailuo/v2/query/video_generation/{task_id}` でクエリします。**パスは `/hailuo` で始まる必要があります**。これがないと、JSON ではなくウェブページが返されます。

  2. ポーリングとステータス：送信時は `{"task_id": ...}` のみが返されます。10秒ごとにポーリングし、15分後に中止してください。クエリ結果は **`task`** オブジェクト内にラップされます。ステータスは `queued` / `running` / `succeeded` / `failed` であり、**成功は `succeeded` です**。`progress` は0または1にしかならないため、これをもとにプログレスバーを作成しないでください。

  3. 動画の保存：URL は **`task.content.url`** であり、認証ヘッダーは不要です。サーバー側でダウンロードして自身で保存してください。URL のチェックには GET を使用してください。HEAD リクエストに対しては 403 が返されます。

  4. リクエストボディと型：5つのフィールド `{ model, content[], resolution, duration, ratio }` はすべて必須です。`model` は常に `MiniMax-H3` です（大文字と小文字を区別）。**`duration` は整数であり**、`"5"` のような文字列や小数は拒絶されます。**`resolution` は大文字の `768P` でなければならず**、`768p` および `2K` はどちらも拒絶されます。

  5. パラメータの制限：`duration` は4〜15秒、`ratio` は `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive` のいずれかです。**テキストのみおよび音声のみのリクエストでは `adaptive` を使用できません**。`content` には最大7000文字のテキスト項目が厳密に1つ含まれている必要があります。ドキュメントに記載されていないフィールド（`seed` や `prompt` など）は追加しないでください。拒絶されます。

  6. メディア入力：画像は `{"type":"image_url","image_url":{"url":...},"role":...}` に格納し、動画は `video_url` + `reference_video`、音声は `audio_url` + `reference_audio` を使用します。すべての URL は**公開された https リンク**である必要があります。base64、データ URI、プライベートアドレスはサポートされていません。最初/最後のフレーム（`first_frame` / `last_frame`）は参照メディアと混在させることは**できません**。複数の画像がある場合はそれぞれに `role` が必要です。制限：参照画像は9件、参照動画は3件（合計で最大15秒）、参照音声クリップは3件までです。prompt 内では、メディアをタイプごとの順番で番号付けして `<Picture 1>` `<Video 1>` `<Audio 1>` として参照してください。

  7. 課金と冪等性：1秒あたり0.03米ドルで課金され、参照画像、動画、音声に追加料金はかかりません。`failed` タスクは自動的に返金され、送信エラーは課金されません。**`Idempotency-Key` ヘッダーは現在効果がないため、再送信するたびに再度課金されます。** ビジネス ID から task\_id への独自のマッピングを保持し、送信時の HTTP 500 番台のエラーおよびネットワークエラーのみをバックオフ（5秒 / 10秒 / 20秒）を伴って再試行してください。400 番台のエラーの場合は、再試行するのではなくパラメータを修正してください。

  8. token：`default` グループまたは `svip` グループが使用可能です。課金モデルを **Pay-as-you-go Priority** に設定してください。「no available channel」というエラーは、token のグループが間違っているか、モデル名のスペルが誤っていることを意味します。

  9. キーは `APIYI_API_KEY` 環境変数から読み取ってください。ハードコードしたり git にコミットしたりしないでください。

  10. 完了したら、実際の5秒間の text-to-video リクエストを1回実行し、動画の URL と呼び出しにかかった費用を私に送信してください。全体のフローには2〜4分かかります。サンドボックスで実行する場合は、コマンドのタイムアウトを600秒以上に設定するか、バックグラウンドで実行してください。
</Prompt>

<Accordion title="この prompt が防止する問題">
  | 要件 | 防止される誤り |
  | - | - |
  | パスが `/hailuo` で始まる | 単なる `/v2/...` ではウェブページが返され、JSON のパースに失敗し、サービスが停止しているように見えます |
  | 結果は `task` 内にある | トップレベルで `status` を探しても一致せず、タイムアウトまでポーリングが繰り返されます |
  | `duration` は4〜15の整数 | 文字列や小数は拒絶され、エラーメッセージには誤解を招く「JSON が無効」という内容が表示されます |
  | テキストのみの場合は `adaptive` なし | text-to-video には固定の比率が必要です |
  | 冪等性キーに効果はない | `Idempotency-Key` で再試行が安全になると想定しがちですが、再試行するたびに新規に課金されます |
  | GET で URL をチェック | 動画の URL は HEAD に対して 403 を返すため、リンク切れのように見えます |
</Accordion>

## APIYI の MiniMax-H3 が選ばれる理由

<CardGroup cols={2}>
  <Card title="完全な機能セット" icon="layers">
    テキスト、開始・終了フレーム、画像／動画／音声の混合参照生成にすべて対応しており、公式モデルと同じ参照制限（画像9枚＋動画3本＋音声クリップ3本）が適用されます
  </Card>

  <Card title="秒単位の課金、失敗時は返金" icon="receipt">
    1秒あたり\$0.03で、生成に成功した動画にのみ課金されます。失敗したタスクは全額返金され、送信エラーは無料です
  </Card>

  <Card title="チャージボーナスの併用が可能" icon="gift">
    [チャージボーナス](/ja/faq/recharge-promotions)と組み合わせることで、実質コストをさらに抑えられます
  </Card>

  <Card title="障壁のないグローバルアクセス" icon="globe">
    1つのAPIキーで`api.apiyi.com`に直接接続でき、海外アカウントは不要です
  </Card>

  <Card title="充実した動画モデルラインナップ" icon="clapperboard">
    同じキーで[Seedance 2.0 / 2.5](/ja/api-capabilities/seedance2/overview)、[Wan2.7](/ja/api-capabilities/wan/overview)、[VEO 3.1](/ja/api-capabilities/veo-3-1-official/overview)などもご利用いただけます
  </Card>

  <Card title="プロフェッショナルサポート" icon="headset">
    連携に関するご質問はサポートまでお問い合わせください。エンタープライズのお客様にはハンズオンでのオンボーディングを提供しています
  </Card>
</CardGroup>

## 主な機能

<CardGroup cols={2}>
  <Card title="ネイティブステレオオーディオ" icon="music">
    すべてのクリップにpromptや任意の参照オーディオに基づいた音楽と効果音が含まれており、ダビングの工程は不要です
  </Card>

  <Card title="7つのアスペクト比" icon="ratio">
    `21:9`から`9:16`までの6つの固定比率に加え、参照画像に追従する`adaptive`に対応しています
  </Card>

  <Card title="4〜15秒の任意の整数秒" icon="timer">
    リクエストされた実際の秒数に基づいて課金されるため、短いクリップほど低コストになります
  </Card>

  <Card title="長文のprompt" icon="text">
    1つのpromptあたり最大7,000文字まで対応しており、カットごとの詳細な描写にも十分です
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="先頭・末尾フレームの制御" icon="image">
    先頭フレームのみ、末尾フレームのみ、またはその両方を指定して、クリップの開始と終了の様子を設定できます
  </Card>

  <Card title="複数の参照画像" icon="images">
    最大9枚の参照画像に対応しています。prompt内で`<Picture 1>`などを使用してキャラクターやオブジェクトをタグ付けできます
  </Card>

  <Card title="動画からのモーション転送" icon="film">
    カメラワークや動きのリズムを再現するために、最大3本の参照動画を指定できます
  </Card>

  <Card title="オーディオ駆動の動画" icon="audio-lines">
    最大3つの参照オーディオクリップに対応しており、映像が音楽や音声に追従します
  </Card>
</CardGroup>

## 料金

本チャンネルは、独自のデプロイ環境でMiniMaxのオープンH3重みを実行しています。**公式MiniMax APIのリレーではない**ため、独自の料金が適用されます：

| 項目 | APIYI（セルフホスト、768P） | 公式MiniMax API（768P） |
| - | - | - |
| 出力動画 | **\$0.03 / 秒** | \$0.08 / 秒 |
| 参照画像 | 無料（最大9枚） | 最初の5枚は無料、以降1枚あたり\$0.04 |
| 参照動画 | 無料 | 入力1秒あたり\$0.08 |
| 参照音声 | 無料 | 無料 |
| 例：10秒のテキスト動画生成 | **\$0.30** | \$0.80 |

<Note>本チャンネルはオープン重みのセルフホストデプロイメントであり、公式MiniMax APIとは個別に料金が設定されており、価格は変更される場合があります。上記の表は参考用であり、トップナビゲーションの**モデル料金**タブの情報が正式なものとなります：[モデル料金](/en/models/index)。公式価格は`platform.minimax.io/docs/guides/pricing-paygo`より（2026-09-29取得）。</Note>

<Info>
  **課金の詳細**:

  * リクエストされた`duration`（秒単位）に基づいて課金され、タスク受付時に事前課金されます
  * **参照メディアの追加料金なし**：参照画像（最大9枚）、動画、音声によって料金が変わることはなく、再生時間のみが課金されます
  * 失敗したタスク（メディアのダウンロード失敗、未対応フォーマット、実行失敗など）は、**自動的に全額返金されます**
  * 送信時に4xx / 5xxを返したリクエストは課金されません。照会およびダウンロードは無料です
  * 実質コストを抑える方法については、[チャージボーナス](/ja/faq/recharge-promotions)をご確認ください
</Info>

## グループの設定

MiniMax-H3は\*\*`default`グループで利用可能**であり、`svip`グループでも動作します。専用のグループは不要です。Tokenの課金モデルは**従量課金優先\*\*に設定することをお勧めします。呼び出し時に「no available channels for the current group」と返される場合、Tokenのグループにこのモデルが含まれていないか、`model`の値のスペルが誤っている（大文字と小文字は区別されます）可能性があります。

| 項目 | 要件 |
| - | - |
| グループ | `default` または `svip` |
| 課金モデル | 従量課金優先（推奨） |
| モデル名 | `MiniMax-H3`（大文字と小文字を区別） |

## 技術仕様

| 項目 | 仕様 |
| - | - |
| モデルID | `MiniMax-H3` |
| 解像度 | `768P` のみ |
| 長さ | 整数 4〜15秒（完成したクリップは通常0.1〜0.5秒長くなります） |
| アスペクト比 | `21:9` 1536×672 / `16:9` 1344×768 / `4:3` 1024×768 / `1:1` 768×768 / `3:4` 768×1024 / `9:16` 768×1344 / `adaptive` |
| 音声 | ステレオトラックが常に含まれ、切り替えスイッチはありません |
| prompt | テキスト1件、1〜7000文字 |
| 参照メディア | 画像 ≤ 9、動画 ≤ 3（合計 ≤ 15秒）、音声 ≤ 3、メディアアイテム全体で ≤ 12 |
| メディア入力 | 公開HTTPS URLのみ |
| 出力 | MP4、`task.content.url` 経由 |
| 生成時間 | 実測中央値は約3分（2〜6分） |

<Warning>
  公式のMiniMax H3モデルは2Kをサポートしていますが、このチャネルでは**768Pのみ提供**しており、`2K` は拒否されます。
</Warning>

## API エンドポイント

| 用途 | メソッド | パス | Content-Type |
| - | - | - | - |
| タスク作成 | `POST` | `/hailuo/v2/video_generation` | `application/json` |
| タスク照会 | `GET` | `/hailuo/v2/query/video_generation/{task_id}` | — |

<Tip>
  プライマリホストは`https://api.apiyi.com`、バックアップホストは`https://vip.apiyi.com`で、パスは共通です。パスは\*\*`/hailuo`で始まり\*\*、`/v1`ではない点にご注意ください。
</Tip>

## 生成モード

生成モードは`content[]`内のメディアから判定されます：

| モード | `content[]` | `ratio` |
| - | - | - |
| テキストから動画 | テキスト項目1点のみ | 固定比率が必須 |
| 先頭フレーム動画 | テキスト + 1つの`first_frame`画像 | 固定または`adaptive` |
| 最終フレーム動画 | テキスト + 1つの`last_frame`画像 | 固定または`adaptive` |
| 先頭・最終フレーム動画 | テキスト + `first_frame` + `last_frame` | 固定または`adaptive` |
| 参照動画 | テキスト + `reference_image` / `reference_video` / `reference_audio`の任意の組み合わせ | 固定または`adaptive`、**音声のみの場合は固定比率が必須** |

### prompt内でのメディアの参照

各メディアタイプは`content[]`内の順序に従って番号付けされます。1つ目と2つ目の参照画像は`<Picture 1>`と`<Picture 2>`、1つ目の参照動画は`<Video 1>`、1つ目の参照音声クリップは`<Audio 1>`となります。例えば：

```text theme={null}
<Picture 1> dances with the moves from <Video 1>, in time with <Audio 1>
```

<Warning>
  * 先頭/最終フレームは、いかなる参照メディアとも組み合わせることは**できません**
  * 画像が1枚だけの場合は`role`を省略できます（先頭フレームとして扱われます）。**画像が2枚以上の場合は、それぞれに`role`を設定してください**
  * 参照動画の**合計時間**は15秒を超えることはできません。超えた場合、タスクは失敗します（返金処理が行われます）。15秒を超える単一のクリップは最初の15秒間にトリミングされます
</Warning>

## ベストプラクティス

<Steps>
  <Step title="まずは4〜5秒でテストする">
    課金は秒単位で行われるため、10〜15秒のレンダリングを行う前に、短いクリップで構図やスタイルを確認してください
  </Step>

  <Step title="テキストからの動画生成には固定比率を使用する">
    横向きには`16:9`、縦向きには`9:16`、ワイドスクリーンには`21:9`を使用します。先頭フレームがある場合、`adaptive`によって画像の比率が維持されます
  </Step>

  <Step title="安定したパブリックストレージにメディアをホストする">
    直リンク防止や期限切れの署名によってメディアのダウンロードが失敗しないよう、独自のオブジェクトストレージやCDNからの直リンクを使用してください
  </Step>

  <Step title="カメラの動きとサウンドを記述する">
    被写体、アクション、カメラの動き、ライティング、希望する音楽や効果音を含めてください。モデルはこれらをまとめて生成します
  </Step>

  <Step title="10秒ごとにポーリングする">
    生成には通常2〜4分かかります。クライアント全体のタイムアウトは15分に設定してください
  </Step>

  <Step title="冪等性は自身で処理する">
    ビジネスIDからtask\_idへのマッピングを保持し、送信がタイムアウトした場合は、再送信する前に既存のタスクを確認してください
  </Step>

  <Step title="動画をすぐに保存する">
    GETで`task.content.url`をダウンロードし、独自のストレージから配信してください
  </Step>
</Steps>

## エラーコードとリトライ

| ステージ | 表示内容 | 原因 | 対処方法 |
| - | - | - | - |
| 送信 | 400、`type: invalid_request`、中国語のメッセージ | 無効なパラメータ（duration、ratio、counts、rolesなど） | パラメータを修正してください。リトライしないでください |
| 送信 | 400、`bad_request_error` | アップストリームで拒否されました（例: `resolution must be 768P`、未対応のフィールドなど） | パラメータを修正してください |
| 送信 | 500、`Unknown Error` | 一部の無効なパラメータ（複数のテキスト項目、`http://`リンク、未知のフィールドなど）または一時的な過負荷 | まず生成モードとリクエストボディを照合して確認してください。問題がなければ、バックオフを設けてリトライしてください |
| 送信 | 503、利用可能なチャネルがありません | Tokenのグループにこのモデルが含まれていないか、`model`のスペルが間違っています | Tokenのグループとモデル名を確認してください |
| 実行 | `status: failed`、`input_download_failed` | メディアURLをダウンロードできません（例: 404） | 公開アクセス可能なリンクに変更して再送信してください |
| 実行 | `status: failed`、`input_format_unsupported` | 誤ったメディア形式（例: 画像スロットに音声） | メディアタイプと形式を確認してください |
| 実行 | `status: failed`、`task_execution_failed` | 生成に失敗しました | 後ほど再送信してください（失敗したタスクは返金済みです） |

<Info>
  **クライアント側のヒント**: 送信タイムアウトを60秒に設定してください（ピーク時は送信だけで10秒以上かかる場合があります）。リトライはバックオフを設けた上で、HTTP 500およびネットワークエラーのみに限定してください。実行ステージでの失敗はすべて自動的に返金され、再送信すると新たに課金が発生します。
</Info>

## よくある質問

<AccordionGroup>
  <Accordion title="JSONではなくWebページが返されるのはなぜですか？">
    パスにプレフィックス`/hailuo`が含まれていません。正しいパスは`/hailuo/v2/video_generation`および`/hailuo/v2/query/video_generation/{task_id}`です。
  </Accordion>

  <Accordion title="2Kまたは1080Pはサポートされていますか？">
    このチャンネルでは`768P`のみサポートしています。公式のMiniMaxモデルは2Kをサポートしていますが、このチャンネルでは提供していません。
  </Accordion>

  <Accordion title="1〜3秒に設定することはできますか？">
    いいえ。`duration`は4から15までの整数です。
  </Accordion>

  <Accordion title="動画に音声はありますか？オフにできますか？">
    すべてのクリップにはステレオオーディオトラックが含まれており、これを無効化するパラメータはありません。不要な場合は、後処理でトラックを削除してください。
  </Accordion>

  <Accordion title="Idempotency-Keyヘッダーによって二重課金を防止できますか？">
    現在は防止できません。同じ`Idempotency-Key`で再送信した場合でも、個別に課金される新しいタスクが作成されます。送信済みのタスクはご自身のアプリケーション側で追跡してください。
  </Accordion>

  <Accordion title="失敗したタスクは課金されますか？">
    いいえ。タスクが`failed`になると自動的に全額返金されます。また、送信時に拒否されたリクエストも課金されません。
  </Accordion>

  <Accordion title="base64やローカルファイルを送信できますか？">
    いいえ。すべてのメディアは公開されているHTTPS URLである必要があります。事前に独自のオブジェクトストレージにアップロードし、そのリンクを渡してください。
  </Accordion>

  <Accordion title="adaptiveではどのようなサイズが生成されますか？">
    入力画像のアスペクト比に従います（例：正方形の画像の場合は768×768、16:9の画像の場合は1344×768）。テキストのみおよび音声のみのリクエストでは`adaptive`を使用できません。
  </Accordion>

  <Accordion title="参照動画が15秒を超えているとエラーになりますか？">
    1つのクリップが15秒を超えている場合は自動的に先頭の15秒にトリミングされますが、複数の参照動画の合計が15秒を超える場合、タスクは失敗します（返金されます）。
  </Accordion>

  <Accordion title="生成にはどのくらいの時間がかかりますか？">
    実測値の中央値は約3分で、通常は2〜4分程度です。10〜15秒のクリップはもう少し時間がかかります。
  </Accordion>

  <Accordion title="動画のURLはどのくらいの期間有効ですか？">
    すぐに有効期限切れになることは確認されていませんが、長期的な可用性は保証されていないため、速やかに動画をダウンロードして保存してください。URLの確認にはGETを使用してください。HEADリクエストは403を返します。
  </Accordion>

  <Accordion title="送信時に500 Unknown Errorが返されることがある場合はどうすればよいですか？">
    まず、リクエストボディがルールに従っていることを確認してください（テキスト項目が厳密に1つのみであること、余分なフィールドがないこと、メディアリンクがhttpsであること）。ルールに従っている場合は通常、一時的な過負荷が原因です。数秒待ってから再試行してください。送信に失敗したリクエストは課金されません。
  </Accordion>
</AccordionGroup>

## 関連ドキュメント

* [MiniMax-H3 動画生成 API リファレンス](/ja/api-capabilities/minimax-h3/video-generation)
* [Seedance 2.0 / 2.5 動画生成](/ja/api-capabilities/seedance2/overview)
* [Wan2.7 動画生成](/ja/api-capabilities/wan/overview)
* [VEO 3.1 動画生成](/ja/api-capabilities/veo-3-1-official/overview)
* [チャージボーナス](/ja/faq/recharge-promotions)