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, você paga 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 PayGo prioritário

O PayGo prioritário é 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
  • Agentic workflows e interações entre agentes
  • Análise de Conteúdo: simulações

Modelos e locais compatíveis

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

Os seguintes modelos oferecem suporte ao PayGo prioritário:

Usar o PayGo prioritário

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

  • Usar a cota de Capacidade de Processamento Provisionada (se disponível) e passar para o PayGo prioritário.

  • Usar apenas o PayGo prioritário.

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 PayGo prioritário, 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 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 o cliente GenAI para usar o PayGo prioritário. Depois de executar esta etapa, não será necessário fazer mais ajustes no código para interagir com a API Gemini usando o PayGo prioritário 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 publisher endpoint do modelo.

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 PayGo prioritário. Para uma lista de modelos que oferecem suporte ao PayGo prioritário, 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-3.5-flash). Este exemplo também pode oferecer suporte a outros modelos.

Usar apenas o PayGo prioritário

Para usar apenas o PayGo prioritário, 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 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 o cliente GenAI para usar o PayGo prioritário. Depois de executar esta etapa, não será necessário fazer mais ajustes no código para interagir com a API Gemini usando o PayGo prioritário 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 PayGo prioritário. Para uma lista de modelos que oferecem suporte ao PayGo prioritário, 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-3.5-flash). Este exemplo também pode oferecer suporte a outros modelos.

Verificar o uso do PayGo prioritário

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

Python

É possível verificar se o PayGo prioritário foi usado para uma solicitação no campo traffic_type da resposta. Se a solicitação foi processada usando o PayGo prioritário, 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 PayGo prioritário foi usado para uma solicitação no campo trafficType da resposta. Se a solicitação foi processada usando o PayGo prioritário, 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 de referência no nível da organização para cada modelo:

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

Esses limites estão disponíveis para sua organização imediatamente. Não há período de aumento e não é necessário criar um uso sustentado antes de alcançá-los. Assim como o PayGo 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 limite não é rebaixado automaticamente. Quando a capacidade está disponível, a Plataforma de agentes continua a atender esse tráfego com prioridade, e ele é faturado nas taxas do PayGo prioritário. As solicitações são rebaixadas para o PayGo padrão somente quando não há capacidade extra para atendê-las com prioridade, e essas solicitações são faturadas nas taxas do PayGo padrão.

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

Para reduzir a chance de um rebaixamento, 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