Use Google Gemini with Comfy Router

Use Google Gemini with Comfy Router. Google Gemini is Google’s family of multimodal text models, covering fast drafting through deep reasoning across the Flash and Pro tiers.

Quick start

Create a key at platform.comfy.org/profile/api-keys and export it as COMFY_API_KEY. The Python and TypeScript snippets use the Comfy SDKs (pip install comfy-sdk, npm install @comfyorg/sdk); the cURL snippet is the same call over raw HTTP. Pick the model you want to call. The models share one request and response shape, documented once below.

Gemini 3.1 Pro
Gemini 3.5 Flash
Gemini 2.5 Pro
Gemini 2.5 Flash

Model ID: vertexai/gemini-3.1-pro-previewEndpoint: POST https://api.comfy.org/v2/models/vertexai/gemini-3.1-pro-preview

import uuid
from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment. Save this key and reuse it if you
# retry this request after the SDK returns an error.
idempotency_key = str(uuid.uuid4())
with Comfy() as client:
    result = client.models.run(
        "vertexai/gemini-3.1-pro-preview",
        {
            "contents": [
                {
                    "role": "user",
                    "parts": [
                        {
                            "text": "Describe a single red maple leaf on a white background in one sentence.",
                        },
                    ],
                },
            ],
            "generationConfig": {
                "temperature": 0.7,
                "maxOutputTokens": 256,
            },
        },
        idempotency_key=idempotency_key,
    )

print("text:", result["candidates"][0]["content"]["parts"][0]["text"])

import { comfy } from "@comfyorg/sdk";

// Reads COMFY_API_KEY from the environment. Save this key and reuse it if you
// retry this request after the SDK returns an error.
type Result = { candidates: { content: { parts: { text: string }[] } }[] };
const idempotencyKey = crypto.randomUUID();
const { data } = await comfy.models.run<Result>("vertexai/gemini-3.1-pro-preview", {
  contents: [
    {
      role: "user",
      parts: [
        {
          text: "Describe a single red maple leaf on a white background in one sentence.",
        },
      ],
    },
  ],
  generationConfig: {
    temperature: 0.7,
    maxOutputTokens: 256,
  },
}, { idempotencyKey });

console.log("text:", data.candidates[0].content.parts[0].text);

# Run this line once. Reuse ROUTER_REQUEST_KEY if you retry the curl command.
ROUTER_REQUEST_KEY=$(uuidgen)
curl https://api.comfy.org/v2/models/vertexai/gemini-3.1-pro-preview \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $ROUTER_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"contents\": [{\"role\":\"user\",\"parts\":[{\"text\":\"Describe a single red maple leaf on a white background in one sentence.\"}]}], \"generationConfig\": {\"temperature\":0.7,\"maxOutputTokens\":256}}"

Model ID: vertexai/gemini-3.5-flashEndpoint: POST https://api.comfy.org/v2/models/vertexai/gemini-3.5-flash

import uuid
from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment. Save this key and reuse it if you
# retry this request after the SDK returns an error.
idempotency_key = str(uuid.uuid4())
with Comfy() as client:
    result = client.models.run(
        "vertexai/gemini-3.5-flash",
        {
            "contents": [
                {
                    "role": "user",
                    "parts": [
                        {
                            "text": "Describe a single red maple leaf on a white background in one sentence.",
                        },
                    ],
                },
            ],
            "generationConfig": {
                "temperature": 0.7,
                "maxOutputTokens": 256,
            },
        },
        idempotency_key=idempotency_key,
    )

print("text:", result["candidates"][0]["content"]["parts"][0]["text"])

import { comfy } from "@comfyorg/sdk";

// Reads COMFY_API_KEY from the environment. Save this key and reuse it if you
// retry this request after the SDK returns an error.
type Result = { candidates: { content: { parts: { text: string }[] } }[] };
const idempotencyKey = crypto.randomUUID();
const { data } = await comfy.models.run<Result>("vertexai/gemini-3.5-flash", {
  contents: [
    {
      role: "user",
      parts: [
        {
          text: "Describe a single red maple leaf on a white background in one sentence.",
        },
      ],
    },
  ],
  generationConfig: {
    temperature: 0.7,
    maxOutputTokens: 256,
  },
}, { idempotencyKey });

console.log("text:", data.candidates[0].content.parts[0].text);

