Flex PayGo

灵活随用随付 (Flex PayGo) 是一种经济实惠的选项，可用于访问 Gemini 模型，以处理能够容忍较长响应时间和较高限制的非关键工作负载。与标准按需付费相比，灵活按需付费可享受 50% 的折扣。

何时使用灵活按需付费

灵活按需付费非常适合同步、能够容忍延迟且对时间不敏感的非关键任务。以下是一些示例用例：

  • 离线分析文本、文档、图片、音频和视频文件

  • 评估模型质量

  • 数据注解和标签

  • 文档翻译

  • 构建商品目录

支持的模型和位置

以下预览版 Gemini 模型仅在global 端点中支持灵活按需付费。灵活按需付费不支持区域级或多区域级端点。

请求载荷限制

对于直接在请求正文中包含载荷的请求，灵活按需付费请求的总载荷大小限制为 20 MB。如需处理更大的文件，请在请求中提供 Cloud Storage URI。

使用灵活按需付费

如需使用灵活按需付费向 Gemini API 发送请求，您必须在请求中添加 X-Vertex-AI-LLM-Shared-Request-Type 标头。您可以通过以下两种方式使用灵活按需付费：

  • 先使用预配吞吐量配额（如果有），然后使用灵活按需付费。

  • 仅使用灵活按需付费。

请注意，与标准按需付费相比，使用灵活按需付费的请求的预期延迟时间更长。

您可以将请求超时时间设置为最长 30 分钟。

在将预配吞吐量用作默认值时使用灵活按需付费

如需在使用灵活按需付费之前利用任何可用的预配吞吐量配额，请在请求中添加标头 X-Vertex-AI-LLM-Shared-Request-Type: flex，如以下示例所示。

Python

安装

pip install --upgrade google-genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用： 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

初始化 GenAI 客户端以使用灵活按需付费。完成此步骤后，您无需对代码进行进一步调整，即可在同一客户端上使用灵活按需付费与 Gemini API 进行交互。

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(
  vertexai=True, project='your_project_id', location='global',
  http_options=HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Shared-Request-Type": "flex"
      },
    # timeout = 600000  # Timeout in milliseconds
  )
)

REST

设置您的环境后，您可以使用 REST 测试文本提示。以下示例会向发布方模型端点发送请求。

在使用任何请求数据之前，请先进行以下替换。

  • PROJECT_ID：您的 项目 ID。
  • MODEL_ID：您要为其初始化灵活按需付费的模型的模型 ID 。如需查看支持 灵活按需付费的模型列表，请参阅模型版本。
  • PROMPT_TEXT： 要包含在提示中的文本说明。 JSON。
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Server-Timeout: 600" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: flex" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

您应该收到类似以下内容的 JSON 响应。

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_FLEX",
    "thoughtsTokenCount": 1054
  }
}
请注意此示例的网址中的以下内容：
  • 使用 generateContent 方法请求在回答完全生成后返回回答。 为了降低真人观众对于延迟的感知度，请使用 streamGenerateContent 方法在生成回答时流式传输回答。
  • 多模态模型 ID 位于网址末尾且位于方法之前 （例如 gemini-2.5-flash）。此示例可能还支持其他 模型。
  • 当您使用区域级 API 端点（例如 us-central1）时，端点网址中的区域会决定请求的处理位置。资源路径中的任何冲突位置都会被忽略。

仅使用灵活按需付费

如需仅使用灵活按需付费，请在请求中添加标头 X-Vertex-AI-LLM-Request-Type: shared 和 X-Vertex-AI-LLM-Shared-Request-Type: flex，如以下示例所示。

Python

安装

pip install --upgrade google-genai

如需了解详情，请参阅 SDK 参考文档。

设置环境变量以将 Gen AI SDK 与 Vertex AI 搭配使用： 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

初始化 GenAI 客户端以使用灵活按需付费。完成此步骤后，您无需对代码进行进一步调整，即可在同一客户端上使用灵活按需付费与 Gemini API 进行交互。

