> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-claude-comfy-concurrency-limits-page-s84u33.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 搭配 Comfy Router 使用 Gemini 3.8 Flash

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

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

## 快速开始

在[你的 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.8-flash`

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

<Tabs defaultTabIndex={1}>
  <Tab title="等待结果">
    <CodeGroup>
      ```python Python theme={null}
      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)
      ```

      ```typescript TypeScript theme={null}
      import { comfy } from "@comfyorg/sdk";

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

      console.log(data);
      ```

      ```bash cURL theme={null}
      curl https://api.comfy.org/v2/models/vertexai/gemini-3.8-flash \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"contents\": [{\"parts\":[{\"text\":\"Describe a robot learning to paint, in two sentences.\"}],\"role\":\"user\"}]}"
      ```
    </CodeGroup>
  </Tab>

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

    <CodeGroup>
      ```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.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())
      ```

      ```typescript TypeScript theme={null}
      import { comfy } from "@comfyorg/sdk";

      // 从环境变量中读取 COMFY_API_KEY。
      // 每次调用 submit() 都会生成自己的 Idempotency-Key，并在自动重试时复用它。
      const handle = await comfy.models.submit("vertexai/gemini-3.8-flash", {
        contents: [
          {
            parts: [
              {
                text: "Describe a robot learning to paint, in two sentences.",
              },
            ],
            role: "user",
          },
        ],
      });
      console.log("requestId:", handle.requestId); // 加上模型 ID，就是另一个进程所需的全部信息

      // 轮询直到请求完成，按服务器给出的 Retry-After 等待。
      for await (const update of handle.events()) {
        console.log(update.status, update.queuePosition);
      }

      // 与 models.run() 返回的结果相同。失败或已取消的请求会在这里拒绝。
      const result = await handle.get();

      console.log(result.data);
      ```

      ```bash cURL theme={null}
      # 1. 提交。Router 会返回 201，并附带 request_id、status_url、response_url 和 cancel_url。
      curl https://api.comfy.org/v2/models/vertexai/gemini-3.8-flash/requests \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"contents\": [{\"parts\":[{\"text\":\"Describe a robot learning to paint, in two sentences.\"}],\"role\":\"user\"}]}"

      # 2. 轮询直到状态为 COMPLETED，等待每个响应给出的 Retry-After 秒数。
      REQUEST_ID="<request_id from the 201 body>"
      curl -i https://api.comfy.org/v2/models/vertexai/gemini-3.8-flash/requests/$REQUEST_ID/status \
        -H "X-API-Key: $COMFY_API_KEY"

      # 3. 收集。返回 200 时带有模型的原生输出，仍在运行时返回 202 和状态响应体。
      curl https://api.comfy.org/v2/models/vertexai/gemini-3.8-flash/requests/$REQUEST_ID \
        -H "X-API-Key: $COMFY_API_KEY"
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Schema

### 输入

<ParamField body="contents" type="object[]" required>
  与模型当前对话的内容。对于单轮查询，这是一个单独的实例。对于多轮查询，这是一个重复字段，包含对话历史和最新的请求。
</ParamField>

<ParamField body="contents[].parts" type="object[]" required />

<ParamField body="contents[].parts[].fileData" type="object">
  基于 URI 的数据。
</ParamField>

<ParamField body="contents[].parts[].fileData.fileUri" type="string">
  URI
</ParamField>

<ParamField body="contents[].parts[].fileData.mimeType" type="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`
</ParamField>

<ParamField body="contents[].parts[].inlineData" type="object">
  原始字节形式的内联数据。对于 gemini-2.0-flash-lite 和 gemini-2.0-flash，使用 inlineData 最多可以指定 3000 张图像。
</ParamField>

<ParamField body="contents[].parts[].inlineData.data" type="string (byte)">
  以内联方式包含在提示中的图像、PDF 或视频的 base64 编码。内联包含媒体时，还必须指定数据的媒体类型（mimeType）。大小限制：20MB

  Format: `byte`
</ParamField>

<ParamField body="contents[].parts[].inlineData.mimeType" type="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`
</ParamField>

