Priority PayGo

Bayar sesuai penggunaan prioritas (Priority PayGo) adalah opsi konsumsi yang memberikan performa lebih konsisten daripada PayGo Standar tanpa komitmen di muka Throughput yang Disediakan.

Saat menggunakan Priority PayGo, Anda akan dikenai biaya per penggunaan token dengan tarif yang lebih tinggi daripada Standard PayGo. Untuk mengetahui informasi tentang harga, lihat halaman harga Gemini Enterprise Agent Platform.

Kapan harus menggunakan PayGo Prioritas

Priority PayGo ideal untuk workload penting bisnis dengan pola traffic yang berfluktuasi atau tidak dapat diprediksi. Berikut adalah contoh kasus penggunaan:

  • Asisten virtual yang ditampilkan kepada pelanggan
  • Alur kerja agentic dan interaksi lintas agen
  • Simulasi riset

Model dan lokasi yang didukung

Secara umum, Priority PayGo didukung di endpoint global, us, dan eu. Namun, beberapa model (seperti model Gemini 2.5) mungkin tidak mendukung ketiga endpoint tersebut. Periksa setiap halaman model yang ditautkan dari model Google untuk melihat endpoint yang didukung saat menggunakan Priority PayGo.

Model berikut mendukung Priority PayGo:

Menggunakan PayGo Prioritas

Untuk mengirim permintaan ke Gemini API menggunakan Priority PayGo, Anda harus menyertakan header X-Vertex-AI-LLM-Shared-Request-Type dalam permintaan Anda. Anda dapat menggunakan Priority PayGo dengan dua cara:

  • Menggunakan kuota Throughput yang Disediakan (jika tersedia) dan beralih ke PayGo Prioritas.

  • Hanya menggunakan PayGo Prioritas.

Contoh berikut menggunakan endpoint global. Untuk mengirim permintaan ke endpoint multi-region, ganti global dengan us atau eu. Untuk permintaan REST, Anda juga harus mengganti nama host aiplatform.googleapis.com dengan aiplatform.us.rep.googleapis.com atau aiplatform.eu.rep.googleapis.com. Untuk mengetahui informasi selengkapnya, lihat Endpoint multi-region.

Menggunakan PayGo Prioritas saat menggunakan Throughput yang Disediakan sebagai default

Untuk memanfaatkan kuota Throughput yang Disediakan yang tersedia sebelum menggunakan Priority PayGo, sertakan header X-Vertex-AI-LLM-Shared-Request-Type: priority dalam permintaan Anda, seperti yang ditunjukkan dalam contoh berikut.

Python

Instal

pip install --upgrade google-genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan 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

Lakukan inisialisasi klien GenAI Anda untuk menggunakan PayGo Prioritas. Setelah melakukan langkah ini, Anda tidak perlu melakukan penyesuaian lebih lanjut pada kode untuk berinteraksi dengan Gemini API menggunakan Priority PayGo pada klien yang sama.

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

Setelah menyiapkan lingkungan, Anda dapat menggunakan REST untuk menguji perintah teks. Contoh berikut mengirimkan permintaan ke endpoint model penayang.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Anda. .
  • MODEL_ID: ID model dari model yang ingin Anda inisialisasi Priority PayGo-nya. Untuk mengetahui daftar model yang mendukung Priority PayGo, lihat Versi model.
  • PROMPT_TEXT: Petunjuk teks yang akan disertakan dalam perintah. 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" }
    }
  }'

Anda akan menerima respons JSON yang mirip dengan berikut ini.

{
  "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
  }
}
  • Gunakan metode generateContent untuk meminta agar respons ditampilkan setelah dibuat sepenuhnya. Untuk mengurangi persepsi latensi bagi audiens manusia, lakukan streaming respons saat respons tersebut dibuat menggunakan metode streamGenerateContent.
  • ID model multimodal terletak di akhir URL sebelum metode (misalnya, gemini-3.5-flash). Contoh ini mungkin juga mendukung model lain.

Hanya menggunakan PayGo Prioritas

