Prioridade PayGo

O pagamento por uso prioritário (PayGo prioritário) é uma opção de consumo que oferece um desempenho mais consistente do que o PayGo padrão, sem o compromisso inicial da Capacidade de Processamento Provisionada.

Ao usar o PayGo prioritário, a cobrança é feita por uso de token a uma taxa mais alta do que o PayGo padrão. Para informações sobre preços, consulte a página de preços da Gemini Enterprise Agent Platform.

Quando usar o Priority PayGo

O PayGo prioritário é ideal para cargas de trabalho essenciais 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
  • Análise de Conteúdo: simulações

Modelos e locais compatíveis

Em geral, o Priority PayGo é compatível com os endpoints global, us e eu. No entanto, alguns modelos (como os do Gemini 2.5) podem não ser compatíveis com todos os três endpoints. Confira as páginas de modelos individuais vinculadas em Modelos do Google para saber quais endpoints são compatíveis ao usar o Priority PayGo.

Os seguintes modelos são compatíveis com o PayGo prioritário:

Usar o Priority PayGo

Para enviar solicitações à API Gemini 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:

  • Use a cota de capacidade de processamento provisionada (se disponível) e transfira para o PayGo prioritário.

  • Use somente o Priority PayGo.

Os exemplos a seguir usam o endpoint global. Para enviar suas solicitações a um endpoint multirregional, substitua global por us ou eu. Para solicitações REST, também é necessário substituir o nome do host aiplatform.googleapis.com por aiplatform.us.rep.googleapis.com ou aiplatform.eu.rep.googleapis.com. Para mais informações, consulte Endpoints multirregionais.

Usar o PayGo prioritário com a capacidade de processamento provisionada como padrão

Para usar qualquer cota de capacidade de processamento provisionada disponível antes de usar o Pay as you go prioritário, inclua o cabeçalho X-Vertex-AI-LLM-Shared-Request-Type: priority nas suas solicitações, conforme mostrado nos exemplos a seguir.

Python

Instalar

pip install --upgrade google-genai

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

Defina variáveis de ambiente para usar o SDK de IA generativa do Google 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_ENTERPRISE=True

Inicialize seu 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 configurar seu ambiente, use REST para testar um comando de texto. O exemplo a seguir envia uma solicitação ao endpoint do modelo de editor.

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

  • PROJECT_ID: o ID do projeto. .
  • 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 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 .
  • O ID do modelo multimodal está localizado no final do URL, antes do método Por exemplo, gemini-3.5-flash). Este exemplo pode oferecer suporte a outros modelos de classificação.

Usar somente 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 suas solicitações, conforme mostrado nos exemplos a seguir.

Python

Instalar

pip install --upgrade google-genai

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

Defina variáveis de ambiente para usar o SDK de IA generativa do Google 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_ENTERPRISE=True

Inicialize seu 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: o ID do projeto. .
  • 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 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 .
  • O ID do modelo multimodal está localizado no final do URL, antes do método Por exemplo, gemini-3.5-flash). Este exemplo pode oferecer suporte a outros modelos de classificação.

Verificar o uso do Priority PayGo

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

Python

Você pode verificar se o Priority PayGo foi usado em uma solicitação do campo traffic_type na resposta. Se a solicitação foi processada usando 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

Você pode verificar se o Priority PayGo foi usado em uma solicitação do campo trafficType na resposta. Se a solicitação foi processada usando 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 capacidade de processamento

O PayGo prioritário oferece um limite de capacidade de processamento básico no nível da organização para cada modelo:

  • Modelos do Gemini Pro: 10.000.000 de tokens por minuto
  • Modelos Gemini Flash e Flash-Lite: 50.000.000 de tokens por minuto

Esses limites ficam disponíveis imediatamente para sua organização. Não há período de aumento gradual nem necessidade de criar um uso sustentado antes de alcançá-los. Assim como no Pay as you go padrão, o limite de capacidade de processamento mostrado para uma família de modelos se aplica de forma independente a cada modelo dessa família.

O tráfego acima do seu limite não é reduzido automaticamente. Quando a capacidade está disponível, a Plataforma de Agentes continua veiculando esse tráfego com prioridade, e ele é faturado de acordo com as taxas do PayGo prioritário. As solicitações são rebaixadas para o PayGo padrão somente quando não há capacidade disponível para atendê-las com prioridade, e essas solicitações são faturadas com as taxas do PayGo padrão.

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

Para reduzir a chance de um downgrade, suavize o tráfego a cada minuto em vez de enviar picos acentuados de segundo nível. Se a carga de trabalho exigir um limite maior, entre em contato com a equipe de vendas. Para cargas de trabalho que precisam de capacidade dedicada e garantida, consulte Capacidade de processamento provisionada.

A seguir