PayGo prioritário

O pagamento por uso prioritário (Priority PayGo) é uma opção de consumo que oferece desempenho mais consistente do que o pagamento por uso padrão sem o compromisso inicial da capacidade de processamento provisionada.

Ao usar o Priority PayGo, você paga por uso de token a uma taxa mais alta do que o pagamento por uso padrão. Para informações sobre preços, consulte a página de preços da plataforma de agentes do Gemini Enterprise.

Quando usar o Priority PayGo

O Priority PayGo é ideal para cargas de trabalho essenciais para os negócios com padrões de tráfego flutuantes ou imprevisíveis. Confira alguns exemplos de casos de uso:

  • Assistentes virtuais voltados para o cliente
  • Fluxos de trabalho agênticos e interações entre agentes
  • Simulações de pesquisa

Modelos e locais compatíveis

Os modelos a seguir oferecem suporte ao Priority PayGo apenas no endpoint global. O Priority PayGo não oferece suporte a endpoints regionais ou multirregionais.

Usar o Priority PayGo

Para enviar solicitações à API Gemini na plataforma de agentes do Gemini Enterprise usando o Priority PayGo, inclua o cabeçalho X-Vertex-AI-LLM-Shared-Request-Type na solicitação. Você pode usar o Priority PayGo de duas maneiras:

  • Usar a cota de capacidade de processamento provisionada (se disponível) e passar para o Priority PayGo.

  • Usar apenas o Priority PayGo.

Usar o Priority PayGo com a capacidade de processamento provisionada como padrão

Para usar qualquer cota de capacidade de processamento provisionada disponível antes de usar o Priority PayGo, inclua o cabeçalho X-Vertex-AI-LLM-Shared-Request-Type: priority nas solicitações, conforme mostrado nos exemplos a seguir.

Python

Instalar

pip install --upgrade google-genai

Para mais informações, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a 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_VERTEXAI=True

Inicialize o cliente de IA generativa para usar o Priority PayGo. Depois de realizar essa etapa, não será necessário fazer mais ajustes no código para interagir com a API Gemini usando o Priority PayGo no mesmo cliente.

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

Depois de configurou seu ambiente use REST para testar uma solicitação de texto. O exemplo a seguir envia uma solicitação ao publisher endpoint do modelo.

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: seu [ID do projeto](/resource-manager/docs/creating-managing-projects#identifiers). .
  • MODEL_ID: o ID do modelo para o qual você quer inicializar o Priority PayGo. Para uma lista de modelos que oferecem suporte ao Priority PayGo, consulte Versões de modelo.
  • PROMPT_TEXT: As instruções de texto a serem incluídas no comando. 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" }
    }
  }'

Você receberá uma resposta JSON semelhante a seguinte.

{
  "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
  }
}
  • Use o generateContent método para solicitar que a resposta seja retornada depois de ser totalmente gerada. Para reduzir a percepção de latência ao público humano, transmita a resposta à medida que geradas usando o streamGenerateContent método.
  • O ID do modelo multimodal está localizado no final do URL, antes do método (Por exemplo, gemini-2.0-flash). Este exemplo pode oferecer suporte a outras modelos de classificação.

Usar apenas o Priority PayGo

Para usar apenas o Priority PayGo, inclua os cabeçalhos X-Vertex-AI-LLM-Request-Type: shared e X-Vertex-AI-LLM-Shared-Request-Type: priority nas solicitações, conforme mostrado nos exemplos a seguir.

Python

Instalar

pip install --upgrade google-genai

Para mais informações, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a 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_VERTEXAI=True

Inicialize o cliente de IA generativa para usar o Priority PayGo. Depois de realizar essa etapa, não será necessário fazer mais ajustes no código para interagir com a API Gemini usando o Priority PayGo no mesmo cliente.

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

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: seu [ID do projeto](/resource-manager/docs/creating-managing-projects#identifiers). .
  • MODEL_ID: o ID do modelo para o qual você quer inicializar o Priority PayGo. Para uma lista de modelos que oferecem suporte ao Priority PayGo, consulte Versões de modelo.
  • PROMPT_TEXT: As instruções de texto a serem incluídas no comando. 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" }
    }
  }'

Você receberá uma resposta JSON semelhante a seguinte.

{
  "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
  }
}
  • Use o generateContent método para solicitar que a resposta seja retornada depois de ser totalmente gerada. Para reduzir a percepção de latência ao público humano, transmita a resposta à medida que geradas usando o streamGenerateContent método.
  • O ID do modelo multimodal está localizado no final do URL, antes do método (Por exemplo, gemini-2.0-flash). Este exemplo pode oferecer suporte a outras modelos de classificação.

Verificar o uso do Priority PayGo

É possível verificar se uma solicitação usou o Priority PayGo no tipo de tráfego na resposta, conforme mostrado nos exemplos a seguir.

Python

É possível verificar se o Priority PayGo foi usado para uma solicitação no campo traffic_type na resposta. Se a solicitação foi processada usando o Priority PayGo, o campo traffic_type será definido como 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

É possível verificar se o Priority PayGo foi usado para uma solicitação no campo trafficType na resposta. Se a solicitação foi processada usando o Priority PayGo, o campo trafficType será definido como 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
  }
}

Limites de aumento

O Priority PayGo define limites de aumento no nível da organização. Os limites de aumento ajudam a fornecer um desempenho previsível e consistente. O limite inicial depende do modelo, conforme mostrado abaixo:

  • Modelos do Gemini Flash e Flash-Lite:4 milhões de tokens/min.
  • Modelos do Gemini Pro:1 milhão de tokens/min.

O limite de aumento aumenta em 50% a cada 10 minutos de uso contínuo.

Se uma solicitação exceder o limite de aumento ou o sistema estiver temporariamente com capacidade excessiva devido a cargas de tráfego altas, a solicitação poderá ser rebaixada para o pagamento por uso padrão e será cobrada nas taxas do pagamento por uso padrão.

Para minimizar os rebaixamentos, dimensione o uso de forma incremental para permanecer dentro do limite. Se você ainda precisar de um desempenho melhor, considere comprar uma cota adicional de capacidade de processamento provisionada.

É possível verificar se uma solicitação foi rebaixada na resposta. Para solicitações rebaixadas para o pagamento por uso padrão, o tipo de tráfego é definido como ON_DEMAND. Para mais informações, consulte Verificar o uso do Priority PayGo.

A seguir