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

# 使用 Gemini 3.1 Flash Lite 与 Comfy Router

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

`vertexai/gemini-3.1-flash-lite` 的 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.1-flash-lite`

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

<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.1-flash-lite",
              {
                  "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.1-flash-lite", {
        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.1-flash-lite \
        -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.1-flash-lite/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.1-flash-lite",
                  {
                      "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.1-flash-lite", {
        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.1-flash-lite/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.1-flash-lite/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-lite/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

  格式：`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 个单词。

  范围：`16` 到 `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">
  可选。如果为 true，模型会在响应中包含它的思考内容。
</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>
  构成单条消息的有序 parts 列表。不同的 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[]">
  一段代码，使系统能够与外部系统交互，以执行模型知识和范围之外的一个操作或一组操作。请参阅函数调用。
</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 值。

  Range: `0` to `999999999`
</ParamField>

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

  Range: `-315576000000` to `315576000000`
</ParamField>

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

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

  Range: `0` to `999999999`
</ParamField>

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

  Range: `-315576000000` to `315576000000`
</ParamField>

根据 Router 在 `GET /v2/models/vertexai/gemini-3.1-flash-lite/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">
  Possible values: `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">
  思考输出中存在的 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.1-flash-lite",
  "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.