# Run this line once. Reuse ROUTER_REQUEST_KEY if you retry the curl command.
ROUTER_REQUEST_KEY=$(uuidgen)
curl https://api.comfy.org/v2/models/vertexai/gemini-3.5-flash \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $ROUTER_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"contents\": [{\"role\":\"user\",\"parts\":[{\"text\":\"Describe a single red maple leaf on a white background in one sentence.\"}]}], \"generationConfig\": {\"temperature\":0.7,\"maxOutputTokens\":256}}"

Model ID: vertexai/gemini-2.5-proEndpoint: POST https://api.comfy.org/v2/models/vertexai/gemini-2.5-pro

import uuid
from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment. Save this key and reuse it if you
# retry this request after the SDK returns an error.
idempotency_key = str(uuid.uuid4())
with Comfy() as client:
    result = client.models.run(
        "vertexai/gemini-2.5-pro",
        {
            "contents": [
                {
                    "role": "user",
                    "parts": [
                        {
                            "text": "Describe a single red maple leaf on a white background in one sentence.",
                        },
                    ],
                },
            ],
            "generationConfig": {
                "temperature": 0.7,
                "maxOutputTokens": 256,
            },
        },
        idempotency_key=idempotency_key,
    )

print("text:", result["candidates"][0]["content"]["parts"][0]["text"])

import { comfy } from "@comfyorg/sdk";

// Reads COMFY_API_KEY from the environment. Save this key and reuse it if you
// retry this request after the SDK returns an error.
type Result = { candidates: { content: { parts: { text: string }[] } }[] };
const idempotencyKey = crypto.randomUUID();
const { data } = await comfy.models.run<Result>("vertexai/gemini-2.5-pro", {
  contents: [
    {
      role: "user",
      parts: [
        {
          text: "Describe a single red maple leaf on a white background in one sentence.",
        },
      ],
    },
  ],
  generationConfig: {
    temperature: 0.7,
    maxOutputTokens: 256,
  },
}, { idempotencyKey });

console.log("text:", data.candidates[0].content.parts[0].text);

# Run this line once. Reuse ROUTER_REQUEST_KEY if you retry the curl command.
ROUTER_REQUEST_KEY=$(uuidgen)
curl https://api.comfy.org/v2/models/vertexai/gemini-2.5-pro \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $ROUTER_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"contents\": [{\"role\":\"user\",\"parts\":[{\"text\":\"Describe a single red maple leaf on a white background in one sentence.\"}]}], \"generationConfig\": {\"temperature\":0.7,\"maxOutputTokens\":256}}"

Model ID: vertexai/gemini-2.5-flashEndpoint: POST https://api.comfy.org/v2/models/vertexai/gemini-2.5-flash

import uuid
from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment. Save this key and reuse it if you
# retry this request after the SDK returns an error.
idempotency_key = str(uuid.uuid4())
with Comfy() as client:
    result = client.models.run(
        "vertexai/gemini-2.5-flash",
        {
            "contents": [
                {
                    "role": "user",
                    "parts": [
                        {
                            "text": "Describe a single red maple leaf on a white background in one sentence.",
                        },
                    ],
                },
            ],
            "generationConfig": {
                "temperature": 0.7,
                "maxOutputTokens": 256,
            },
        },
        idempotency_key=idempotency_key,
    )

print("text:", result["candidates"][0]["content"]["parts"][0]["text"])

import { comfy } from "@comfyorg/sdk";

// Reads COMFY_API_KEY from the environment. Save this key and reuse it if you
// retry this request after the SDK returns an error.
type Result = { candidates: { content: { parts: { text: string }[] } }[] };
const idempotencyKey = crypto.randomUUID();
const { data } = await comfy.models.run<Result>("vertexai/gemini-2.5-flash", {
  contents: [
    {
      role: "user",
      parts: [
        {
          text: "Describe a single red maple leaf on a white background in one sentence.",
        },
      ],
    },
  ],
  generationConfig: {
    temperature: 0.7,
    maxOutputTokens: 256,
  },
}, { idempotencyKey });

console.log("text:", data.candidates[0].content.parts[0].text);

# Run this line once. Reuse ROUTER_REQUEST_KEY if you retry the curl command.
ROUTER_REQUEST_KEY=$(uuidgen)
curl https://api.comfy.org/v2/models/vertexai/gemini-2.5-flash \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $ROUTER_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"contents\": [{\"role\":\"user\",\"parts\":[{\"text\":\"Describe a single red maple leaf on a white background in one sentence.\"}]}], \"generationConfig\": {\"temperature\":0.7,\"maxOutputTokens\":256}}"

Schema

Input

object[]

required

The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries, this is a repeated field that contains conversation history and the latest request.

object[]

