優先即付即用

「優先即付即用」模式會按用量計費，效能比「標準即付即用」模式更穩定，而且不必像「佈建輸送量」模式一樣，預留資源並預付費用。

使用「優先即付即用」模式時，系統會依權杖用量計費，費率比「標準即付即用」模式高。如要瞭解定價，請參閱 Gemini Enterprise Agent Platform 定價頁面。

何時適合使用 Priority PayGo

Priority PayGo 適合流量模式波動或無法預測的重要業務工作負載。以下是範例用途：

  • 面向顧客的虛擬助理
  • Agentic Workflows 和跨代理互動
  • 研究模擬

支援的機型和地區

一般來說，global、us 和 eu 端點都支援「優先即付即用」模式。不過，部分模型 (例如 Gemini 2.5 模型) 可能不支援所有三個端點。請前往 Google 模型頁面，點選各個模型的連結，查看使用 Priority PayGo 時支援哪些端點。

下列機型支援優先 PayGo：

使用 Priority PayGo

如要使用 Priority PayGo 向 Gemini API 傳送要求，必須在要求中加入 X-Vertex-AI-LLM-Shared-Request-Type 標頭。您可以使用 Priority PayGo 執行下列操作：

  • 使用佈建輸送量配額 (如有)，並溢出至優先即付即用。

  • 只能使用優先 PayGo。

下列範例使用 global 端點。如要改為將要求傳送至多區域端點，請將 global 替換為 us 或 eu。如果是 REST 要求，您也必須將 aiplatform.googleapis.com 主機名稱替換為 aiplatform.us.rep.googleapis.com 或 aiplatform.eu.rep.googleapis.com。詳情請參閱「多區域端點」。

使用優先即付即用模式，並將佈建輸送量設為預設模式

如要在使用 Priority PayGo 前先用完可用的佈建輸送量配額，請在要求中加入 X-Vertex-AI-LLM-Shared-Request-Type: priority 標頭，如下列範例所示。

Python

安裝

pip install --upgrade google-genai

詳情請參閱 SDK 參考文件。

設定環境變數，以便透過 Vertex AI 使用 Google Gen AI SDK： 

# 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 用戶端，即可使用 Priority PayGo。完成這個步驟後，您不需要進一步調整程式碼，即可在同一個用戶端上，使用 Priority PayGo 與 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": "priority"
      },
  )
)

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-Vertex-AI-LLM-Shared-Request-Type: priority" \
  "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_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}
  • 使用 generateContent 方法要求系統在完整生成回覆後傳回。 如要減少人類觀眾對延遲的感受，請使用 streamGenerateContent 方法，在生成回覆的同時串流回覆內容。
  • 多模態模型 ID 位於網址結尾，方法之前 (例如 gemini-3.5-flash)。這個範例也可能支援其他模型。

僅使用優先 PayGo

如要只使用 Priority PayGo，請在要求中加入 X-Vertex-AI-LLM-Request-Type: shared 和 X-Vertex-AI-LLM-Shared-Request-Type: priority 標頭，如下列範例所示。

Python

安裝

pip install --upgrade google-genai

詳情請參閱 SDK 參考文件。

設定環境變數，以便透過 Vertex AI 使用 Google Gen AI SDK： 

# 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 用戶端，即可使用 Priority PayGo。完成這個步驟後，您不需要進一步調整程式碼，即可在同一個用戶端上，使用 Priority PayGo 與 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": "priority"
      },
  )
)

REST

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：您的專案 ID。。
  • MODEL_ID：要初始化 Priority PayGo 的模型 ID。如要查看支援 Priority PayGo 的模型清單，請參閱「模型版本」。
  • PROMPT_TEXT：要加入提示的文字指令。JSON。
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Vertex-AI-LLM-Request-Type: shared" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: priority" \
  "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_PRIORITY",
    "thoughtsTokenCount": 1054
  }
}
  • 使用 generateContent 方法，要求在回覆完全生成後傳回。如要減少人類觀眾對延遲時間的感知，請使用 streamGenerateContent 方法，在生成回覆時串流回覆。
  • 多模態模型 ID 位於網址結尾，方法之前 (例如 gemini-3.5-flash)。這個範例也可能支援其他模型。

驗證 Priority PayGo 用量

如要確認要求是否使用 Priority PayGo，請查看回應中的流量類型，如下列範例所示。

Python

您可以透過回應中的 traffic_type 欄位，確認要求是否使用優先 PayGo。如果要求是透過 Priority PayGo 處理，traffic_type 欄位會設為 ON_DEMAND_PRIORITY。

sdk_http_response=HttpResponse(
  headers=<dict len=9>
) 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_PRIORITY: 'ON_DEMAND_PRIORITY'>
) automatic_function_calling_history=[] parsed=None

REST

您可以透過回應中的 trafficType 欄位，確認要求是否使用優先 PayGo。如果要求是透過 Priority PayGo 處理，trafficType 欄位會設為 ON_DEMAND_PRIORITY。

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

處理量限制

「優先即付即用」模式會為每個模型提供機構層級的基準輸送量限制：

  • Gemini Pro 模型：每分鐘 10,000,000 個權杖
  • Gemini Flash 和 Flash-Lite 模型：每分鐘 5,000 萬個符記

貴組織可立即使用這些限制。沒有適應期，也不需要先累積用量才能達到這些限制。與標準 PayGo 類似，模型系列顯示的處理量限制，會分別套用至該系列中的各個模型。

超過上限的流量不會自動降級。如有可用容量，Agent Platform 會優先處理該流量，並按照「優先即付即用」費率計費。只有在沒有多餘容量可優先處理要求時，要求才會降級為標準即付即用，並按照標準即付即用費率計費。

您可以從回應中確認要求是否降級。如果要求降級為標準即付即用方案，流量類型會設為 ON_DEMAND。詳情請參閱「驗證優先 PayGo 使用情形」。

為減少降級的機率，請在每分鐘內平均分配流量，而不是傳送尖峰流量。如果工作負載需要較高的限制，請與銷售團隊聯絡。如要為工作負載提供專屬的保證容量，請參閱「佈建輸送量」。

後續步驟