Flex PayGo

O pagamento flexível por uso (Flex PayGo) é uma opção econômica para acessar modelos do Gemini em cargas de trabalho não críticas que podem tolerar tempos de resposta mais longos e limitação mais alta. O Flex PayGo oferece um desconto de 50% em comparação com o PayGo Standard.

Quando usar o Flex PayGo

O Flex PayGo é ideal para tarefas síncronas, tolerantes à latência e não críticas que não são urgentes. Confira alguns exemplos de casos de uso:

  • Análise off-line de arquivos de texto, documentos, imagens, áudio e vídeo

  • Avaliação das qualidades do modelo

  • Anotação e rotulagem de dados

  • Tradução de documentos

  • Como criar um catálogo de produtos

Modelos e locais compatíveis

Os seguintes modelos do Gemini em prévia são compatíveis com o Flex PayGo apenas no endpoint global. O Flex PayGo não é compatível com endpoints regionais ou multirregionais.

Usar o Flex PayGo

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

  • Use a cota de capacidade de processamento provisionada (se disponível) e depois o Flex PayGo.

  • Use somente o PayGo flexível.

As solicitações que usam o Flex PayGo têm latência maior do que o Standard PayGo. O tempo limite padrão é de 20 minutos, que pode ser substituído (em milissegundos) usando o parâmetro timeout. O valor máximo permitido é de 30 minutos.

Usar o Flex 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 Flex PayGo, inclua o cabeçalho X-Vertex-AI-LLM-Shared-Request-Type: flex 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 Flex 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 Flex 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": "flex"
      },
    # timeout = 600000  # Timeout in milliseconds
  )
)

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 Flex PayGo. Para uma lista de modelos que oferecem suporte ao Flex PayGo, consulte Versões do 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-Server-Timeout: 600" \  # Timeout in milliseconds
  -H "X-Vertex-AI-LLM-Shared-Request-Type: flex" \
  "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_FLEX",
    "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 apenas o Flex PayGo

Para usar apenas o Flex PayGo, inclua os cabeçalhos X-Vertex-AI-LLM-Request-Type: shared e X-Vertex-AI-LLM-Shared-Request-Type: flex 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 Flex 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 Flex 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": "flex"
      },
    # timeout = 600000  # Timeout in milliseconds
  )
)

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 Flex PayGo. Para uma lista de modelos que oferecem suporte ao Flex PayGo, consulte Versões do 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-Server-Timeout: 600" \  # Timeout in milliseconds
  -H "X-Vertex-AI-LLM-Request-Type: shared" \
  -H "X-Vertex-AI-LLM-Shared-Request-Type: flex" \
  "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_FLEX",
    "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 Flex PayGo

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

Python

É possível verificar se o Flex PayGo foi usado em uma solicitação do campo traffic_type na resposta. Se a solicitação foi processada usando Flex PayGo, o campo traffic_type será definido como ON_DEMAND_FLEX.

sdk_http_response=HttpResponse(
  headers=
) 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_FLEX: 'ON_DEMAND_FLEX'>
) automatic_function_calling_history=[] parsed=None

REST

É possível verificar se o Flex PayGo foi usado em uma solicitação do campo trafficType na resposta. Se a solicitação foi processada usando Flex PayGo, o campo trafficType será definido como ON_DEMAND_FLEX.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Response to sample request."
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 900,
    "totalTokenCount": 1957,
    "trafficType": "ON_DEMAND_FLEX",
    "thoughtsTokenCount": 1054
  }
}

Cota extra para o Flex PayGo

Além das cotas disponíveis para solicitações de geração de conteúdo (incluindo a cota de capacidade de processamento provisionada para tráfego de transbordamento), as solicitações que usam o Flex PayGo estão sujeitas à seguinte cota:

Descrição QPM para cada modelo de base em um projeto
Cota para cada modelo de base em um projeto que usa o Flex PayGo 3000

A seguir