required

object

URI based data.

string

URI

string

The media type of the file specified in the data or fileUri fields. Acceptable values include the following. For gemini-2.0-flash-lite and gemini-2.0-flash, the maximum length of an audio file is 8.4 hours and the maximum length of a video file (without audio) is one hour. For more information, see Gemini audio and video requirements. Text files must be UTF-8 encoded. The contents of the text file count toward the token limit. There is no limit on image resolution.Possible values: 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

object

Inline data in raw bytes. For gemini-2.0-flash-lite and gemini-2.0-flash, you can specify up to 3000 images by using inlineData.

string (byte)

The base64 encoding of the image, PDF, or video to include inline in the prompt. When including media inline, you must also specify the media type (mimeType) of the data. Size limit: 20MBFormat: byte

string

A text prompt or code snippet.

boolean

Indicates this part is a thinking/reasoning step from the model.

string

Possible values: user, model

object

Sampling, length and output settings for the generation. Every field is optional: the fields below that declare a default apply it when omitted, and the rest fall back to the model’s own behaviour.

object

Configuration for image generation

string

Aspect ratio for generated images

object

Optional. The image output format for generated images.

integer

Optional. The compression quality of the output image.

string

Optional. The image format that the output should be saved as.

string

Optional. Specifies the size of generated images. Supported values are 1K, 2K, 4K. If not specified, the model will use default value 1K.

integer

Maximum number of tokens that can be generated in the response. A token is approximately 4 characters. 100 tokens correspond to roughly 60-80 words.Range: 16 to 65536

`TEXT`, `IMAGE`[]

integer

When seed is fixed to a specific value, the model makes a best effort to provide the same response for repeated requests. Deterministic output isn’t guaranteed. Also, changing the model or parameter settings, such as the temperature, can cause variations in the response even when you use the same seed value. By default, a random seed value is used. Available for the following models:, 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

string[]

number

default:"1"

The temperature is used for sampling during response generation, which occurs when topP and topK are applied. Temperature controls the degree of randomness in token selection. Lower temperatures are good for prompts that require a less open-ended or creative response, while higher temperatures can lead to more diverse or creative results. A temperature of 0 means that the highest probability tokens are always selected. In this case, responses for a given prompt are mostly deterministic, but a small amount of variation is still possible. If the model returns a response that’s too generic, too short, or the model gives a fallback response, try increasing the temperatureRange: 0 to 2Format: float

object

Optional. Configuration for thinking features. Thinking is a process where the model breaks down a complex task into smaller steps to generate a higher-quality response.

boolean

Optional. If true, the model will include its thoughts in the response.

integer

Optional. The token budget for the model’s thinking process. The model will make a best effort to stay within this budget.

string

Optional. The thinking level for the model.Possible values: THINKING_LEVEL_UNSPECIFIED, LOW, MEDIUM, HIGH, MINIMAL

integer

default:"40"

Top-K changes how the model selects tokens for output. A top-K of 1 means the next selected token is the most probable among all tokens in the model’s vocabulary. A top-K of 3 means that the next token is selected from among the 3 most probable tokens by using temperature.Range: 1 to …

number

default:"0.95"

If specified, nucleus sampling is used. Top-P changes how the model selects tokens for output. Tokens are selected from the most (see top-K) to least probable until the sum of their probabilities equals the top-P value. For example, if tokens A, B, and C have a probability of 0.3, 0.2, and 0.1 and the top-P value is 0.5, then the model will select either A or B as the next token by using temperature and excludes C as a candidate. Specify a lower value for less random responses and a higher value for more random responses.Range: 0 to 1Format: float

object[]

Per request settings for blocking unsafe content. Enforced on GenerateContentResponse.candidates.

string

required

Possible values: HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_DANGEROUS_CONTENT

string

required

Possible values: OFF, BLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH

object

Instructions for the model to steer it toward better performance. For example, “Answer as concisely as possible” or “Don’t use technical terms in your response”. The text strings count toward the token limit. The role field of systemInstruction is ignored and doesn’t affect the performance of the model. Note: Only text should be used in parts and content in each part should be in a separate paragraph.

object[]

required

A list of ordered parts that make up a single message. Different parts may have different IANA MIME types. For limits on the inputs, such as the maximum number of tokens or the number of images, see the model specifications on the Google models page.

string

A text prompt or code snippet.

string

The identity of the entity that creates the message. The following values are supported: user: This indicates that the message is sent by a real person, typically a user-generated message. model: This indicates that the message is generated by the model. The model value is used to insert messages from the model into the conversation during multi-turn conversations. For non-multi-turn conversations, this field can be left blank or unset.Possible values: user, model