from google import genai
from google.genai.types import HttpOptions
client = genai.Client(
  vertexai=True, project='your_project_id', location='global',
  http_options=HttpOptions(
    api_version="v1",
      headers={
        "X-Vertex-AI-LLM-Request-Type": "shared",
        "X-Vertex-AI-LLM-Shared-Request-Type": "flex"
      },
    # timeout = 600000  # Timeout in milliseconds
  )
)

REST

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您的 项目 ID。
  • MODEL_ID：您要为其初始化灵活按需付费的模型的模型 ID 。如需查看支持 灵活按需付费的模型列表，请参阅模型版本。
  • PROMPT_TEXT： 要包含在提示中的文本说明。 JSON。
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Server-Timeout: 600" \
  -H "X-Vertex-AI-LLM-Request-Type: shared" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: flex" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL_ID:generateContent" -d \
  $'{
      "contents": {
        "role": "model",
        "parts": { "text": "PROMPT_TEXT" }
    }
  }'

您应该收到类似以下内容的 JSON 响应。

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_FLEX",
    "thoughtsTokenCount": 1054
  }
}
请注意此示例的网址中的以下内容：
  • 使用 generateContent 方法请求在回答完全生成后返回回答。 为了降低真人观众对于延迟的感知度，请使用 streamGenerateContent 方法在生成回答时流式传输回答。
  • 多模态模型 ID 位于网址末尾且位于方法之前 （例如 gemini-2.5-flash）。此示例可能还支持其他 模型。
  • 当您使用区域级 API 端点（例如 us-central1）时，端点网址中的区域会决定请求的处理位置。资源路径中的任何冲突位置都会被忽略。

验证灵活按需付费的使用情况

您可以从响应中的流量类型验证请求是否使用了灵活按需付费，如以下示例所示。

Python

您可以从响应中的 traffic_type 字段验证请求是否使用了灵活按需付费。如果您的请求是使用灵活按需付费处理的，则 traffic_type 字段会设置为 ON_DEMAND_FLEX。

sdk_http_response=HttpResponse(
  headers=
) candidates=[Candidate(
  avg_logprobs=-0.539712212302468,
  content=Content(
    parts=[
      Part(
        text="""Response to sample request.
        """
      ),
    ],
    role='model'
  ),
  finish_reason=<FinishReason.STOP: 'STOP'>
)] create_time=datetime.datetime(2025, 12, 3, 20, 32, 55, 916498, tzinfo=TzInfo(0)) model_version='gemini-2.5-flash' prompt_feedback=None response_id='response_id' usage_metadata=GenerateContentResponseUsageMetadata(
  candidates_token_count=1408,
  candidates_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=1408
    ),
  ],
  prompt_token_count=5,
  prompt_tokens_details=[
    ModalityTokenCount(
      modality=<MediaModality.TEXT: 'TEXT'>,
      token_count=5
    ),
  ],
  thoughts_token_count=1356,
  total_token_count=2769,
  traffic_type=<TrafficType.ON_DEMAND_FLEX: 'ON_DEMAND_FLEX'>
) automatic_function_calling_history=[] parsed=None

REST

您可以从响应中的 trafficType 字段验证请求是否使用了灵活按需付费。如果您的请求是使用灵活按需付费处理的，则 trafficType 字段会设置为 ON_DEMAND_FLEX。

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_FLEX",
    "thoughtsTokenCount": 1054
  }
}

灵活按需付费的额外配额

除了内容生成请求的可用配额（包括溢出流量的预配吞吐量配额）之外，使用灵活按需付费的请求还受以下配额的约束：

说明 项目中每个基础模型的 QPM
项目中每个基础模型使用灵活按需付费的请求的配额 3000

后续步骤

资源

与 Agent Platform 相关的配额和限制。

资源

与 Agent Platform 相关的配额和限制，不包括特定于产品的限制。

概览

了解 Google Cloud 如何限制 Google Cloud 项目可使用的资源量，以及配额如何应用于一系列资源类型，包括硬件、软件和网络组件。