> ## 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.

# Comfy Router で Nano Banana 2 を使う

> Comfy Router 経由で HTTP を使って Nano Banana 2 (Gemini 3.1 Flash Image) で画像を生成するための Python、TypeScript、cURL スニペット、およびリクエストのフィールドと結果の形状

Nano Banana 2 の API リファレンスです。Nano Banana 2（Gemini 3.1 Flash Image）はテキストから画像を生成し、入力画像が指定された場合はその画像を編集します。

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

## クイックスタート

[お使いの 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:** `vertexai/gemini-3.1-flash-image`

**エンドポイント:** `POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image`

> [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(
>             "vertexai/gemini-3.1-flash-image",
>             {
>                 "contents": [
>                     {
>                         "role": "user",
>                         "parts": [
>                             {
>                                 "text": "a single red maple leaf on a plain white background, studio lighting",
>                             },
>                         ],
>                     },
>                 ],
>                 "generationConfig": {
>                     "responseModalities": ["IMAGE"],
>                     "imageConfig": {
>                         "aspectRatio": "1:1",
>                     },
>                 },
>             },
>         )
>
>     print("image (base64):", result["candidates"][0]["content"]["parts"][0]["inlineData"]["data"])
>
> asyncio.run(main())
> ```
>
> ```typescript TypeScript theme={null}
> import { comfy } from "@comfyorg/sdk";
>
> // 環境変数から COMFY_API_KEY を読み取ります。
> // SDK は冪等キーを自動的に作成し、自動リトライのために再利用します。
> type Result = { candidates: { content: { parts: { inlineData: { data: string } }[] } }[] };
> const result = await comfy.models.run<Result>("vertexai/gemini-3.1-flash-image", {
>   contents: [
>     {
>       role: "user",
>       parts: [
>         {
>           text: "a single red maple leaf on a plain white background, studio lighting",
>         },
>       ],
>     },
>   ],
>   generationConfig: {
>     responseModalities: ["IMAGE"],
>     imageConfig: {
>       aspectRatio: "1:1",
>     },
>   },
> });
> if (result.kind !== "json") throw new Error("expected a JSON result");
>
> console.log("image (base64):", result.data.candidates[0].content.parts[0].inlineData.data);
> ```
>
> ```bash cURL theme={null}
> curl https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image \
>   -H "X-API-Key: $COMFY_API_KEY" \
>   -H "Idempotency-Key: $(uuidgen)" \
>   -H "Content-Type: application/json" \
>   -d "{\"contents\": [{\"role\":\"user\",\"parts\":[{\"text\":\"a single red maple leaf on a plain white background, studio lighting\"}]}], \"generationConfig\": {\"responseModalities\":[\"IMAGE\"],\"imageConfig\":{\"aspectRatio\":\"1:1\"}}}"
> ```

> [tab] キューに送信して後で収集する
>
> 同じボディを `POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image/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(
>             "vertexai/gemini-3.1-flash-image",
>             {
>                 "contents": [
>                     {
>                         "role": "user",
>                         "parts": [
>                             {
>                                 "text": "a single red maple leaf on a plain white background, studio lighting",
>                             },
>                         ],
>                     },
>                 ],
>                 "generationConfig": {
>                     "responseModalities": ["IMAGE"],
>                     "imageConfig": {
>                         "aspectRatio": "1:1",
>                     },
>                 },
>             },
>         )
>         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("image (base64):", result["candidates"][0]["content"]["parts"][0]["inlineData"]["data"])
>
> asyncio.run(main())
> ```
>
> ```typescript TypeScript theme={null}
> import { comfy } from "@comfyorg/sdk";
>
> // 環境変数から COMFY_API_KEY を読み取ります。
> // 各 submit() 呼び出しは独自の Idempotency-Key を発行し、自動リトライで再利用します。
> type Result = { candidates: { content: { parts: { inlineData: { data: string } }[] } }[] };
> const handle = await comfy.models.submit<Result>("vertexai/gemini-3.1-flash-image", {
>   contents: [
>     {
>       role: "user",
>       parts: [
>         {
>           text: "a single red maple leaf on a plain white background, studio lighting",
>         },
>       ],
>     },
>   ],
>   generationConfig: {
>     responseModalities: ["IMAGE"],
>     imageConfig: {
>       aspectRatio: "1:1",
>     },
>   },
> });
> 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("image (base64):", result.data.candidates[0].content.parts[0].inlineData.data);
> ```
>
> ```bash cURL theme={null}
> # 1. 送信。Router は request_id、status_url、response_url、cancel_url とともに 201 を返します。
> curl https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image/requests \
>   -H "X-API-Key: $COMFY_API_KEY" \
>   -H "Idempotency-Key: $(uuidgen)" \
>   -H "Content-Type: application/json" \
>   -d "{\"contents\": [{\"role\":\"user\",\"parts\":[{\"text\":\"a single red maple leaf on a plain white background, studio lighting\"}]}], \"generationConfig\": {\"responseModalities\":[\"IMAGE\"],\"imageConfig\":{\"aspectRatio\":\"1:1\"}}}"
>
> # 2. ステータスが COMPLETED になるまでポーリングし、各レスポンスが指定する Retry-After 秒だけ待機します。
> REQUEST_ID="<request_id from the 201 body>"
> curl -i https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image/requests/$REQUEST_ID/status \
>   -H "X-API-Key: $COMFY_API_KEY"
>
> # 3. 収集。モデルのネイティブ出力とともに 200、まだ実行中の場合はステータスボディとともに 202 を返します。
> curl https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image/requests/$REQUEST_ID \
>   -H "X-API-Key: $COMFY_API_KEY"
> ```

## サービングプロバイダー

このモデルは、リクエストで別のプロバイダーが指定されない限り、Comfy Router が直接提供します。以下のプロバイダーも、同じエンドポイントかつ同じモデル ID でこのモデルを提供しており、`model_provider` クエリパラメータで選択します。

* **Comfy**（デフォルト）: `POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image`
* **fal**、`fal/fal-nano-banana-2` として: `POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image?model_provider=fal`
* **MiniMax**、`minimax/minimax-nano-banana-2` として: `POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image?model_provider=minimax`
* **Pika**、`pika/pika-nano-banana-2` として: `POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image?model_provider=pika`
* **Runware**、`runware/runware-nano-banana-2` として: `POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image?model_provider=runware`
* **WaveSpeed**、`wavespeed/wavespeed-nano-banana-2` として: `POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-flash-image?model_provider=wavespeed`

`strict_mode` のデフォルトは false であるため、Router はこのページで説明されているネイティブのリクエストボディをプロバイダー独自のスキーマに変換し、レスポンスを元に戻す変換を行います。API リファレンスの [`model_provider`、`strict_mode`、`fallback_provider`](https://docs.comfy.org/ja/development/comfy-router/reference#post-v2modelsprovidermodel) を参照し、この方法でルーティングされるすべてのモデルについては[サービングプロバイダー](https://docs.comfy.org/ja/development/comfy-router/providers.md)を参照してください。

## スキーマ

### 入力

**contents** `object[]` *required*

モデルとの現在の会話のコンテンツ。単一ターンのクエリでは単一のインスタンスです。マルチターンのクエリでは、会話履歴と最新のリクエストを含む繰り返しフィールドです。

**contents\[].parts** `object[]` *required*

**contents\[].parts\[].fileData** `object`

URI ベースのデータ。

**contents\[].parts\[].fileData.fileUri** `string`

URI

**contents\[].parts\[].fileData.mimeType** `string`

data フィールドまたは fileUri フィールドで指定されたファイルのメディアタイプ。使用可能な値は次のとおりです。gemini-2.0-flash-lite および gemini-2.0-flash では、オーディオファイルの最大長は 8.4 時間、ビデオファイル（オーディオなし）の最大長は 1 時間です。詳細については、Gemini のオーディオとビデオの要件を参照してください。テキストファイルは UTF-8 でエンコードされている必要があります。テキストファイルの内容はトークン制限にカウントされます。画像の解像度に制限はありません。

使用可能な値: `application/pdf`, `audio/mpeg`, `audio/mp3`, `audio/wav`, `image/png`, `image/jpeg`, `image/webp`, `text/plain`, `video/mov`, `video/mpeg`, `video/mp4`, `video/mpg`, `video/avi`, `video/wmv`, `video/mpegps`, `video/flv`, `image/heic`, `image/heif`, `audio/flac`, `video/webm`

**contents\[].parts\[].inlineData** `object`

生バイトのインラインデータ。gemini-2.0-flash-lite および gemini-2.0-flash では、inlineData を使用して最大 3000 枚の画像を指定できます。

**contents\[].parts\[].inlineData.data** `string (byte)`

プロンプトにインラインで含める画像、PDF、またはビデオの base64 エンコーディング。メディアをインラインで含める場合は、データのメディアタイプ（mimeType）も指定する必要があります。サイズ制限: 20MB

形式: `byte`

**contents\[].parts\[].inlineData.mimeType** `string`

data フィールドまたは fileUri フィールドで指定されたファイルのメディアタイプ。使用可能な値は次のとおりです。gemini-2.0-flash-lite および gemini-2.0-flash では、オーディオファイルの最大長は 8.4 時間、ビデオファイル（オーディオなし）の最大長は 1 時間です。詳細については、Gemini のオーディオとビデオの要件を参照してください。テキストファイルは UTF-8 でエンコードされている必要があります。テキストファイルの内容はトークン制限にカウントされます。画像の解像度に制限はありません。

使用可能な値: `application/pdf`, `audio/mpeg`, `audio/mp3`, `audio/wav`, `image/png`, `image/jpeg`, `image/webp`, `text/plain`, `video/mov`, `video/mpeg`, `video/mp4`, `video/mpg`, `video/avi`, `video/wmv`, `video/mpegps`, `video/flv`, `image/heic`, `image/heif`, `audio/flac`, `video/webm`

**contents\[].parts\[].mediaProcessing** `string`

モデルがこのパートのビデオを読み取る方法。"AGENTIC" を設定すると、固定レートのフレームサンプリングの代わりに、モデルが検査するセグメントを決定できます。省略すると、デフォルトの固定レートサンプリングになります。gemini-3.7-flash 以降の Flash モデルでサポートされています。

**contents\[].parts\[].text** `string`

テキストプロンプトまたはコードスニペット。

**contents\[].parts\[].thought** `boolean`

このパートがモデルからの思考/推論ステップであることを示します。

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

使用可能な値: `user`, `model`

**generationConfig** `object`

生成のサンプリング、長さ、出力の設定。すべてのフィールドはオプションです。以下で `default` を宣言しているフィールドは省略時にそれを適用し、残りはモデル自身の動作にフォールバックします。

**generationConfig.imageConfig** `object`

画像生成の設定

**generationConfig.imageConfig.aspectRatio** `string`

生成画像のアスペクト比

**generationConfig.imageConfig.imageOutputOptions** `object`

オプション。生成画像の出力形式。

**generationConfig.imageConfig.imageOutputOptions.compressionQuality** `integer`

オプション。出力画像の圧縮品質。

**generationConfig.imageConfig.imageOutputOptions.mimeType** `string`

オプション。出力を保存する画像形式。Vertex AI の経路、つまり Comfy 自身の認証情報で処理されるリクエスト、および GCP サービスアカウントで認証された BYOK リクエストで使用されます。そこで受け入れられる値は `image/png` と `image/jpeg` で、大文字と小文字を区別せずに照合され、リクエストが転送される前に小文字に正規化されます。それ以外の値は、このフィールド名を含む 400 エラーで拒否されます。省略時は `image/png` がデフォルトです。Google AI Studio の APIキーで認証された BYOK リクエストは例外です。その上流にはそのようなプロパティがなく、存在する場合は呼び出し全体を拒否するため、このフィールドは尊重されたり拒否されたりするのではなくリクエストから削除され、出力形式は AI Studio が選択するものになります。どの経路でも、送信した値を仮定するのではなく、受け取ったレスポンスのパートからメディアタイプを読み戻してください（`inlineData.mimeType`、または `uploadImagesToStorage` が設定されている場合は `fileData.mimeType`）。

**generationConfig.imageConfig.imageSize** `string`

オプション。生成画像のサイズを指定します。サポートされる値は 1K、2K、4K です。指定しない場合、モデルはデフォルト値 1K を使用します。

**generationConfig.maxOutputTokens** `integer`

レスポンスで生成できるトークンの最大数。トークンは約 4 文字です。100 トークンはおよそ 60-80 語に相当します。

範囲: `16` ～ `65536`

**generationConfig.responseModalities** \`\`TEXT`, `IMAGE`[]`

**generationConfig.seed** `integer`

シードを特定の値に固定すると、モデルは繰り返しのリクエストに対して同じ応答を返せるよう最善を尽くします。決定的な出力は保証されません。また、temperature などのモデルやパラメータ設定を変更すると、同じシード値を使用していても応答にばらつきが生じることがあります。デフォルトでは、ランダムなシード値が使用されます。次のモデルで利用できます: gemini-2.5-flash, gemini-2.5-pro, gemini-2.5-flash-preview-04-1, gemini-2.5-pro-preview-05-0, gemini-2.0-flash-lite-00, gemini-2.0-flash-001

**generationConfig.stopSequences** `string[]`

**generationConfig.temperature** `number` (default: 1)

temperature は、topP と topK が適用される応答生成時のサンプリングに使用されます。temperature は、トークン選択におけるランダム性の度合いを制御します。低い temperature は、あまり自由奔放でない回答や創造性を必要としないプロンプトに適しており、高い temperature はより多様な、または創造的な結果につながります。temperature が 0 の場合、常に最も確率の高いトークンが選択されます。この場合、特定のプロンプトに対する応答はほぼ決定的になりますが、少量のばらつきは依然として発生する可能性があります。モデルの応答が一般的すぎる、短すぎる、またはフォールバック応答が返される場合は、temperature を上げてみてください。

範囲: `0` から `2`

形式: `float`

**generationConfig.thinkingConfig** `object`

オプション。思考機能の設定です。思考とは、モデルが複雑なタスクをより小さなステップに分解し、より高品質な応答を生成するプロセスです。

**generationConfig.thinkingConfig.includeThoughts** `boolean`

オプション。true の場合、モデルは応答に自身の思考を含めます。

**generationConfig.thinkingConfig.thinkingBudget** `integer`

オプション。モデルの思考プロセスに割り当てるトークン予算です。モデルはこの予算内に収まるよう最善を尽くします。

**generationConfig.thinkingConfig.thinkingLevel** `string`

オプション。モデルの思考レベルです。

指定可能な値: `THINKING_LEVEL_UNSPECIFIED`、`LOW`、`MEDIUM`、`HIGH`、`MINIMAL`、`XHIGH`

**generationConfig.topK** `integer` (default: 40)

Top-K は、モデルが出力のためにトークンを選択する方法を変更します。Top-K が 1 の場合、次に選択されるトークンはモデルの語彙内のすべてのトークンの中で最も確率の高いものになります。Top-K が 3 の場合、次に選択されるトークンは、temperature を使用して確率の高い上位 3 つのトークンの中から選択されます。

範囲: `1` から `…`

**generationConfig.topP** `number` (default: 0.95)

指定した場合、nucleus サンプリングが使用されます。
Top-P は、モデルが出力のためにトークンを選択する方法を変更します。トークンは、その確率の合計が top-P の値に等しくなるまで、最も確率の高いもの (top-K を参照) から最も低いものへと選択されます。たとえば、トークン A、B、C の確率がそれぞれ 0.3、0.2、0.1 で、top-P の値が 0.5 の場合、モデルは temperature を使用して A または B のいずれかを次のトークンとして選択し、C は候補から除外されます。
ランダム性の低い応答には低い値を、ランダム性の高い応答には高い値を指定してください。

範囲: `0` から `1`

形式: `float`

**safetySettings** `object[]`

安全でないコンテンツをブロックするためのリクエストごとの設定です。GenerateContentResponse.candidates に対して適用されます。

**safetySettings\[].category** `string` *required*

指定可能な値: `HARM_CATEGORY_SEXUALLY_EXPLICIT`、`HARM_CATEGORY_HATE_SPEECH`、`HARM_CATEGORY_HARASSMENT`、`HARM_CATEGORY_DANGEROUS_CONTENT`

**safetySettings\[].threshold** `string` *required*

指定可能な値: `OFF`、`BLOCK_NONE`、`BLOCK_LOW_AND_ABOVE`、`BLOCK_MEDIUM_AND_ABOVE`、`BLOCK_ONLY_HIGH`

**systemInstruction** `object`

モデルのパフォーマンスを向上させるための指示です。たとえば、「できるだけ簡潔に回答してください」や「回答に専門用語を使わないでください」などです。テキスト文字列はトークン上限にカウントされます。systemInstruction の role フィールドは無視され、モデルのパフォーマンスには影響しません。注: parts にはテキストのみを使用し、各 part 内のコンテンツは個別の段落にしてください。

**systemInstruction.parts** `object[]` *required*

1 つのメッセージを構成する順序付けされた part のリストです。part ごとに異なる IANA MIME タイプを指定できます。トークンの最大数や画像の数などの入力の制限については、Google のモデルページにあるモデルの仕様を参照してください。

**systemInstruction.parts\[].text** `string`

テキストプロンプトまたはコードスニペット。

**systemInstruction.role** `string`

メッセージを作成するエンティティの識別子です。次の値がサポートされています: user: メッセージが実在の人物によって送信されたことを示します。通常はユーザーが生成したメッセージです。model: メッセージがモデルによって生成されたことを示します。model の値は、マルチターンの会話中にモデルからのメッセージを会話に挿入するために使用されます。マルチターンでない会話では、このフィールドは空のままにするか、未設定にできます。

指定可能な値: `user`、`model`

**tools** `object[]`

システムがモデルの知識と範囲外のアクションまたはアクション群を実行するために、外部システムと連携できるようにするコードです。関数呼び出しを参照してください。

**tools\[].functionDeclarations** `object[]`

**tools\[].functionDeclarations\[].description** `string`

**tools\[].functionDeclarations\[].name** `string` *required*

**tools\[].functionDeclarations\[].parameters** `object`

関数パラメータの JSON スキーマ

**uploadImagesToStorage** `boolean`

true の場合、生成済みの画像はクラウドストレージにアップロードされ、インラインの base64 データではなく署名付き URL として返されます。URL は 24 時間後に失効します。

**videoMetadata** `object`

ビデオ入力の場合、ビデオの開始と終了のオフセットを Duration 形式で指定します。たとえば、1:00 から始まる 10 秒のクリップを指定するには、"startOffset": \{ "seconds": 60 } と "endOffset": \{ "seconds": 70 } を設定します。メタデータは、ビデオデータが inlineData または fileData で提供されている場合にのみ指定してください。

**videoMetadata.endOffset** `object`

ビデオのタイムライン位置に対する再生時間オフセットを表します。

**videoMetadata.endOffset.nanos** `integer`

ナノ秒精度の符号付き秒未満の端数。小数を含む負の秒値であっても、nanos 値は非負である必要があります。

範囲: `0` \~ `999999999`

**videoMetadata.endOffset.seconds** `integer`

時間幅の符号付き秒数。-315,576,000,000 から +315,576,000,000 まで（両端を含む）である必要があります。

範囲: `-315576000000` \~ `315576000000`

**videoMetadata.startOffset** `object`

ビデオのタイムライン位置に対する再生時間オフセットを表します。

**videoMetadata.startOffset.nanos** `integer`

ナノ秒精度の符号付き秒未満の端数。小数を含む負の秒値であっても、nanos 値は非負である必要があります。

範囲: `0` \~ `999999999`

**videoMetadata.startOffset.seconds** `integer`

時間幅の符号付き秒数。-315,576,000,000 から +315,576,000,000 まで（両端を含む）である必要があります。

範囲: `-315576000000` \~ `315576000000`

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

### 出力

**candidates** `object[]`

**candidates\[].citationMetadata** `object`

**candidates\[].citationMetadata.citations** `object[]`

**candidates\[].citationMetadata.citations\[].authors** `string[]`

**candidates\[].citationMetadata.citations\[].endIndex** `integer`

**candidates\[].citationMetadata.citations\[].license** `string`

**candidates\[].citationMetadata.citations\[].publicationDate** `string (date)`

形式: `date`

**candidates\[].citationMetadata.citations\[].startIndex** `integer`

**candidates\[].citationMetadata.citations\[].title** `string`

**candidates\[].citationMetadata.citations\[].uri** `string`

**candidates\[].content** `object`

モデルとの現在の会話のコンテンツ。単一ターンのクエリでは単一のインスタンスです。マルチターンのクエリでは、会話履歴と最新のリクエストを含む繰り返しフィールドです。

**candidates\[].content.parts** `object[]` *required*

**candidates\[].content.parts\[].fileData** `object`

URIベースのデータ。

**candidates\[].content.parts\[].fileData.fileUri** `string`

URI

**candidates\[].content.parts\[].fileData.mimeType** `string`

dataフィールドまたはfileUriフィールドで指定されたファイルのメディアタイプ。許容される値は次のとおりです。gemini-2.0-flash-liteおよびgemini-2.0-flashでは、オーディオファイルの最大長は8.4時間、ビデオファイル（オーディオなし）の最大長は1時間です。詳細については、Geminiのオーディオとビデオの要件を参照してください。テキストファイルはUTF-8でエンコードされている必要があります。テキストファイルの内容はトークン制限にカウントされます。画像の解像度に制限はありません。

指定可能な値: `application/pdf`, `audio/mpeg`, `audio/mp3`, `audio/wav`, `image/png`, `image/jpeg`, `image/webp`, `text/plain`, `video/mov`, `video/mpeg`, `video/mp4`, `video/mpg`, `video/avi`, `video/wmv`, `video/mpegps`, `video/flv`, `image/heic`, `image/heif`, `audio/flac`, `video/webm`

**candidates\[].content.parts\[].inlineData** `object`

生のバイトデータによるインラインデータ。gemini-2.0-flash-liteおよびgemini-2.0-flashでは、inlineDataを使用して最大3000枚の画像を指定できます。

**candidates\[].content.parts\[].inlineData.data** `string (byte)`

プロンプトにインラインで含める画像、PDF、またはビデオのbase64エンコード。メディアをインラインで含める場合は、データのメディアタイプ（mimeType）も指定する必要があります。サイズ制限: 20MB

形式: `byte`

**candidates\[].content.parts\[].inlineData.mimeType** `string`

dataフィールドまたはfileUriフィールドで指定されたファイルのメディアタイプ。許容される値は次のとおりです。gemini-2.0-flash-liteおよびgemini-2.0-flashでは、オーディオファイルの最大長は8.4時間、ビデオファイル（オーディオなし）の最大長は1時間です。詳細については、Geminiのオーディオとビデオの要件を参照してください。テキストファイルはUTF-8でエンコードされている必要があります。テキストファイルの内容はトークン制限にカウントされます。画像の解像度に制限はありません。

指定可能な値: `application/pdf`, `audio/mpeg`, `audio/mp3`, `audio/wav`, `image/png`, `image/jpeg`, `image/webp`, `text/plain`, `video/mov`, `video/mpeg`, `video/mp4`, `video/mpg`, `video/avi`, `video/wmv`, `video/mpegps`, `video/flv`, `image/heic`, `image/heif`, `audio/flac`, `video/webm`

**candidates\[].content.parts\[].mediaProcessing** `string`

モデルがこのパートのビデオを読み取る方法。"AGENTIC"を設定すると、固定レートのフレームサンプリングではなく、モデルが検査するセグメントを決定できます。省略すると、デフォルトの固定レートサンプリングになります。gemini-3.7-flash以降のFlashモデルでサポートされています。

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

テキストプロンプトまたはコードスニペット。

**candidates\[].content.parts\[].thought** `boolean`

このパートがモデルからの思考/推論ステップであることを示します。

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

指定可能な値: `user`, `model`

**candidates\[].finishReason** `string`

**candidates\[].safetyRatings** `object[]`

**candidates\[].safetyRatings\[].category** `string`

指定可能な値: `HARM_CATEGORY_SEXUALLY_EXPLICIT`, `HARM_CATEGORY_HATE_SPEECH`, `HARM_CATEGORY_HARASSMENT`, `HARM_CATEGORY_DANGEROUS_CONTENT`

**candidates\[].safetyRatings\[].probability** `string`

コンテンツが指定された安全性カテゴリに違反する確率

指定可能な値: `NEGLIGIBLE`, `LOW`, `MEDIUM`, `HIGH`, `UNKNOWN`

**createTime** `string`

レスポンスが作成されたタイムスタンプ。

**modelVersion** `string`

レスポンスの生成に使用されたモデルのバージョン。

**promptFeedback** `object`

**promptFeedback.blockReason** `string`

**promptFeedback.blockReasonMessage** `string`

**promptFeedback.safetyRatings** `object[]`

**promptFeedback.safetyRatings\[].category** `string`

指定可能な値: `HARM_CATEGORY_SEXUALLY_EXPLICIT`, `HARM_CATEGORY_HATE_SPEECH`, `HARM_CATEGORY_HARASSMENT`, `HARM_CATEGORY_DANGEROUS_CONTENT`

**promptFeedback.safetyRatings\[].probability** `string`

コンテンツが指定された安全カテゴリに違反する確率

指定可能な値: `NEGLIGIBLE`, `LOW`, `MEDIUM`, `HIGH`, `UNKNOWN`

**responseId** `string`

レスポンスの一意の識別子。

**usageMetadata** `object`

**usageMetadata.cachedContentTokenCount** `integer`

出力専用。入力のキャッシュ部分（キャッシュされたコンテンツ）内のトークン数。

**usageMetadata.candidatesTokenCount** `integer`

レスポンス内のトークン数。

**usageMetadata.candidatesTokensDetails** `object[]`

モダリティ別の候補トークンの内訳。

**usageMetadata.candidatesTokensDetails\[].modality** `string`

入力コンテンツまたは出力コンテンツのモダリティのタイプ。

指定可能な値: `MODALITY_UNSPECIFIED`, `TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `DOCUMENT`

**usageMetadata.candidatesTokensDetails\[].tokenCount** `integer`

指定されたモダリティのトークン数。

**usageMetadata.promptTokenCount** `integer`

リクエスト内のトークン数。cachedContent が設定されている場合でも、これはキャッシュされたコンテンツ内のトークン数を含む、有効なプロンプトサイズの合計です。

**usageMetadata.promptTokensDetails** `object[]`

モダリティ別のプロンプトトークンの内訳。

**usageMetadata.promptTokensDetails\[].modality** `string`

入力コンテンツまたは出力コンテンツのモダリティのタイプ。

指定可能な値: `MODALITY_UNSPECIFIED`, `TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `DOCUMENT`

**usageMetadata.promptTokensDetails\[].tokenCount** `integer`

指定されたモダリティのトークン数。

**usageMetadata.thoughtsTokenCount** `integer`

thoughts 出力に含まれるトークン数。

**usageMetadata.toolUsePromptTokenCount** `integer`

ツール使用プロンプトに含まれるトークン数。

**usageMetadata.toolUsePromptTokensDetails** `object[]`

モダリティ別のツール使用プロンプトトークンの内訳。

**usageMetadata.toolUsePromptTokensDetails\[].modality** `string`

入力コンテンツまたは出力コンテンツのモダリティのタイプ。

指定可能な値: `MODALITY_UNSPECIFIED`, `TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `DOCUMENT`

**usageMetadata.toolUsePromptTokensDetails\[].tokenCount** `integer`

指定されたモダリティのトークン数。

**usageMetadata.totalTokenCount** `integer`

トークンの合計数（プロンプト + 候補）。

**usageMetadata.trafficType** `string`

リクエストに使用されたトラフィックタイプ（例: PROVISIONED\_THROUGHPUT）。

## 例

### 入力

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "a single red maple leaf on a plain white background, studio lighting"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ],
    "imageConfig": {
      "aspectRatio": "1:1"
    }
  }
}
```

### 出力

```json theme={null}
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "PGJhc2U2ND4="
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 1290
  }
}
```

デフォルトでは、生成済み画像の part には `inlineData.data` に base64 バイトデータが、`inlineData.mimeType` にメディアタイプが含まれます。バイトデータをデコードしてファイルに保存してください。`uploadImagesToStorage: true` を指定した場合、アップロードされた画像は代わりに、署名付き URL に `fileData.fileUri`、メディアタイプに `fileData.mimeType` を使用します。これらの画像は、URL が作成されてから 24 時間後に失効するため、失効する前にダウンロードしてください。アップロードに失敗すると、その画像はインラインのまま残ります。そのため、各 part に `inlineData` または `fileData` が含まれているかを確認してください。テキストの part も含まれる場合があり、画像が必ず最初の part であるとは限りません。上記のクイックスタートのサンプルにある `candidates[0].content.parts[0].inlineData.data` というパスは、このページのサンプルレスポンスにある単一のインライン part を読み取るものです。実際のレスポンスに対しては、位置 0 を指定するのではなく、`parts` をスキャンして目的のキーを探してください。

## 出荷前の確認

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.