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

# MiniMax H3 を Comfy Router で使用する

> Comfy Router 経由で minimax/minimax-h3 を呼び出します。エンドポイント、リクエストの形状、Router が返すネイティブステレオ音声付き MP4 について説明します。

`minimax/minimax-h3` の API リファレンスです。MiniMax H3（Hailuo 03）はオムニモーダルな動画モデルで、1 回の生成で映像と音声トラックを同時に出力するため、完成したクリップにはセリフ、効果音、音楽がそのまま含まれます。

**入力：** テキスト, 画像 · **出力：** ビデオ + オーディオ

## クイックスタート

[Comfy ワークスペース](https://platform.comfy.org/profile/api-keys?onboarding=router)でキーを作成し、`COMFY_API_KEY` としてエクスポートします。Python と TypeScript のスニペットは Comfy SDK (`pip install comfy-sdk` と `npm install @comfyorg/sdk`) を使用しています。cURL のスニペットは、同じ呼び出しを生の HTTP で行うものです。

**モデル ID:** `minimax/minimax-h3`

**エンドポイント:** `POST https://api.comfy.org/v2/models/minimax/minimax-h3`

> [tab] 結果を待つ
>
> ```python Python theme={null}
> import asyncio
> from comfy_sdk import AsyncComfy
>
> # 環境変数から COMFY_API_KEY を読み取ります。
> # SDK は自動的に冪等キーを作成し、自動リトライ時に再利用します。
> async def main():
>     async with AsyncComfy() as client:
>         result = await client.models.run(
>             "minimax/minimax-h3",
>             {
>                 "content": [
>                     {
>                         "text": "A single red maple leaf resting on a plain white background.",
>                         "type": "text",
>                     },
>                 ],
>                 "duration": 5,
>                 "ratio": "16:9",
>                 "resolution": "768P",
>             },
>         )
>
>     print("video:", result["task"]["content"]["url"])
>
> asyncio.run(main())
> ```
>
> ```typescript TypeScript theme={null}
> import { comfy } from "@comfyorg/sdk";
>
> // 環境変数から COMFY_API_KEY を読み取ります。
> // SDK は自動的に冪等キーを作成し、自動リトライ時に再利用します。
> type Result = { task: { content: { url: string } } };
> const result = await comfy.models.run<Result>("minimax/minimax-h3", {
>   content: [
>     {
>       text: "A single red maple leaf resting on a plain white background.",
>       type: "text",
>     },
>   ],
>   duration: 5,
>   ratio: "16:9",
>   resolution: "768P",
> });
> if (result.kind !== "json") throw new Error("expected a JSON result");
>
> console.log("video:", result.data.task.content.url);
> ```
>
> ```bash cURL theme={null}
> curl https://api.comfy.org/v2/models/minimax/minimax-h3 \
>   -H "X-API-Key: $COMFY_API_KEY" \
>   -H "Idempotency-Key: $(uuidgen)" \
>   -H "Content-Type: application/json" \
>   -d "{\"content\": [{\"text\":\"A single red maple leaf resting on a plain white background.\",\"type\":\"text\"}], \"duration\": 5, \"ratio\": \"16:9\", \"resolution\": \"768P\"}"
> ```

> [tab] キューに送信して後で収集
>
> 同じボディを `POST https://api.comfy.org/v2/models/minimax/minimax-h3/requests` に送信します。Router は実行が受け付けられ次第 `201` と `request_id` を返し、結果は準備が整った時点で、このプロセスからでも別のプロセスからでも取得できます。ステータス、キャンセル、結果の取得の詳細は [キュー配信](https://docs.comfy.org/ja/development/comfy-router/queue.md) を参照してください。
>
> ```python Python theme={null}
> import asyncio
> from comfy_sdk import AsyncComfy
>
> # 環境変数から COMFY_API_KEY を読み取ります。
> # 各 submit() 呼び出しは独自の Idempotency-Key を発行し、自動リトライのために再利用します。
> async def main():
>     async with AsyncComfy() as client:
>         handle = await client.models.submit(
>             "minimax/minimax-h3",
>             {
>                 "content": [
>                     {
>                         "text": "A single red maple leaf resting on a plain white background.",
>                         "type": "text",
>                     },
>                 ],
>                 "duration": 5,
>                 "ratio": "16:9",
>                 "resolution": "768P",
>             },
>         )
>         print("request_id:", handle.request_id)  # モデル ID と合わせて、別のプロセスに必要なものはこれだけです
>
>         # リクエストが完了するまでポーリングし、サーバーが指定する Retry-After の時間だけ待機します。
>         async for update in handle.iter_events():
>             print(update.status, update.queue_position)
>
>         # プロバイダー自身のペイロードで、models.run() が返す値と同じです。
>         # 失敗またはキャンセル済みのリクエストは、ここで型付きの Router エラーを送出します。
>         result = await handle.get()
>
>     print("video:", result["task"]["content"]["url"])
>
> asyncio.run(main())
> ```
>
> ```typescript TypeScript theme={null}
> import { comfy } from "@comfyorg/sdk";
>
> // 環境変数から COMFY_API_KEY を読み取ります。
> // 各 submit() 呼び出しは独自の Idempotency-Key を発行し、自動リトライのために再利用します。
> type Result = { task: { content: { url: string } } };
> const handle = await comfy.models.submit<Result>("minimax/minimax-h3", {
>   content: [
>     {
>       text: "A single red maple leaf resting on a plain white background.",
>       type: "text",
>     },
>   ],
>   duration: 5,
>   ratio: "16:9",
>   resolution: "768P",
> });
> console.log("requestId:", handle.requestId); // モデル ID と合わせて、別のプロセスに必要なものはこれだけです
>
> // リクエストが完了するまでポーリングし、サーバーが指定する Retry-After の時間だけ待機します。
> for await (const update of handle.events()) {
>   console.log(update.status, update.queuePosition);
> }
>
> // models.run() が返すのと同じ結果です。失敗またはキャンセル済みのリクエストは、ここで reject されます。
> const result = await handle.get();
> if (result.kind !== "json") throw new Error("expected a JSON result");
>
> console.log("video:", result.data.task.content.url);
> ```
>
> ```bash cURL theme={null}
> # 1. 送信。Router は request_id、status_url、response_url、cancel_url を含む 201 を返します。
> curl https://api.comfy.org/v2/models/minimax/minimax-h3/requests \
>   -H "X-API-Key: $COMFY_API_KEY" \
>   -H "Idempotency-Key: $(uuidgen)" \
>   -H "Content-Type: application/json" \
>   -d "{\"content\": [{\"text\":\"A single red maple leaf resting on a plain white background.\",\"type\":\"text\"}], \"duration\": 5, \"ratio\": \"16:9\", \"resolution\": \"768P\"}"
>
> # 2. ステータスが COMPLETED になるまでポーリングし、各レスポンスが指定する Retry-After 秒だけ待機します。
> REQUEST_ID="<request_id from the 201 body>"
> curl -i https://api.comfy.org/v2/models/minimax/minimax-h3/requests/$REQUEST_ID/status \
>   -H "X-API-Key: $COMFY_API_KEY"
>
> # 3. 収集。モデルのネイティブ出力とともに 200、まだ実行中はステータスボディとともに 202。
> curl https://api.comfy.org/v2/models/minimax/minimax-h3/requests/$REQUEST_ID \
>   -H "X-API-Key: $COMFY_API_KEY"
> ```

## スキーマ

### 入力

**aigc\_watermark** `boolean`

出力に AIGC ウォーターマークを追加するかどうか。デフォルトは false。

**callback\_url** `string`

任意。チャレンジ検証後にタスクの状態変化を受け取る URL。

**content** `object[]` *required*

生成を駆動するコンテンツ項目。空でないテキスト項目を 1 つ含める必要があります。任意で first\_frame/last\_frame の画像や reference\_\* メディアを追加できます。

**content\[].audio\_url** `object`

オーディオソース。audio\_url 項目では必須です。

**content\[].audio\_url.url** `string`

一般に公開された URL、mm\_file://\{file\_id} 参照、またはデータ URI。

**content\[].image\_url** `object`

画像ソース。image\_url 項目では必須です。

**content\[].image\_url.url** `string`

一般に公開された URL、mm\_file://\{file\_id} 参照、またはデータ URI。

**content\[].role** `string`

メディア項目の役割。オプション: first\_frame、last\_frame、reference\_image、reference\_video、reference\_audio、base\_video。キーフレームの役割と reference\_\* の役割は 1 つのリクエスト内で同時に使用できません。base\_video はビデオ再生成リクエストのソースビデオを示します。

**content\[].text** `string`

プロンプトテキスト。リクエストごとに空でないテキスト項目がちょうど 1 つ必要です。

**content\[].type** `string` *required*

コンテンツ項目のタイプ。オプション: text、image\_url、video\_url、audio\_url。

**content\[].video\_url** `object`

ビデオソース。video\_url 項目では必須です。

**content\[].video\_url.url** `string`

一般に公開された URL、mm\_file://\{file\_id} 参照、またはデータ URI。

**duration** `integer` *required*

ビデオの長さ（秒）。Comfy Router は 4 から 15 を受け付け、それ以外の値はプロバイダーが呼び出される前に拒否します。このモデルに関する MiniMax 自身のドキュメントには 5 から 15 と記載されていますが、ComfyUI MiniMax H3 ノードは 4 から 15 を提供しており、4 秒の生成が成功することも確認されているため、ここでは 4 が受け付けられます。

範囲: `4` から `15`

**model** `string`

モデルの ID。オプション: MiniMax-H3。Router の呼び出し元はこのフィールドを省略するか null を送信できます。Router はプロバイダーへのディスパッチ前に、リクエストパスで選択されたモデルを注入します。

**ratio** `string`

アスペクト比。オプション: adaptive（デフォルト）、21:9、16:9、4:3、1:1、3:4、9:16。テキストから動画への生成では必須で、adaptive にすることはできません。first-frame または last-frame の生成では無視されます（adaptive として扱われます）。

**resolution** `string` *required*

ビデオの解像度。オプション: 2K、768P。値は大文字と小文字を区別せずに照合され、ディスパッチ前に正規化されるため、`2k` と `768p` も受け付けられ、`2K` と `768P` として送信されます。

指定可能な値: `2K`, `2k`, `768P`, `768p`

**seed** `integer`

\[-1, 2^32 - 1] の範囲のランダムシード。省略するか -1 を指定するとランダムになります。

形式: `int64`

`GET /v2/models/minimax/minimax-h3/openapi.json` で Router が提供するスキーマから生成されています。これは、リクエストがプロバイダーに到達する前に Router が呼び出しの検証に使用するドキュメントと同じものです。

### 出力

**task** `object`

Minimax V2 のビデオ生成タスク。

**task.content** `object`

生成済みの出力。status が succeeded の場合に存在します。

**task.content.prompt** `string`

succeeded になった h3\_context\_ir タスクによって生成された拡張ビデオプロンプト。

**task.content.url** `string`

生成済み MP4 の期限付き URL。再度クエリすると URL を更新できます。

**task.duration** `number`

生成済みビデオの再生時間（秒）。

**task.error** `object`

status が failed の場合のエラー詳細。code と message を含みます。

**task.id** `string`

タスク ID。

**task.model** `string`

タスクで使用されたモデル。

**task.ratio** `string`

生成済みビデオの実際の比率。

**task.resolution** `string`

生成済みビデオの解像度。

**task.status** `string`

タスクのステータス。オプション: queued、running、succeeded、failed、cancelled、expired。

**task.task\_type** `string`

タスクのタイプ。

**task.usage** `object`

タスクで記録された使用量。

**task.usage.completion\_tokens** `integer`

**task.usage.input\_image\_count** `integer`

**task.usage.input\_seconds** `number`

**task.usage.output\_seconds** `number`

**task.usage.prompt\_tokens** `integer`

**task.usage.total\_seconds** `number`

**task.usage.total\_tokens** `integer`

## 例

### 入力

```json theme={null}
{
  "content": [
    {
      "text": "A single red maple leaf resting on a plain white background.",
      "type": "text"
    }
  ],
  "duration": 5,
  "ratio": "16:9",
  "resolution": "768P"
}
```

### 出力

```json theme={null}
{
  "task": {
    "content": {
      "url": "https://example.invalid/minimax/minimax-h3/generated.mp4"
    },
    "duration": 6,
    "id": "3f7a1b28-5c0d-4e91-8a6f-1b2c3d4e5f60",
    "model": "MiniMax-H3",
    "ratio": "16:9",
    "resolution": "768P",
    "status": "succeeded",
    "usage": {
      "output_seconds": 6,
      "total_seconds": 6
    }
  }
}
```

**MP4 には生成された音声トラックが含まれます。** H3 はオムニモーダルです。音声、サウンドエフェクト、音楽は、後から重ね合わせるのではなく、映像とまとめて単一のフォワードパスで合成され、その結果はネイティブステレオオーディオを持つ 1 つの MP4 になります。上記のリクエストボディでこれを無効にするものはありません。記載されているフィールドはプロンプトのコンテンツ、`duration`、`ratio`、`resolution`、`seed`、`aigc_watermark`、`callback_url` であり、いずれも無音レンダリングを選択するものではありません。したがって、独自のナレーションをクリップに重ねることを意図したパイプラインは、まず返されたトラックをミュートするか取り除く必要があります。そうしなければ、すでに音声が入っているクリップの上に多重化してしまいます。オーディオを方向づけるのはプロンプトです。セリフ、サウンドエフェクト、音楽は、ショットと同じプロンプトブロックに記述してください。プロンプトの構成方法については [MiniMax H3 プロンプトガイド](https://docs.comfy.org/ja/tutorials/video/minimax/minimax-h3-prompt-guide.md) を、ComfyUI でこのモデルが何をするかについては [MiniMax H3 の概要](https://docs.comfy.org/ja/tutorials/video/minimax/minimax-h3.md) を参照してください。

ビデオ URL には有効期限があります。Router は MP4 を再ホストし、12 時間有効な Comfy 署名付き URL を返します。再ホストに失敗した場合は、MiniMax 自身のより短い有効期間のリンクにフォールバックします。上記のレスポンススキーマにある `task.content.url` の説明は、URL を更新するために再度クエリするよう案内しています。それは MiniMax 自身の API 向けの表現をそのまま引き継いだもので、Router は MiniMax のタスククエリルートを公開していません。キューに登録されたリクエストの結果ルートを再度読み取ると、そのリクエストが[完了後 24 時間保持されている](https://docs.comfy.org/ja/development/comfy-router/queue.md#冪等性と課金)間は保存された結果ドキュメントが返されますが、その読み取りによって新たに署名された URL が発行されることを記述した箇所はありません。リンクを保存するのではなく、MP4 を速やかにダウンロードしてください。

## 出荷前の確認

SDK は `Idempotency-Key` を生成し、自動リトライで再利用します。手動リトライでは元のキーを再利用してください。Router は最大 10 分間接続を保持できます。

リクエストが失敗すると、Router は理由を説明する `X-Comfy-Error-Type` レスポンスヘッダーを送信します。`422` は、プロバイダーを呼び出す前に Router が入力を拒否したことを意味し、`413` はリクエスト本文が Router の受け入れ可能なサイズを超えていたことを意味します。生成されたアセットは [結果 URL の有効期限](https://docs.comfy.org/ja/development/comfy-router/reference.md#結果アセット) があるため、早めにダウンロードしてください。

上記のフィールド説明に記載されているサイズ制限は、プロバイダーの仕様から引用した、そのフィールドに対するプロバイダー自身の上限です。Router はリクエスト本文全体に対して別の上限を適用し、base64 エンコードされたメディアもこれにカウントされます。[リクエスト本文のサイズ](https://docs.comfy.org/ja/development/comfy-router/limitations.md) を参照してください。

このページは、Comfy Router 経由で呼び出す 1 つのパートナーモデルについて説明しています。同じ `comfy-sdk` / `@comfyorg/sdk` パッケージには、Comfy Cloud 上で ComfyUI のワークフローグラフ全体を実行するための 2 つ目のクライアントも含まれています: `Comfy(api_key=...)` / `new Comfy({ apiKey })`、および `client.workflows`、`client.assets`、`client.jobs`。[Comfy SDKs](https://docs.comfy.org/ja/development/api-development/sdks.md) を参照してください。

> [card] [ヘッダー](https://docs.comfy.org/ja/development/comfy-router/headers.md)
>
> 認証、冪等性、リクエスト ID、エラー分類、リトライ間隔、支出上限。

> [card] [Router API の利用](https://docs.comfy.org/ja/development/comfy-router/api.md)
>
> モデルの検出、バリデーションエラー、リトライ、課金。

> [card] [制限事項](https://docs.comfy.org/ja/development/comfy-router/limitations.md)
>
> Router が現在対応していないことと、代替手段。


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