クイックスタート
お使いの Comfy ワークスペースでキーを作成し、COMFY_API_KEY としてエクスポートします。Python と TypeScript のスニペットは Comfy SDK(pip install comfy-sdk および npm install @comfyorg/sdk)を使用しています。cURL のスニペットは、同じ呼び出しを生の HTTP で行うものです。
モデル ID: vertexai/gemini-3-pro-image
エンドポイント: POST https://api.comfy.org/v2/models/vertexai/gemini-3-pro-image
- 結果を待つ
- キューに登録して後で収集
同じボディを
POST https://api.comfy.org/v2/models/vertexai/gemini-3-pro-image/requests に送信します。Router は実行が受け付けられるとすぐに request_id とともに 201 を返し、結果は準備ができ次第、このプロセスからでも別のプロセスからでも収集できます。キュー配信では、ステータス、キャンセル、収集について説明しています。提供プロバイダー
このモデルは、リクエストで別のプロバイダーを指定しない限り、Comfy Router が直接提供します。以下のプロバイダーも、同じエンドポイントと同じモデル ID でこのモデルを提供しており、model_provider クエリパラメータで選択します。
- Comfy(デフォルト):
POST https://api.comfy.org/v2/models/vertexai/gemini-3-pro-image - fal、
fal/fal-nano-banana-proとして:POST https://api.comfy.org/v2/models/vertexai/gemini-3-pro-image?model_provider=fal - MiniMax、
minimax/minimax-nano-banana-proとして:POST https://api.comfy.org/v2/models/vertexai/gemini-3-pro-image?model_provider=minimax - Pika、
pika/pika-nano-banana-proとして:POST https://api.comfy.org/v2/models/vertexai/gemini-3-pro-image?model_provider=pika - Runware、
runware/runware-nano-banana-proとして:POST https://api.comfy.org/v2/models/vertexai/gemini-3-pro-image?model_provider=runware - WaveSpeed、
wavespeed/wavespeed-nano-banana-proとして:POST https://api.comfy.org/v2/models/vertexai/gemini-3-pro-image?model_provider=wavespeed
strict_mode のデフォルトは false であるため、Router はこのページで説明されているネイティブのリクエストボディをプロバイダー独自のスキーマに変換し、レスポンスを元に戻す変換を行います。API リファレンスの model_provider、strict_mode、fallback_provider と、この方法でルーティングされるすべてのモデルについては提供プロバイダーを参照してください。
スキーマ
入力
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生のバイト形式のインラインデータ。gemini-2.0-flash-lite および gemini-2.0-flash では、inlineData を使用して最大 3000 枚の画像を指定できます。
プロンプトにインラインで含める画像、PDF、またはビデオの base64 エンコーディング。メディアをインラインで含める場合は、データのメディアタイプ(mimeType)も指定する必要があります。サイズ制限: 20MB形式:
bytedata フィールドまたは 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モデルがこのパートのビデオを読み取る方法。“AGENTIC” を設定すると、固定レートのフレームサンプリングではなく、モデルが検査するセグメントを決定できます。省略すると、デフォルトの固定レートサンプリングになります。gemini-3.7-flash 以降の Flash モデルでサポートされています。
生成のためのサンプリング、長さ、出力の設定。すべてのフィールドは任意です。以下で
default を宣言しているフィールドは省略時にその値が適用され、それ以外はモデル固有の動作にフォールバックします。任意。Vertex AI のパス(Comfy 自身の認証情報で処理されるリクエスト、および GCP サービスアカウントで認証された BYOK リクエスト)で、出力を保存する際の画像形式。そこで受け入れられる値は
image/png と image/jpeg で、大文字と小文字を区別せずに照合され、リクエストが転送される前に小文字に正規化されます。その他の値は、このフィールドを名指しした 400 で拒否されます。省略時は image/png がデフォルトです。Google AI Studio の APIキーで認証された BYOK リクエストは例外です。そのアップストリームには該当するプロパティがなく、存在する場合は呼び出し全体を拒否します。そのため、このフィールドは尊重または拒否されるのではなくリクエストから削除され、出力形式は AI Studio が選択するものになります。どのパスでも、送信した値を前提とするのではなく、与えられたレスポンスのパート(inlineData.mimeType、または uploadImagesToStorage が設定されている場合は fileData.mimeType)からメディアタイプを読み戻してください。シードを特定の値に固定すると、モデルは繰り返しのリクエストに対して同じ応答を返せるよう最善を尽くします。決定的な出力は保証されません。また、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
temperature はレスポンス生成中のサンプリングに使用され、これは topP と topK が適用されるときに行われます。temperature はトークン選択のランダム性の度合いを制御します。低い温度は、よりオープンエンドでない、または創造的なレスポンスを必要とするプロンプトに適しており、高い温度はより多様で創造的な結果につながる可能性があります。温度 0 は、常に最も確率の高いトークンが選択されることを意味します。この場合、特定のプロンプトに対するレスポンスはほぼ決定的ですが、少量のばらつきは依然として発生する可能性があります。モデルが汎用的すぎる、短すぎるレスポンスを返す場合、またはモデルがフォールバックレスポンスを返す場合は、temperature を上げてみてください範囲:
0 から 2形式: floatTop-K は、モデルが出力のためにトークンを選択する方法を変更します。Top-K が 1 の場合、次に選択されるトークンはモデルの語彙内のすべてのトークンの中で最も確率が高いものになります。Top-K が 3 の場合、次のトークンは temperature を使用して、確率の高い上位 3 つのトークンの中から選択されます。範囲:
1 から …指定した場合、nucleus サンプリングが使用されます。
Top-P は、モデルが出力のためにトークンを選択する方法を変更します。トークンは、最も確率が高いもの(top-K を参照)から最も低いものへと、それらの確率の合計が top-P の値に等しくなるまで選択されます。たとえば、トークン A、B、C の確率がそれぞれ 0.3、0.2、0.1 で、top-P の値が 0.5 の場合、モデルは temperature を使用して A または B のいずれかを次のトークンとして選択し、C を候補から除外します。
ランダム性の低いレスポンスには低い値を、ランダム性の高いレスポンスには高い値を指定します。範囲:
0 から 1形式: float指定可能な値:
HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_DANGEROUS_CONTENTモデルをより良いパフォーマンスへと導くための指示です。たとえば、「できるだけ簡潔に答えてください」や「レスポンスに技術用語を使わないでください」などです。テキスト文字列はトークン制限にカウントされます。systemInstruction の role フィールドは無視され、モデルのパフォーマンスには影響しません。注: parts にはテキストのみを使用し、各 part のコンテンツは別々の段落にしてください。
単一のメッセージを構成する順序付けられた part のリストです。異なる part は異なる IANA MIME タイプを持つことがあります。最大トークン数や画像数などの入力の制限については、Google のモデルページにあるモデル仕様を参照してください。
メッセージを作成するエンティティの識別情報です。以下の値がサポートされています: user: メッセージが実際の人物によって送信されたことを示します。通常はユーザーが生成したメッセージです。model: メッセージがモデルによって生成されたことを示します。model 値は、マルチターンの会話中にモデルからのメッセージを会話に挿入するために使用されます。マルチターンでない会話では、このフィールドは空白または未設定のままにできます。指定可能な値:
user, modelシステムがモデルの知識と範囲外でアクションまたは一連のアクションを実行するために外部システムと対話できるようにするコードの断片です。Function calling を参照してください。
true の場合、生成済みの画像はクラウドストレージにアップロードされ、インラインの base64 データではなく署名付き URL として返されます。URL は 24 時間で失効します。
ビデオ入力の場合、ビデオの開始と終了のオフセットを Duration 形式で指定します。たとえば、1:00 から始まる 10 秒のクリップを指定するには、“startOffset”: { “seconds”: 60 } と “endOffset”: { “seconds”: 70 } を設定します。メタデータは、ビデオデータが inlineData または fileData で提示されている場合にのみ指定してください。
時間範囲の符号付き秒数。-315,576,000,000 から +315,576,000,000 まで(両端を含む)である必要があります。範囲:
-315576000000 から 315576000000時間範囲の符号付き秒数。-315,576,000,000 から +315,576,000,000 まで(両端を含む)である必要があります。範囲:
-315576000000 から 315576000000GET /v2/models/vertexai/gemini-3-pro-image/openapi.json で提供するスキーマから生成されています。これは、リクエストがプロバイダーに到達する前に Router が呼び出しを検証する際に使用するドキュメントと同じものです。
出力
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生のバイト形式のインラインデータです。gemini-2.0-flash-lite および gemini-2.0-flash では、inlineData を使用して最大 3000 枚の画像を指定できます。
プロンプトにインラインで含める画像、PDF、またはビデオの base64 エンコーディングです。メディアをインラインで含める場合は、データのメディアタイプ(mimeType)も指定する必要があります。サイズ制限: 20MB形式:
bytedata フィールドまたは 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モデルがこのパートのビデオをどのように読み取るかです。固定レートのフレームサンプリングの代わりに、モデルが検査するセグメントを決定できるようにするには “AGENTIC” を設定します。省略すると、デフォルトの固定レートサンプリングになります。gemini-3.7-flash 以降の Flash モデルでサポートされています。
指定可能な値:
HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_DANGEROUS_CONTENTPossible values:
HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_DANGEROUS_CONTENT例
入力
出力
parts の読み取り
デフォルトでは、生成された画像の part には、base64 バイト列がinlineData.data に、メディアタイプが inlineData.mimeType に含まれます。バイト列をデコードしてファイルに保存してください。uploadImagesToStorage: true の場合、アップロードされた画像は代わりに、署名付き URL に fileData.fileUri を、メディアタイプに fileData.mimeType を使用します。これらの画像は、URL が失効する前にダウンロードしてください。URL は作成から 24 時間後に失効します。
fileData は、それを要求していないレスポンスにも現れることがあります。 この 2 つの形はレスポンス単位ではなく part 単位です。uploadImagesToStorage: true が設定されている場合、アップロードに失敗した画像は inlineData のまま残るため、1 つのレスポンスに両方が混在することがあります。要求した内容ではなく、どのキーが存在するかで分岐してください。逆のケースは起こりません。フィールドが未設定または false の場合、生成されたすべての画像は inlineData として返り、fileData の画像 part は生成されません。テキストの part も現れることがあり、画像が最初の part であるとも限らないため、インデックスではなく必要なフィールドで part を選択してください。上記のクイックスタートのサンプルにある candidates[0].content.parts[0].inlineData.data というパスは、このページのサンプルレスポンスにある唯一の inline part を読み取るものです。実際のレスポンスに対しては、位置 0 をインデックス指定するのではなく、parts を走査して目的のキーを探してください。
thoughtSignature も part のフィールドで、しかもサイズが大きくなります。 part は thoughtSignature を持つことがあります。これはモデルの推論を表す不透明な base64 署名で、後続のリクエストでその思考を再生できるようにするために存在します。上記の生成スキーマには含まれていません。このスキーマは Router が公開しているリクエスト/レスポンスのドキュメントに従ったものです。実際のレスポンスで計測すると、part あたりおよそ 1〜2 MB で、画像本体と同程度です。そのため、レスポンスをログに記録したり、サーバーレス関数を介して転送したり、保存したりする場合は、その分の容量を見込むか、明示的に破棄することを検討してください。
imageSize は幅ではなくクラス
generationConfig.imageConfig.imageSize は 1K、2K、4K のいずれかを取り、段階が上がるごとに幅を設定するのではなく両辺が 2 倍になります。16:9 のリクエストを計測すると、1K では 1376x768 で約 1.35 MB、2K では 2752x1536 で約 5.6 MB でした。同じアスペクト比で、ピクセル数は 4 倍、バイト数もおよそ 4 倍です。したがって 2K は幅 2048 ピクセルの画像を意味するものではありません。2K を幅であるかのように扱ってアップロード経路、レスポンスボディの上限、ストレージバケットのサイズを見積もると、約 4 倍の不足が生じます。
参照チェーン
生成済みの画像をそのまま入力し直すと、同じ被写体を別のカメラアングルで捉えた画像が得られます。そのため、1 つのシーンの一連のショットは、すべてを一度に記述しなければならない 1 つのプロンプトではなく、呼び出しのチェーンになります。アーキテクチャ、素材、ライティングはチェーンを通じて維持されることがよくありますが、モデルがそれを保証するわけではありません。連続性は、信頼できる性質ではなく、確認すべき可能性の高い結果として扱ってください。 画像は、前のレスポンスで使われた形のまま送り返してください。inlineData の part の場合は、inlineData.data から base64 バイト列を取り出し、それをそのまま inlineData として送信します(以下を参照)。uploadImagesToStorage: true で fileData として返ってきた part の場合は、署名付き URL がまだ有効なうちに、その fileData.fileUri と fileData.mimeType を fileData part として送信してください。バイト列を inlineData として再アップロードする方法も機能し、失効しません。そのうえで、希望する変更を指示します。
2K の画像は 1K のおよそ 4 倍のバイト数になります。
出荷前の確認
SDK はIdempotency-Key を生成し、自動リトライで再利用します。手動リトライでは元のキーを再利用してください。Router は最大 10 分間接続を保持できます。
リクエストが失敗すると、Router は理由を説明する X-Comfy-Error-Type レスポンスヘッダーを送信します。422 は、プロバイダーを呼び出す前に Router が入力を拒否したことを意味し、413 はリクエスト本文が Router の受け入れ可能なサイズを超えていたことを意味します。生成されたアセットは 結果 URL の有効期限 があるため、早めにダウンロードしてください。
上記のフィールド説明に記載されているサイズ制限は、プロバイダーの仕様から引用した、そのフィールドに対するプロバイダー自身の上限です。Router はリクエスト本文全体に対して別の上限を適用し、base64 エンコードされたメディアもこれにカウントされます。リクエスト本文のサイズ を参照してください。
このページは、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 を参照してください。
ヘッダー
認証、冪等性、リクエスト ID、エラー分類、リトライ間隔、支出上限。
Router API の利用
モデルの検出、バリデーションエラー、リトライ、課金。
制限事項
Router が現在対応していないことと、代替手段。