搭配 Comfy Router 使用 Gemini 3.8 Flash

通过 Comfy Router 调用 vertexai/gemini-3.8-flash：端点、请求形状以及 Router 返回的响应。

vertexai/gemini-3.8-flash 的 API 参考文档，该模型由 Comfy Router 从 Google 提供。

​

快速开始

在你的 Comfy 工作区中创建一个密钥，并将其导出为 COMFY_API_KEY。Python 和 TypeScript 代码片段使用 Comfy SDK（pip install comfy-sdk 和 npm install @comfyorg/sdk）；cURL 代码片段则是通过原始 HTTP 发起同样的调用。

模型 ID： vertexai/gemini-3.8-flash

端点： POST https://api.comfy.org/v2/models/vertexai/gemini-3.8-flash

等待结果

Python

from comfy_sdk import Comfy

# 从环境变量中读取 COMFY_API_KEY。
# SDK 会自动创建幂等键，并在自动重试时复用它。
with Comfy() as client:
    result = client.models.run(
        "vertexai/gemini-3.8-flash",
        {
            "contents": [
                {
                    "parts": [
                        {
                            "text": "Describe a robot learning to paint, in two sentences.",
                        },
                    ],
                    "role": "user",
                },
            ],
        },
    )

print(result)

排队并稍后收集

将相同的请求体发送到 POST https://api.comfy.org/v2/models/vertexai/gemini-3.8-flash/requests。运行被受理后，Router 会立即返回 201 和 request_id；结果就绪后，可以从本进程或其他进程收集。状态、取消与收集的细节见队列投递。

Python

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.8-flash",
            {
                "contents": [
                    {
                        "parts": [
                            {
                                "text": "Describe a robot learning to paint, in two sentences.",
                            },
                        ],
                        "role": "user",
                    },
                ],
            },
        )
        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(result)

asyncio.run(main())

​

Schema

​

输入

contents · object[] · 必填

与模型当前对话的内容。对于单轮查询，这是一个单独的实例。对于多轮查询，这是一个重复字段，包含对话历史和最新的请求。

contents[].parts · object[] · 必填

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 小时，视频文件（无音频）的最大长度为一小时。有关更多信息，请参阅 Gemini 音频和视频要求。文本文件必须采用 UTF-8 编码。文本文件的内容会占用 token 限额。图像分辨率无限制。

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

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

Format: byte

contents[].parts[].inlineData.mimeType · string

在 data 或 fileUri 字段中指定的文件的媒体类型。可接受的取值包括以下内容。对于 gemini-2.0-flash-lite 和 gemini-2.0-flash，音频文件的最大长度为 8.4 小时，视频文件（无音频）的最大长度为一小时。有关更多信息，请参阅 Gemini 音频和视频要求。文本文件必须采用 UTF-8 编码。文本文件的内容会占用 token 限额。图像分辨率无限制。

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

contents[].parts[].mediaProcessing · string

模型读取此部分视频的方式。设置为 “AGENTIC” 可让模型自行决定检查哪些片段，而不是采用固定帧率采样。省略则使用默认的固定帧率采样。受 gemini-3.7-flash 及更新的 Flash 模型支持。

contents[].parts[].text · string

文本提示或代码片段。

contents[].parts[].thought · boolean

表示此部分是模型的一个思考/推理步骤。

contents[].role · string

Possible values: 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

响应中可生成的 token 最大数量。一个 token 大约相当于 4 个字符。100 个 token 大致对应 60 到 80 个单词。

Range: 16 to 65536

generationConfig.responseModalities · `TEXT`, `IMAGE`[]

generationConfig.seed · 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

generationConfig.stopSequences · string[]

generationConfig.temperature · number · 默认值: "1"

温度用于在生成响应期间进行采样，该过程在应用 topP 和 topK 时发生。温度控制 token 选择的随机程度。较低的温度适合需要较为封闭或较少创造性的响应的提示，而较高的温度可能带来更多样或更有创造性的结果。温度为 0 表示始终选择概率最高的 token。在这种情况下，给定提示的响应基本上是确定性的，但仍可能存在少量变化。如果模型返回的响应过于宽泛、过短，或者模型给出了回退响应，请尝试提高温度