<ParamField body="contents[].parts[].mediaProcessing" type="string">
  模型读取此部分视频的方式。设置为 "AGENTIC" 可让模型自行决定检查哪些片段，而不是采用固定帧率采样。省略则使用默认的固定帧率采样。受 gemini-3.7-flash 及更新的 Flash 模型支持。
</ParamField>

<ParamField body="contents[].parts[].text" type="string">
  文本提示或代码片段。
</ParamField>

<ParamField body="contents[].parts[].thought" type="boolean">
  表示此部分是模型的一个思考/推理步骤。
</ParamField>

<ParamField body="contents[].role" type="string">
  Possible values: `user`, `model`
</ParamField>

<ParamField body="generationConfig" type="object">
  生成的采样、长度和输出设置。每个字段都是可选的：下面声明了 `default` 的字段在省略时应用该默认值，其余字段则回退到模型自身的行为。
</ParamField>

<ParamField body="generationConfig.imageConfig" type="object">
  图像生成配置
</ParamField>

<ParamField body="generationConfig.imageConfig.aspectRatio" type="string">
  已生成图像的宽高比
</ParamField>

<ParamField body="generationConfig.imageConfig.imageOutputOptions" type="object">
  可选。已生成图像的图像输出格式。
</ParamField>

<ParamField body="generationConfig.imageConfig.imageOutputOptions.compressionQuality" type="integer">
  可选。输出图像的压缩质量。
</ParamField>

<ParamField body="generationConfig.imageConfig.imageOutputOptions.mimeType" type="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`），而不要假定你发送的值。
</ParamField>

<ParamField body="generationConfig.imageConfig.imageSize" type="string">
  可选。指定已生成图像的尺寸。支持的值为 1K、2K、4K。如果未指定，模型将使用默认值 1K。
</ParamField>

<ParamField body="generationConfig.maxOutputTokens" type="integer">
  响应中可生成的 token 最大数量。一个 token 大约相当于 4 个字符。100 个 token 大致对应 60 到 80 个单词。

  Range: `16` to `65536`
</ParamField>

<ParamField body="generationConfig.responseModalities" type="`TEXT`, `IMAGE`[]" />

<ParamField body="generationConfig.seed" type="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
</ParamField>

<ParamField body="generationConfig.stopSequences" type="string[]" />

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

  范围：`0` 到 `2`

  格式：`float`
</ParamField>

<ParamField body="generationConfig.thinkingConfig" type="object">
  可选。思考功能的配置。思考是指模型将复杂任务拆解为更小的步骤，从而生成更高质量响应的过程。
</ParamField>

<ParamField body="generationConfig.thinkingConfig.includeThoughts" type="boolean">
  可选。如果为是，模型会在响应中包含其思考过程。
</ParamField>

<ParamField body="generationConfig.thinkingConfig.thinkingBudget" type="integer">
  可选。模型思考过程的 token 预算。模型会尽力保持在该预算范围内。
</ParamField>

<ParamField body="generationConfig.thinkingConfig.thinkingLevel" type="string">
  可选。模型的思考级别。

  可能的值：`THINKING_LEVEL_UNSPECIFIED`、`LOW`、`MEDIUM`、`HIGH`、`MINIMAL`
</ParamField>

<ParamField body="generationConfig.topK" type="integer" default="40">
  Top-K 会改变模型为输出选择 token 的方式。top-K 为 1 表示所选的下一个 token 是模型词汇表中所有 token 里概率最高的一个。top-K 为 3 表示通过使用温度从前 3 个概率最高的 token 中选择下一个 token。

  范围：`1` 到 `…`
</ParamField>

<ParamField body="generationConfig.topP" type="number" default="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`
</ParamField>

<ParamField body="safetySettings" type="object[]">
  用于阻止不安全内容的按请求设置。在 GenerateContentResponse.candidates 上强制执行。
</ParamField>

<ParamField body="safetySettings[].category" type="string" required>
  可能的值：`HARM_CATEGORY_SEXUALLY_EXPLICIT`、`HARM_CATEGORY_HATE_SPEECH`、`HARM_CATEGORY_HARASSMENT`、`HARM_CATEGORY_DANGEROUS_CONTENT`
