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

Flex PayGo

Flex pagamento a consumo (Flex PayGo) è un'opzione conveniente per accedere ai modelli Gemini per i workload non critici che possono tollerare tempi di risposta più lunghi e una limitazione più elevata. Flex PayGo offre uno sconto del 50% rispetto a Standard PayGo.

Quando utilizzare Flex PayGo

Flex PayGo è ideale per attività sincrone, tolleranti alla latenza e non critiche che non sono sensibili al tempo. Di seguito sono riportati alcuni casi d'uso di esempio:

Analisi offline di file di testo, documenti, immagini, audio e video
Valutazione della qualità del modello
Annotazione ed etichettatura dei dati
Traduzione di documenti
Creare un catalogo dei prodotti

Modelli e località supportati

I seguenti modelli Gemini in anteprima supportano Flex PayGo solo nell'endpoint global. Flex PayGo non supporta endpoint regionali o multiregionali.

Limite del payload della richiesta

Le richieste Flex PayGo hanno un limite di dimensioni totali del payload di 20 MB. Per i payload superiori a 20 MB, fornisci invece un URI Cloud Storage.

Utilizzare Flex PayGo

Per inviare richieste all'API Gemini utilizzando Flex PayGo, devi includere l'intestazione X-Vertex-AI-LLM-Shared-Request-Type nella richiesta. Puoi utilizzare Flex PayGo in due modi:

Utilizza la quota di throughput riservato (se disponibile) e poi utilizza Flex PayGo.
Utilizza solo Flex PayGo.

Le richieste che utilizzano Flex PayGo hanno una latenza prevista maggiore rispetto a Standard PayGo.

Puoi impostare il timeout della richiesta su un massimo di 30 minuti.

Utilizzare Flex PayGo quando PT è impostato come predefinito

Per utilizzare la quota PT disponibile prima di utilizzare Flex PayGo, includi l'intestazione X-Vertex-AI-LLM-Shared-Request-Type: flex nelle tue richieste, come mostrato negli esempi seguenti.

Python

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare SDK Google Gen AI con 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

Inizializza il client GenAI per utilizzare Flex PayGo. Dopo aver eseguito questo passaggio, non dovrai apportare ulteriori modifiche al codice per interagire con l'API Gemini utilizzando Flex PayGo sullo stesso client.

Puoi ignorare il timeout predefinito utilizzando il parametro timeout. Il timeout è specificato in millisecondi.

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

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni.

PROJECT_ID: il tuo ID progetto.
MODEL_ID: l'ID modello del modello per cui vuoi inizializzare Flex PayGo.
PROMPT_TEXT: le istruzioni di testo da includere nel prompt. JSON.

Puoi ignorare il timeout predefinito impostando l'intestazione X-Server-Timeout. Il timeout è specificato in secondi.

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" }
    }
  }'

Dovresti ricevere una risposta JSON simile alla seguente.

{
  "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
  }
}

Utilizza solo Flex PayGo

Per utilizzare solo Flex PayGo, includi le intestazioni X-Vertex-AI-LLM-Request-Type: shared e X-Vertex-AI-LLM-Shared-Request-Type: flex nelle richieste, come mostrato negli esempi seguenti.

Python

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare SDK Google Gen AI con 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

Puoi ignorare il timeout predefinito utilizzando il parametro timeout. Il timeout è specificato in millisecondi.

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

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

PROJECT_ID: il tuo ID progetto.
MODEL_ID: l'ID modello del modello per cui vuoi inizializzare Flex PayGo.
PROMPT_TEXT: le istruzioni di testo da includere nel prompt. JSON.

Puoi ignorare il timeout predefinito impostando l'intestazione X-Server-Timeout. Il timeout è specificato in secondi.

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" }
    }
  }'

Dovresti ricevere una risposta JSON simile alla seguente.

{
  "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
  }
}

Verificare l'utilizzo di Flex PayGo

Puoi verificare se una richiesta ha utilizzato Flex PayGo dal tipo di traffico nella risposta, come mostrato negli esempi seguenti.

Python

Puoi verificare se Flex PayGo è stato utilizzato per una richiesta dal campo traffic_type nella risposta. Se la tua richiesta è stata elaborata utilizzando Flex PayGo, il campo traffic_type è impostato su 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

Puoi verificare se Flex PayGo è stato utilizzato per una richiesta dal campo trafficType nella risposta. Se la tua richiesta è stata elaborata utilizzando Flex PayGo, il campo trafficType è impostato su 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
  }
}

Quota aggiuntiva per Flex PayGo

Oltre alle quote disponibili per le richieste di generazione di contenuti (inclusa la quota PT per il traffico di overflow), le richieste che utilizzano Flex PayGo sono soggette alla seguente quota:

Descrizione	QPM per ogni modello di base in un progetto
Quota per ogni modello di base in un progetto che richiede l'utilizzo di Flex PayGo	3000

Flex PayGo Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Quando utilizzare Flex PayGo

Modelli e località supportati

Limite del payload della richiesta

Utilizzare Flex PayGo

Utilizzare Flex PayGo quando PT è impostato come predefinito

Python

Installa

REST

Utilizza solo Flex PayGo

Python

Installa

REST

Verificare l'utilizzo di Flex PayGo

Python

REST

Quota aggiuntiva per Flex PayGo

Flex PayGo