范围：0 到 2

格式：float

generationConfig.thinkingConfig · object

可选。思考功能的配置。思考是指模型将复杂任务拆解为更小的步骤，从而生成更高质量响应的过程。

generationConfig.thinkingConfig.includeThoughts · boolean

可选。如果为是，模型会在响应中包含其思考过程。

generationConfig.thinkingConfig.thinkingBudget · integer

可选。模型思考过程的 token 预算。模型会尽力保持在该预算范围内。

generationConfig.thinkingConfig.thinkingLevel · string

可选。模型的思考级别。

可能的值：THINKING_LEVEL_UNSPECIFIED、LOW、MEDIUM、HIGH、MINIMAL

generationConfig.topK · integer · 默认值: "40"

Top-K 会改变模型为输出选择 token 的方式。top-K 为 1 表示所选的下一个 token 是模型词汇表中所有 token 里概率最高的一个。top-K 为 3 表示通过使用温度从前 3 个概率最高的 token 中选择下一个 token。

范围：1 到 …

generationConfig.topP · number · 默认值: "0.95"

如果指定，则使用核采样。 Top-P 会改变模型为输出选择 token 的方式。token 会按概率从最高（参见 top-K）到最低进行选择，直到它们的概率之和等于 top-P 值。例如，如果 token A、B 和 C 的概率分别为 0.3、0.2 和 0.1，且 top-P 值为 0.5，那么模型会通过使用温度选择 A 或 B 作为下一个 token，并将 C 排除在候选之外。 指定较低的值可获得随机性更低的响应，指定较高的值可获得随机性更高的响应。

范围：0 到 1

格式：float

safetySettings · object[]

用于阻止不安全内容的按请求设置。在 GenerateContentResponse.candidates 上强制执行。

safetySettings[].category · string · 必填

可能的值：HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_DANGEROUS_CONTENT

safetySettings[].threshold · string · 必填

可能的值：OFF、BLOCK_NONE、BLOCK_LOW_AND_ABOVE、BLOCK_MEDIUM_AND_ABOVE、BLOCK_ONLY_HIGH

systemInstruction · object

用于引导模型以获得更好表现的指令。例如，“尽可能简洁地回答”或”不要在响应中使用技术术语”。文本字符串会计入 token 上限。systemInstruction 的 role 字段会被忽略，且不会影响模型的表现。注意：parts 中应仅使用文本，且每个 part 中的内容应位于单独的段落中。

systemInstruction.parts · object[] · 必填

构成单条消息的有序 part 列表。不同的 part 可以具有不同的 IANA MIME 类型。有关输入的限制，例如最大 token 数或图像数量，请参阅 Google 模型页面上的模型规格。

systemInstruction.parts[].text · string

文本提示或代码片段。

systemInstruction.role · string

创建该消息的实体的身份。支持以下值：user：表示该消息由真人发送，通常是用户生成的消息。model：表示该消息由模型生成。在多轮对话中，使用 model 值可将模型的消息插入到对话中。对于非多轮对话，该字段可以留空或不设置。

可能的值：user、model

tools · object[]

一段代码，使系统能够与外部系统交互，以执行超出模型知识范围与能力范围的操作或一组操作。请参阅 Function calling。

tools[].functionDeclarations · object[]

tools[].functionDeclarations[].description · string

tools[].functionDeclarations[].name · string · 必填

tools[].functionDeclarations[].parameters · object

函数参数的 JSON schema

uploadImagesToStorage · boolean

如果为 true，已生成的图像将上传到云端存储，并以签名 URL 的形式返回，而不是内联 base64 数据。这些 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.8-flash/openapi.json 提供的 schema 生成，这也是请求到达提供商之前 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[] · 必填

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 小时，视频文件（不含音频）的最大长度为一小时。有关更多信息，请参阅 Gemini 音频和视频要求。文本文件必须采用 UTF-8 编码。文本文件的内容计入 token 限制。图像分辨率无限制。