</ParamField>

<ParamField body="safetySettings[].threshold" type="string" required>
  可能的值：`OFF`、`BLOCK_NONE`、`BLOCK_LOW_AND_ABOVE`、`BLOCK_MEDIUM_AND_ABOVE`、`BLOCK_ONLY_HIGH`
</ParamField>

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

<ParamField body="systemInstruction.parts" type="object[]" required>
  构成单条消息的有序 part 列表。不同的 part 可以具有不同的 IANA MIME 类型。有关输入的限制，例如最大 token 数或图像数量，请参阅 Google 模型页面上的模型规格。
</ParamField>

<ParamField body="systemInstruction.parts[].text" type="string">
  文本提示或代码片段。
</ParamField>

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

  可能的值：`user`、`model`
</ParamField>

<ParamField body="tools" type="object[]">
  一段代码，使系统能够与外部系统交互，以执行超出模型知识范围与能力范围的操作或一组操作。请参阅 Function calling。
</ParamField>

<ParamField body="tools[].functionDeclarations" type="object[]" />

<ParamField body="tools[].functionDeclarations[].description" type="string" />

<ParamField body="tools[].functionDeclarations[].name" type="string" required />

<ParamField body="tools[].functionDeclarations[].parameters" type="object">
  函数参数的 JSON schema
</ParamField>

<ParamField body="uploadImagesToStorage" type="boolean">
  如果为 true，已生成的图像将上传到云端存储，并以签名 URL 的形式返回，而不是内联 base64 数据。这些 URL 会在 24 小时后过期。
</ParamField>

<ParamField body="videoMetadata" type="object">
  对于视频输入，表示视频的起始和结束偏移量，采用 Duration 格式。例如，要指定一段从 1:00 开始的 10 秒片段，请设置 "startOffset": \{ "seconds": 60 } 和 "endOffset": \{ "seconds": 70 }。只有当视频数据以 inlineData 或 fileData 形式呈现时，才应指定该元数据。
</ParamField>

<ParamField body="videoMetadata.endOffset" type="object">
  表示视频时间轴位置的时长偏移量。
</ParamField>

<ParamField body="videoMetadata.endOffset.nanos" type="integer">
  以纳秒分辨率表示的有符号秒的小数部分。带小数的负秒值仍必须具有非负的 nanos 值。

  范围：`0` 到 `999999999`
</ParamField>

<ParamField body="videoMetadata.endOffset.seconds" type="integer">
  时间跨度的有符号秒数。必须在 -315,576,000,000 到 +315,576,000,000 之间（含端点）。

  范围：`-315576000000` 到 `315576000000`
</ParamField>

<ParamField body="videoMetadata.startOffset" type="object">
  表示视频时间轴位置的时长偏移量。
</ParamField>

<ParamField body="videoMetadata.startOffset.nanos" type="integer">
  以纳秒分辨率表示的有符号秒的小数部分。带小数的负秒值仍必须具有非负的 nanos 值。

  范围：`0` 到 `999999999`
</ParamField>

<ParamField body="videoMetadata.startOffset.seconds" type="integer">
  时间跨度的有符号秒数。必须在 -315,576,000,000 到 +315,576,000,000 之间（含端点）。

  范围：`-315576000000` 到 `315576000000`
</ParamField>

本文档由 Router 在 `GET /v2/models/vertexai/gemini-3.8-flash/openapi.json` 提供的 schema 生成，这也是请求到达提供商之前 Router 用来验证调用的同一份文档。

### 输出

<ResponseField name="candidates" type="object[]" />

<ResponseField name="candidates[].citationMetadata" type="object" />

<ResponseField name="candidates[].citationMetadata.citations" type="object[]" />

<ResponseField name="candidates[].citationMetadata.citations[].authors" type="string[]" />

<ResponseField name="candidates[].citationMetadata.citations[].endIndex" type="integer" />

<ResponseField name="candidates[].citationMetadata.citations[].license" type="string" />

