PayGo prioritário

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

Ao usar o Priority PayGo, 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 Vertex AI.

Quando usar o PayGo prioritário

O PayGo prioritário é ideal para cargas de trabalho sensíveis à latência e críticas com padrões de tráfego flutuantes ou imprevisíveis. Confira alguns exemplos de casos de uso:

  • Assistentes virtuais voltados para o cliente

  • Processamento de dados e documentos sensíveis à latência

  • Fluxos de trabalho com agentes e interações entre agentes

  • Simulações de pesquisa

Modelos e locais compatíveis

Os seguintes modelos são compatíveis com o Priority PayGo apenas no endpoint global. O Priority PayGo não é compatível com endpoints regionais ou multirregionais.

Usar o PayGo prioritário

Para enviar solicitações à API Gemini na Vertex AI usando o PayGo prioritário, inclua o cabeçalho X-Vertex-AI-LLM-Shared-Request-Type na sua 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 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 do PayGo 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 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 seu cliente de IA generativa para usar o Priority PayGo. Depois de realizar esta 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: 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
  }
}
Observe o seguinte no URL deste exemplo:
  • 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-2.0-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 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 seu cliente de IA generativa para usar o Priority PayGo. Depois de realizar esta 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
  }
}
Observe o seguinte no URL deste exemplo:
  • 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-2.0-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 Priority PayGo pelo tipo de tráfego na resposta, conforme mostrado nos exemplos a seguir.

Python

É possível verificar se o Priority PayGo foi usado em uma solicitação no campo traffic_type da 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=
) candidates=[Candidate(
  avg_logprobs=-0.539712212302468,
  content=Content(
    parts=[
      Part(
        text="""Response to sample request.
        """
      ),
    ],
    role='model'
  ),
  finish_reason=nishReason.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=ty.TEXT: 'TEXT'>,
      token_count=1408
    ),
  ],
  prompt_token_count=5,
  prompt_tokens_details=[
    ModalityTokenCount(
      modality=ty.TEXT: 'TEXT'>,
      token_count=5
    ),
  ],
  thoughts_token_count=1356,
  total_token_count=2769,
  traffic_type=fficType.ON_DEMAND_PRIORITY: 'ON_DEMAND_PRIORITY'>
) automatic_function_calling_history=[] parsed=None

REST

É possível verificar se o Priority PayGo foi usado em uma solicitação no campo trafficType da 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 aceleração

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

  • Modelos 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 e o sistema estiver com capacidade acima do normal devido a altas cargas de tráfego, a solicitação será rebaixada para o pagamento por uso padrão e será cobrada de acordo com as taxas do pagamento por uso padrão.

Para minimizar os downgrades, aumente o uso de forma incremental para não ultrapassar o limite. Se você ainda precisar de um desempenho melhor, considere comprar mais cota de capacidade de processamento provisionada.

É possível verificar se uma solicitação foi rebaixada na resposta. Para solicitações que passaram 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.

A seguir