Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Flex PayGo

O pagamento por uso flexível (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 Standard PayGo.

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 sensíveis ao tempo. Confira alguns exemplos de casos de uso:

Análise off-line de arquivos de texto, documentos, imagens, áudio e vídeo
Avaliação da qualidade 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.

Limite de payload da solicitação

As solicitações do Flex PayGo têm um limite total de tamanho de payload de 20 MB. Para payloads maiores que 20 MB, forneça um URI do Cloud Storage.

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 Flex PayGo.

As solicitações que usam o Flex PayGo têm uma latência esperada maior do que o PayGo padrão.

É possível definir o tempo limite da solicitação em até 30 minutos.

Usar o Flex PayGo com o PT como padrão

Para usar qualquer cota de PT 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.

Para substituir o tempo limite padrão, use o parâmetro timeout. O tempo limite é especificado em milissegundos.

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 configurar seu ambiente, use REST para testar uma solicitação 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 Flex PayGo.
PROMPT_TEXT: as instruções de texto a serem incluídas no comando. JSON.

É possível substituir o tempo limite padrão definindo o cabeçalho X-Server-Timeout. O tempo limite é especificado em segundos.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Server-Timeout: 600" \
  -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 trecho:

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.5-flash). Este exemplo pode oferecer suporte a outros modelos de classificação.
Quando você usa um endpoint regional de API (por exemplo, us-central1), a região do URL do endpoint determina onde a solicitação é processada. Qualquer local conflitante no caminho do recurso é ignorado.

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

Para substituir o tempo limite padrão, use o parâmetro timeout. O tempo limite é especificado em milissegundos.

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.
PROMPT_TEXT: as instruções de texto a serem incluídas no comando. JSON.

É possível substituir o tempo limite padrão definindo o cabeçalho X-Server-Timeout. O tempo limite é especificado em segundos.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Server-Timeout: 600" \
  -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 trecho:

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.5-flash). Este exemplo pode oferecer suporte a outros modelos de classificação.
Quando você usa um endpoint regional de API (por exemplo, us-central1), a região do URL do endpoint determina onde a solicitação é processada. Qualquer local conflitante no caminho do recurso é ignorado.

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 o 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 o 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 PT para tráfego excedente), 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

Flex PayGo Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Quando usar o Flex PayGo

Modelos e locais compatíveis

Limite de payload da solicitação

Usar o Flex PayGo

Usar o Flex PayGo com o PT como padrão

Python

Instalar

REST

Usar apenas o Flex PayGo

Python

Instalar

REST

Verificar o uso do Flex PayGo

Python

REST

Cota extra para o Flex PayGo

Flex PayGo