<ResponseField name="candidates[].citationMetadata.citations[].publicationDate" type="string (date)">
  格式：`date`
</ResponseField>

<ResponseField name="candidates[].citationMetadata.citations[].startIndex" type="integer" />

<ResponseField name="candidates[].citationMetadata.citations[].title" type="string" />

<ResponseField name="candidates[].citationMetadata.citations[].uri" type="string" />

<ResponseField name="candidates[].content" type="object">
  与模型进行的当前对话的内容。对于单轮查询，这是单个实例。对于多轮查询，这是一个重复字段，包含对话历史和最新的请求。
</ResponseField>

<ResponseField name="candidates[].content.parts" type="object[]" required />

<ResponseField name="candidates[].content.parts[].fileData" type="object">
  基于 URI 的数据。
</ResponseField>

<ResponseField name="candidates[].content.parts[].fileData.fileUri" type="string">
  URI
</ResponseField>

<ResponseField name="candidates[].content.parts[].fileData.mimeType" type="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`
</ResponseField>

<ResponseField name="candidates[].content.parts[].inlineData" type="object">
  以内联方式提供的原始字节数据。对于 gemini-2.0-flash-lite 和 gemini-2.0-flash，使用 inlineData 最多可以指定 3000 张图像。
</ResponseField>

<ResponseField name="candidates[].content.parts[].inlineData.data" type="string (byte)">
  以内联方式包含在提示中的图像、PDF 或视频的 base64 编码。以内联方式包含媒体时，还必须指定数据的媒体类型（mimeType）。大小限制：20MB

  格式：`byte`
</ResponseField>

<ResponseField name="candidates[].content.parts[].inlineData.mimeType" type="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`
</ResponseField>

<ResponseField name="candidates[].content.parts[].mediaProcessing" type="string">
  模型读取此部分的视频的方式。设置为 "AGENTIC" 可让模型自行决定要检查哪些片段，而不是采用固定帧率采样。省略则使用默认的固定帧率采样。受 gemini-3.7-flash 及更新的 Flash 模型支持。
</ResponseField>

<ResponseField name="candidates[].content.parts[].text" type="string">
  文本提示或代码片段。
</ResponseField>

<ResponseField name="candidates[].content.parts[].thought" type="boolean">
  指示此部分是模型的思考/推理步骤。
</ResponseField>

<ResponseField name="candidates[].content.role" type="string">
  可能的值：`user`、`model`
</ResponseField>

<ResponseField name="candidates[].finishReason" type="string" />

<ResponseField name="candidates[].safetyRatings" type="object[]" />

<ResponseField name="candidates[].safetyRatings[].category" type="string">
  可能的值：`HARM_CATEGORY_SEXUALLY_EXPLICIT`、`HARM_CATEGORY_HATE_SPEECH`、`HARM_CATEGORY_HARASSMENT`、`HARM_CATEGORY_DANGEROUS_CONTENT`
</ResponseField>

<ResponseField name="candidates[].safetyRatings[].probability" type="string">
  内容违反指定安全类别的概率

  可能的值：`NEGLIGIBLE`、`LOW`、`MEDIUM`、`HIGH`、`UNKNOWN`
</ResponseField>

<ResponseField name="createTime" type="string">
  创建响应时的时间戳。
</ResponseField>

<ResponseField name="modelVersion" type="string">
  用于生成响应的模型版本。
</ResponseField>

<ResponseField name="promptFeedback" type="object" />

<ResponseField name="promptFeedback.blockReason" type="string" />

<ResponseField name="promptFeedback.blockReasonMessage" type="string" />

<ResponseField name="promptFeedback.safetyRatings" type="object[]" />

<ResponseField name="promptFeedback.safetyRatings[].category" type="string">
  内容所属的安全类别。

  可能的值：`HARM_CATEGORY_SEXUALLY_EXPLICIT`、`HARM_CATEGORY_HATE_SPEECH`、`HARM_CATEGORY_HARASSMENT`、`HARM_CATEGORY_DANGEROUS_CONTENT`