object[]

A piece of code that enables the system to interact with external systems to perform an action, or set of actions, outside of knowledge and scope of the model. See Function calling.

object[]

string

required

object

JSON schema for the function parameters

boolean

If true, generated images will be uploaded to cloud storage and returned as signed URLs instead of inline base64 data. The URLs expire after 24 hours.

object

For video input, the start and end offset of the video in Duration format. For example, to specify a 10 second clip starting at 1:00, set “startOffset”: { “seconds”: 60 } and “endOffset”: { “seconds”: 70 }. The metadata should only be specified while the video data is presented in inlineData or fileData.

object

Represents a duration offset for video timeline positions.

integer

Signed fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values.Range: 0 to 999999999

integer

Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive.Range: -315576000000 to 315576000000

object

Represents a duration offset for video timeline positions.

integer

Signed fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values.Range: 0 to 999999999

integer

Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive.Range: -315576000000 to 315576000000

Generated from the schema Router serves at GET /v2/models/vertexai/gemini-3.1-pro-preview/openapi.json, the same document it validates a call against before the request reaches the provider.

Output

object[]

object

object[]

string[]

integer

string

string (date)

Format: date

integer

string

object

object[]

required

object

URI based data.

string

URI

string

object

Inline data in raw bytes. For gemini-2.0-flash-lite and gemini-2.0-flash, you can specify up to 3000 images by using inlineData.

string (byte)

string

A text prompt or code snippet.

boolean

Indicates this part is a thinking/reasoning step from the model.

string

Possible values: user, model

string

object[]

string

Possible values: HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_DANGEROUS_CONTENT

string

The probability that the content violates the specified safety categoryPossible values: NEGLIGIBLE, LOW, MEDIUM, HIGH, UNKNOWN

string

Timestamp when the response was created.

string

The model version used to generate the response.

object

string

object[]

string

Possible values: HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_DANGEROUS_CONTENT

string

The probability that the content violates the specified safety categoryPossible values: NEGLIGIBLE, LOW, MEDIUM, HIGH, UNKNOWN

string

Unique identifier for the response.

object

integer

Output only. Number of tokens in the cached part in the input (the cached content).

integer

Number of tokens in the response(s).

object[]

Breakdown of candidate tokens by modality.

string

Type of input or output content modality.Possible values: MODALITY_UNSPECIFIED, TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT

integer

Number of tokens for the given modality.

integer

Number of tokens in the request. When cachedContent is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content.

object[]

Breakdown of prompt tokens by modality.

string

Type of input or output content modality.Possible values: MODALITY_UNSPECIFIED, TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT

integer

Number of tokens for the given modality.

integer

Number of tokens present in thoughts output.

integer

Number of tokens present in tool-use prompt(s).

integer

Total number of tokens (prompt + candidates).

string

Traffic type used for the request (e.g., PROVISIONED_THROUGHPUT).

Examples

Input

{
  "contents": [
    {
      "parts": [
        {
          "text": "Describe a robot learning to paint, in two sentences."
        }
      ],
      "role": "user"
    }
  ]
}

Output

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "A lighthouse stands at the edge of the harbour, its lamp still turning as the sun comes up."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "modelVersion": "gemini-2.5-flash",
  "responseId": "0d1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "usageMetadata": {
    "candidatesTokenCount": 21,
    "promptTokenCount": 12,
    "totalTokenCount": 33
  }
}

Before you ship

Save one Idempotency-Key for each call and reuse it for retries. Router can hold the connection for up to 10 minutes. The SDKs handle authentication; raw HTTP clients send the headers themselves. Use X-Comfy-Error-Type to classify a failure. A 422 means Router rejected the input before calling the provider. Download generated assets promptly because result URLs can expire.

Headers

Authentication, idempotency, request IDs, error buckets, retry pacing, spend limits.

Using the Router API

Find models, inspect schemas, and retry safely.

Limitations

What Router does not do today, and what to use instead.

Develop with Comfy

Deploy ComfyUI

Run Workflows

Comfy Router

Comfy CLI

Specifications

Use Google Gemini with Comfy Router

Quick start

Schema

Input

Output

Examples

Input

Output

Before you ship

Headers

Using the Router API

Limitations

​Quick start

​Schema

​Input

​Output

​Examples

​Input

​Output

​Before you ship

Headers

Using the Router API

Limitations

Quick start

Schema

Input

Output

Examples

Input

Output

Before you ship