可能的值：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 小时，视频文件（不含音频）的最大长度为一小时。有关更多信息，请参阅 Gemini 音频和视频要求。文本文件必须采用 UTF-8 编码。文本文件的内容计入 token 限制。图像分辨率无限制。

可能的值：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

仅输出。输入中缓存部分（即缓存内容）的 token 数量。

usageMetadata.candidatesTokenCount · integer

响应中的 token 数量。

usageMetadata.candidatesTokensDetails · object[]

按模态划分的候选 token 明细。

usageMetadata.candidatesTokensDetails[].modality · string

输入或输出内容的模态类型。

可能的值：MODALITY_UNSPECIFIED、TEXT、IMAGE、VIDEO、AUDIO、DOCUMENT

usageMetadata.candidatesTokensDetails[].tokenCount · integer

给定模态的 token 数量。

usageMetadata.promptTokenCount · integer

请求中的 token 数量。设置 cachedContent 时，这仍然是提示词的有效总大小，也就是说它包含缓存内容中的 token 数量。

usageMetadata.promptTokensDetails · object[]

按模态划分的提示词 token 明细。

usageMetadata.promptTokensDetails[].modality · string

输入或输出内容的模态类型。

可能的值：MODALITY_UNSPECIFIED、TEXT、IMAGE、VIDEO、AUDIO、DOCUMENT

usageMetadata.promptTokensDetails[].tokenCount · integer

给定模态的 token 数量。

usageMetadata.thoughtsTokenCount · integer

thoughts 输出中包含的 token 数量。

usageMetadata.toolUsePromptTokenCount · integer

工具使用提示词中包含的 token 数量。

usageMetadata.toolUsePromptTokensDetails · object[]

按模态划分的工具使用提示词 token 明细。

usageMetadata.toolUsePromptTokensDetails[].modality · string

输入或输出内容的模态类型。

可能的值：MODALITY_UNSPECIFIED、TEXT、IMAGE、VIDEO、AUDIO、DOCUMENT

usageMetadata.toolUsePromptTokensDetails[].tokenCount · integer

给定模态的 token 数量。

usageMetadata.totalTokenCount · integer

token 总数（提示词 + 候选）。

usageMetadata.trafficType · string

请求使用的流量类型（例如 PROVISIONED_THROUGHPUT）。

​

示例

​

输入

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

​

输出

{
  "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-3.8-flash",
  "responseId": "0d1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "usageMetadata": {
    "candidatesTokenCount": 21,
    "promptTokenCount": 12,
    "totalTokenCount": 33
  }
}

​

发布前须知

SDK 会生成 Idempotency-Key 并在自动重试中复用它。手动重试时，请复用原始 key。Router 最长可保持连接 10 分钟。

请求失败时，Router 会发送 X-Comfy-Error-Type 响应头说明原因。422 表示 Router 在调用提供商之前就拒绝了输入，413 表示请求体超出了 Router 可接受的大小。已生成的资源请及时下载，因为结果 URL 会过期。

上文任何字段描述中提到的尺寸限制，都是提供商对该字段自身的限定，引自提供商的规范。Router 会对整个请求体另行设置上限，base64 编码的媒体内容也计入其中：参见请求体大小。

本页记录的是通过 Comfy Router 调用的某一个合作伙伴模型。同一个 comfy-sdk / @comfyorg/sdk 包还提供第二个客户端，用于在 Comfy Cloud 上运行完整的 ComfyUI 工作流图：Comfy(api_key=...) / new Comfy({ apiKey })，并带有 client.workflows、client.assets 和 client.jobs。请参阅 Comfy SDKs。

请求头

身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。

使用 Router API

模型发现、验证错误、重试与计费。

限制

Router 目前不支持的功能，以及替代方案。