</ResponseField>

<ResponseField name="promptFeedback.safetyRatings[].probability" type="string">
  内容违反指定安全类别的概率。

  可能的值：`NEGLIGIBLE`、`LOW`、`MEDIUM`、`HIGH`、`UNKNOWN`
</ResponseField>

<ResponseField name="responseId" type="string">
  响应的唯一标识符。
</ResponseField>

<ResponseField name="usageMetadata" type="object" />

<ResponseField name="usageMetadata.cachedContentTokenCount" type="integer">
  仅输出。输入中缓存部分（即缓存内容）的 token 数量。
</ResponseField>

<ResponseField name="usageMetadata.candidatesTokenCount" type="integer">
  响应中的 token 数量。
</ResponseField>

<ResponseField name="usageMetadata.candidatesTokensDetails" type="object[]">
  按模态划分的候选 token 明细。
</ResponseField>

<ResponseField name="usageMetadata.candidatesTokensDetails[].modality" type="string">
  输入或输出内容的模态类型。

  可能的值：`MODALITY_UNSPECIFIED`、`TEXT`、`IMAGE`、`VIDEO`、`AUDIO`、`DOCUMENT`
</ResponseField>

<ResponseField name="usageMetadata.candidatesTokensDetails[].tokenCount" type="integer">
  给定模态的 token 数量。
</ResponseField>

<ResponseField name="usageMetadata.promptTokenCount" type="integer">
  请求中的 token 数量。设置 cachedContent 时，这仍然是提示词的有效总大小，也就是说它包含缓存内容中的 token 数量。
</ResponseField>

<ResponseField name="usageMetadata.promptTokensDetails" type="object[]">
  按模态划分的提示词 token 明细。
</ResponseField>

<ResponseField name="usageMetadata.promptTokensDetails[].modality" type="string">
  输入或输出内容的模态类型。

  可能的值：`MODALITY_UNSPECIFIED`、`TEXT`、`IMAGE`、`VIDEO`、`AUDIO`、`DOCUMENT`
</ResponseField>

<ResponseField name="usageMetadata.promptTokensDetails[].tokenCount" type="integer">
  给定模态的 token 数量。
</ResponseField>

<ResponseField name="usageMetadata.thoughtsTokenCount" type="integer">
  thoughts 输出中包含的 token 数量。
</ResponseField>

<ResponseField name="usageMetadata.toolUsePromptTokenCount" type="integer">
  工具使用提示词中包含的 token 数量。
</ResponseField>

<ResponseField name="usageMetadata.toolUsePromptTokensDetails" type="object[]">
  按模态划分的工具使用提示词 token 明细。
</ResponseField>

<ResponseField name="usageMetadata.toolUsePromptTokensDetails[].modality" type="string">
  输入或输出内容的模态类型。

  可能的值：`MODALITY_UNSPECIFIED`、`TEXT`、`IMAGE`、`VIDEO`、`AUDIO`、`DOCUMENT`
</ResponseField>

<ResponseField name="usageMetadata.toolUsePromptTokensDetails[].tokenCount" type="integer">
  给定模态的 token 数量。
</ResponseField>

<ResponseField name="usageMetadata.totalTokenCount" type="integer">
  token 总数（提示词 + 候选）。
</ResponseField>

<ResponseField name="usageMetadata.trafficType" type="string">
  请求使用的流量类型（例如 PROVISIONED\_THROUGHPUT）。
</ResponseField>

## 示例

### 输入

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

### 输出

```json theme={null}
{
  "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 会过期](/zh/development/comfy-router/reference#结果资产)。

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

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

<CardGroup cols={3}>
  <Card title="请求头" icon="list" href="/zh/development/comfy-router/headers">
    身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
  </Card>

  <Card title="使用 Router API" icon="code" href="/zh/development/comfy-router/api">
    模型发现、验证错误、重试与计费。
  </Card>

  <Card title="限制" icon="triangle-exclamation" href="/zh/development/comfy-router/limitations">
    Router 目前不支持的功能，以及替代方案。
  </Card>
</CardGroup>


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