Inferenza flessibile

L'API Gemini Flex è un livello di inferenza che offre una riduzione dei costi del 50% rispetto alle tariffe standard, in cambio di latenza variabile e disponibilità best-effort. È progettata per carichi di lavoro tolleranti alla latenza che richiedono l'elaborazione sincrona, ma non necessitano delle prestazioni in tempo reale dell'API standard.

Come usare Flex

Per utilizzare il livello Flex, specifica service_tier come flex nella richiesta. Per impostazione predefinita, le richieste utilizzano il livello standard se questo campo viene omesso.

Python

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

try:
    interaction = client.interactions.create(
        model="gemini-3-flash-preview",
        input="Analyze this dataset for trends...",
        service_tier='flex'
    )
    print(interaction.steps[-1].content[0].text)
except Exception as e:
    print(f"Flex request failed: {e}")

JavaScript

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

async function main() {
    try {
        const interaction = await client.interactions.create({
            model: 'gemini-3-flash-preview',
            input: 'Analyze this dataset for trends...',
            service_tier: 'flex'
        });
        console.log(interaction.steps.at(-1).content[0].text);
    } catch (e) {
        console.log(`Flex request failed: ${e}`);
    }
}
await main();

REST

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3-flash-preview",
      "input": "Analyze this dataset for trends...",
      "service_tier": "flex"
  }'

Come funziona l'inferenza flessibile

L'inferenza di Gemini Flex colma il divario tra l'API standard e il tempo di risposta di 24 ore dell'API Batch. Utilizza la capacità di calcolo "riducibile" non di punta per fornire una soluzione conveniente per le attività in background e i flussi di lavoro sequenziali.

Funzionalità Flex Priorità Standard Batch
Prezzi Sconto del 50% 75-100% in più rispetto a Standard Intero Sconto del 50%
Latenza Minuti (obiettivo 1-15 minuti) Basso (secondi) Da secondi a minuti Fino a 24 ore
Affidabilità Best effort (eliminabile) Elevata (non eliminabile) Alta / Medio alta Elevata (per il throughput)
Interfaccia Sincrona Sincrona Sincrona Asincrona

Vantaggi principali

  • Efficienza dei costi: risparmi sostanziali per valutazioni non di produzione, agenti in background e arricchimento dei dati.
  • Semplice: basta aggiungere un solo parametro alle richieste esistenti.
  • Workflow sincroni: ideali per le catene di API sequenziali in cui la richiesta successiva dipende dall'output di quella precedente, il che li rende più flessibili rispetto ai batch per i workflow agentici.

Casi d'uso

  • Valutazioni offline: esecuzione di test di regressione o classifiche "LLM-as-a-judge".
  • Agenti in background: attività sequenziali come aggiornamenti del CRM, creazione di profili o moderazione dei contenuti in cui sono accettabili ritardi di minuti.
  • Ricerca con limiti di budget: esperimenti accademici che richiedono un volume elevato di token con un budget limitato.

Limiti di frequenza

Il traffico di inferenza flessibile viene conteggiato ai fini dei limiti di frequenza generali; non offre limiti di frequenza estesi come l'API Batch.

Capacità riducibile

Il traffico flessibile viene trattato con priorità inferiore. Se si verifica un picco di traffico standard, le richieste flessibili potrebbero essere interrotte o rimosse per garantire la capacità per gli utenti ad alta priorità. Se stai cercando un'inferenza ad alta priorità, consulta Inferenza prioritaria

Codici di errore

Quando la capacità flessibile non è disponibile o il sistema è sovraccarico, l'API restituisce codici di errore standard:

  • 503 - Servizio non disponibile: il sistema è attualmente al massimo della capacità.
  • 429 Too Many Requests: limiti di frequenza o esaurimento delle risorse.

Responsabilità del cliente

  • Nessun fallback lato server: per evitare addebiti imprevisti, il sistema non esegue automaticamente l'upgrade di una richiesta Flex al livello Standard se la capacità Flex è piena.
  • Nuovi tentativi: devi implementare la tua logica di nuovi tentativi lato client con backoff esponenziale.
  • Timeout: poiché le richieste Flex potrebbero rimanere in una coda, ti consigliamo di aumentare i timeout lato client a 10 minuti o più per evitare la chiusura prematura della connessione.

Regolare le finestre di timeout

Puoi configurare i timeout per richiesta per l'API REST e le librerie client. Assicurati sempre che il timeout lato client copra la finestra di attesa del server prevista (ad es. 600 secondi o più per le code di attesa flessibili). Gli SDK prevedono valori di timeout in millisecondi.

Timeout per richiesta

Python

from google import genai

client = genai.Client(http_options={"timeout": 900000})

try:
    interaction = client.interactions.create(
        model="gemini-3-flash-preview",
        input="why is the sky blue?",
        service_tier="flex",
    )
except Exception as e:
    print(f"Flex request failed: {e}")

JavaScript

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

async function main() {
    try {
        const interaction = await client.interactions.create({
            model: "gemini-3-flash-preview",
            input: "why is the sky blue?",
            service_tier: "flex",
        }, {timeout: 900000});
    } catch (e) {
        console.log(`Flex request failed: ${e}`);
    }
}

await main();

Implementare i nuovi tentativi

Poiché Flex è eliminabile e non funziona con errori 503, ecco un esempio di implementazione facoltativa della logica di ripetizione per continuare con le richieste non riuscite:

Python

import time
from google import genai

client = genai.Client()

def call_with_retry(max_retries=3, base_delay=5):
    for attempt in range(max_retries):
        try:
            return client.interactions.create(
                model="gemini-3-flash-preview",
                input="Analyze this batch statement.",
                service_tier="flex",
            )
        except Exception as e:
            if attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt) # Exponential Backoff
                print(f"Flex busy, retrying in {delay}s...")
                time.sleep(delay)
            else:
                # Fallback to standard on last strike (Optional)
                print("Flex exhausted, falling back to Standard...")
                return client.interactions.create(
                    model="gemini-3-flash-preview",
                    input="Analyze this batch statement."
                )

# Usage
interaction = call_with_retry()
print(interaction.steps[-1].content[0].text)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function callWithRetry(maxRetries = 3, baseDelay = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      console.log(`Attempt ${attempt + 1}: Calling Flex tier...`);
      const interaction = await ai.interactions.create({
        model: "gemini-3-flash-preview",
        input: "Analyze this batch statement.",
        service_tier: 'flex',
      });
      return interaction;
    } catch (e) {
      if (attempt < maxRetries - 1) {
        const delay = baseDelay * (2 ** attempt);
        console.log(`Flex busy, retrying in ${delay}s...`);
        await sleep(delay * 1000);
      } else {
        console.log("Flex exhausted, falling back to Standard...");
        return await ai.interactions.create({
          model: "gemini-3-flash-preview",
          input: "Analyze this batch statement.",
        });
      }
    }
  }
}

async function main() {
    const interaction = await callWithRetry();
    console.log(interaction.steps.at(-1).content[0].text);
}

await main();

Prezzi

L'inferenza flessibile ha un prezzo pari al 50% dell'API standard e viene fatturata per token.

Modelli supportati

I seguenti modelli supportano l'inferenza flessibile:

Modello Inferenza flessibile
Gemini 3.1 Flash-Lite ✔️
Gemini 3.1 Flash-Lite (anteprima) ✔️
Anteprima di Gemini 3.1 Pro ✔️
Gemini 3 Flash (anteprima) ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

Passaggi successivi