Inferenza Flex

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 i carichi di lavoro con tolleranza alla latenza che richiedono l'elaborazione sincrona, ma non le prestazioni in tempo reale dell'API standard.

Come utilizzare 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

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

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...',
            serviceTier: 'flex'
        });
        console.log(interaction.steps.at(-1).content[0].text);
    } catch (e) {
        console.log(`Flex request failed: ${e}`);
    }
}
await main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "model": "gemini-3-flash-preview",
      "input": "Analyze this dataset for trends...",
      "service_tier": "flex"
  }'

Come funziona l'inferenza Flex

L'inferenza 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 "sheddable" fuori orario 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 allo standard Intero Sconto del 50%
Latenza Minuti (target 1-15 min) Bassa (secondi) Da secondi a minuti Fino a 24 ore
Affidabilità Best effort (sheddable) Elevata (non sheddable) Elevata / medio-alta Elevata (per il throughput)
Interfaccia Sincrona Sincrona Sincrona Asincrona

Vantaggi principali

  • Efficienza dei costi: risparmi significativi per le valutazioni non di produzione, gli agenti in background e l'arricchimento dei dati.
  • Basso attrito: basta aggiungere un singolo parametro alle richieste esistenti.
  • Flussi di lavoro sincroni: ideale per le catene di API sequenziali in cui la richiesta successiva dipende dall'output della precedente, il che la rende più flessibile rispetto a Batch per i flussi di lavoro agentici.

Casi d'uso

  • Valutazioni offline: esecuzione di test di regressione o classifiche "LLM-as-a-judge".
  • Agenti in background: attività sequenziali come aggiornamenti CRM, creazione di profili o moderazione dei contenuti in cui sono accettabili minuti di ritardo.
  • 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 Flex viene conteggiato ai fini dei limiti di frequenza generali; non offre limiti di frequenza estesi come l'API Batch.

Capacità sheddable

Il traffico Flex viene trattato con una priorità inferiore. Se si verifica un picco di traffico standard, le richieste Flex potrebbero essere interrotte o eliminate per garantire la capacità per gli utenti con priorità elevata. Se stai cercando un'inferenza con priorità elevata, consulta la sezione Inferenza con priorità

Codici di errore

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

  • 503 Service Unavailable: 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 Flex). Gli SDK prevedono valori di timeout in millisecondi.

Timeout per richiesta

Python

from google import genai

client = genai.Client()

try:
    interaction = client.interactions.create(
        model="gemini-3-flash-preview",
        input="why is the sky blue?",
        service_tier="flex",
        http_options={"timeout": 900000}
    )
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?",
            serviceTier: "flex",
            httpOptions: {timeout: 900000}
        });
    } catch (e) {
        console.log(`Flex request failed: ${e}`);
    }
}

await main();

Implementare i nuovi tentativi

Poiché Flex è sheddable e non riesce a eseguire le richieste con errori 503, ecco un esempio di implementazione facoltativa della logica di nuovi tentativi 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.",
        serviceTier: '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 Flex ha un prezzo pari al 50% dell'API standard e viene fatturata per token.

Modelli supportati

I seguenti modelli supportano l'inferenza Flex:

Modello Inferenza Flex
Gemini 3.1 Flash-Lite ✔️
Gemini 3.1 Flash-Lite (anteprima) ✔️
Gemini 3.1 Pro (anteprima) ✔️
Gemini 3 Flash (anteprima) ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

Passaggi successivi