Untuk hanya menggunakan Priority PayGo, sertakan header X-Vertex-AI-LLM-Request-Type: shared dan X-Vertex-AI-LLM-Shared-Request-Type: priority dalam permintaan Anda, seperti yang ditunjukkan dalam contoh berikut.

Python

Instal

pip install --upgrade google-genai

Untuk mempelajari lebih lanjut, lihat dokumentasi referensi SDK.

Tetapkan variabel lingkungan untuk menggunakan Google Gen AI SDK dengan 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

Lakukan inisialisasi klien GenAI Anda untuk menggunakan PayGo Prioritas. Setelah melakukan langkah ini, Anda tidak perlu melakukan penyesuaian lebih lanjut pada kode untuk berinteraksi dengan Gemini API menggunakan Priority PayGo pada klien yang sama.

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

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Anda. .
  • MODEL_ID: ID model dari model yang ingin Anda inisialisasi Priority PayGo-nya. Untuk mengetahui daftar model yang mendukung Priority PayGo, lihat Versi model.
  • PROMPT_TEXT: Petunjuk teks yang akan disertakan dalam perintah. 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" }
    }
  }'

Anda akan menerima respons JSON yang mirip dengan berikut ini.

{
  "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
  }
}
  • Gunakan metode generateContent untuk meminta agar respons ditampilkan setelah dibuat sepenuhnya. Untuk mengurangi persepsi latensi bagi audiens manusia, lakukan streaming respons saat respons tersebut dibuat menggunakan metode streamGenerateContent.
  • ID model multimodal terletak di akhir URL sebelum metode (misalnya, gemini-3.5-flash). Contoh ini mungkin juga mendukung model lain.

Memverifikasi penggunaan PayGo Prioritas

Anda dapat memverifikasi apakah permintaan menggunakan Priority PayGo dari jenis traffic dalam respons, seperti yang ditunjukkan dalam contoh berikut.

Python

Anda dapat memverifikasi apakah Priority PayGo digunakan untuk permintaan dari kolom traffic_type dalam respons. Jika permintaan Anda diproses menggunakan Priority PayGo, kolom traffic_type akan ditetapkan ke 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

Anda dapat memverifikasi apakah Priority PayGo digunakan untuk permintaan dari kolom trafficType dalam respons. Jika permintaan Anda diproses menggunakan Priority PayGo, kolom trafficType akan ditetapkan ke 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
  }
}

Batas throughput

Priority PayGo memberikan batas throughput dasar di tingkat organisasi untuk setiap model:

  • Model Gemini Pro, Carbon, dan Argon: 10.000.000 token per menit
  • Model Gemini Flash, Flash-Lite, dan Hydrogen: 50.000.000 token per menit

Batas ini langsung tersedia untuk organisasi Anda. Tidak ada periode penyesuaian, dan tidak perlu membangun penggunaan berkelanjutan sebelum Anda dapat mencapainya. Serupa dengan PayGo Standar, batas throughput yang ditampilkan untuk kelompok model berlaku secara independen untuk setiap model dalam kelompok tersebut.

Traffic di atas batas Anda tidak akan otomatis didowngrade. Jika kapasitas tersedia, Agent Platform akan terus menyalurkan traffic tersebut dengan prioritas, dan akan ditagih dengan tarif PayGo Prioritas. Permintaan akan didowngrade ke Standard PayGo hanya jika tidak ada kapasitas cadangan untuk menyajikannya dengan prioritas, dan permintaan tersebut akan ditagih dengan tarif Standard PayGo.

Anda dapat memverifikasi apakah permintaan di-downgrade dari respons. Untuk permintaan yang didowngrade ke PayGo Standar, jenis traffic ditetapkan ke ON_DEMAND. Untuk mengetahui informasi selengkapnya, lihat Memverifikasi penggunaan PayGo Prioritas.

Untuk mengurangi kemungkinan downgrade, lancarkan traffic setiap menit, bukan mengirimkan lonjakan tajam di tingkat detik. Jika workload Anda memerlukan batas yang lebih tinggi, hubungi tim penjualan Anda. Untuk workload yang memerlukan kapasitas khusus dan terjamin, lihat Throughput yang Disediakan.

Langkah berikutnya