Vai al contenuto principale

Tutorial API Gemini 3.8 Flash: thinking level, estrazione PDF e function calling in Python

Impara a usare l’API Gemini 3.8 Flash in Python: setup dell’Interactions API, tuning di thinking_level, estrazione PDF→JSON e function calling con codice.
Aggiornato 7 set 2026  · 15 min leggi

Esplora con l'AI

ChatGPTClaudePerplexity

Google ha rilasciato 3 modelli Flash in 6 settimane: 3.6 a fine luglio, poi 3.7 Flash il 13 agosto e ora Gemini 3.8 Flash il 2 settembre 2026. Se arrivi dalla 3.7, l’upgrade è di una riga, perché la superficie API è identica. Le configurazioni più vecchie si rompono comunque se non adegui i parametri.

Invece di rattoppare codice legacy, questo tutorial imposta un ambiente pulito da zero. Inizializzeremo un client Python sull’Interactions API, confronteremo i 3 livelli di ragionamento su un task pratico di debugging con conteggio reale dei token, estrarremo JSON pulito da uno schema da una fattura PDF e implementeremo un loop completo di function calling. Infine, vedremo la checklist di migrazione per gli sviluppatori che passano dalla 3.6 Flash o precedenti.

Per seguire, ti servono Python 3.10+ e una API key di Google AI Studio. Questa guida si concentra sull’implementazione del codice, non sugli annunci di funzionalità.

TL;DR

  • Gemini 3.8 Flash (gemini-3.8-flash) usa l’Interactions API tramite client.interactions.create() nell’SDK google-genai

  • La profondità di ragionamento si imposta con valori stringa (thinking_level: low, medium, high). 

  • Le opzioni di sampling legacy (temperature, top_p, top_k) sono deprecate 

  • Lo stato multi-turn è gestito lato server tramite previous_interaction_id

  • Prezzo introduttivo di $0,75 / $3,75 per milione di token input/output fino al 31 dicembre 2026. 

  • Se arrivi da 3.7 Flash, cambia solo la stringa del modello.

Che cos’è Gemini 3.8 Flash?

Gemini 3.8 Flash è il modello “workhorse” di Google, disponibile in GA dal 2 settembre 2026 con l’ID modello gemini-3.8-flash. È arrivato 3 settimane dopo la 3.7 Flash, e Google lo posiziona per coding a lungo raggio, workflow agentici e ragionamento multi-step in domini specialistici come finanza e area legale.

Le specifiche che contano per le chiamate API sono invariate rispetto alla 3.7: 

  • finestra di contesto da 1M token
  • 64k token massimi in output
  • input multimodale (testo, immagini, video, audio, PDF) con output testuale
  • Lo stesso prezzo introduttivo di $0,75 per 1M token in input e $3,75 per 1M token in output fino al 31 dicembre 2026 (che saliranno a $1,50 e $7,50 dal 1° gennaio 2027)

Quello che è cambiato è il comportamento, non la superficie: Google dice che la 3.8 lavora di più sui task complessi, facendo passi di ragionamento extra e chiamando gli strumenti in modo iterativo, il che può aumentare l’uso di token a livelli di sforzo più alti. 3.7 Flash resta pienamente supportata per carichi in cui l’efficienza conta più della profondità.

Per benchmark e dettagli sui prezzi, dai un’occhiata alla nostra guida a Gemini 3.8 Flash, oppure leggi la guida Cos’è Google Gemini? per una panoramica della piattaforma.

Gemini 3.8 Flash vs. 3.8 Flash Cyber

Il lancio include 2 varianti, e solo 1 di queste ha un ID modello che puoi digitare. 

  • Gemini 3.8 Flash è il modello generale, disponibile oggi in Google AI Studio e nella Gemini API. 
  • Gemini 3.8 Flash Cyber è una variante per la cybersecurity ottimizzata per scoprire vulnerabilità e applicare patch in modo automatico.

La variante Cyber non è disponibile sulla API pubblica: l’accesso passa dal Fairwind Program di Google, che è limitato ad autorità governative approvate, operatori di infrastrutture critiche e maintainer software.

Se stai seguendo questo tutorial, il tuo ID modello è gemini-3.8-flash. Niente di quanto segue richiede o usa la variante Cyber.

Interactions API vs. generateContent

Per chiamare Gemini 3.8 Flash, usa client.interactions.create() nell’SDK google-genai. Google ha portato l’Interactions API in GA a giugno 2026 e la raccomanda per tutti i nuovi lavori. Anche se generateContent funziona ancora, ora è legacy. Nuove funzionalità come cronologia lato server, esecuzione in background ed execution steps osservabili arrivano prima su Interactions.

Il cambiamento più grande in pratica è la gestione dello stato. Le chiamate multi-turn ora usano un previous_interaction_id lato server: passi l’ID dell’ultima interaction e il server gestisce il ripristino dello stato. Non devi più aggiungere o reinviare manualmente l’intera cronologia della chat dal client. Evita anche di precompilare i turni del modello; è un pattern legacy di generateContent e si romperà su Gemini 3.x.

C’è una cosa che coglie quasi tutti, e tornerà nella sezione PDF: previous_interaction_id ripristina la cronologia della conversazione e nient’altro. tools, system_instruction, generation_config e response_format hanno scope di interaction, quindi in ogni turno in cui servono vanno ripassati.

thinking_level sostituisce le manopole di sampling

Sui modelli Gemini più vecchi, gli sviluppatori usavano temperature, top_p e top_k per controllare la casualità dell’output. Gemini 3.x elimina queste manopole di sampling e le sostituisce con thinking_level, che ora è l’unica leva.

Accetta 3 valori:

  • low: meno token di ragionamento, più veloce ed economico. Adatto a estrazione, classificazione e tutto ciò che verificherai tu stesso.

  • medium: il default, e la raccomandazione di Google per codice e lavoro agentico.

  • high: il budget di ragionamento più ampio, per logiche multi-step difficili e task con uso intensivo di strumenti.

Non inviare minimal. È non valido dalla Gemini Flash 3.7 e restituisce un errore di validazione 400. 

Un’altra regola che prosegue dalla 3.7: frequency_penalty, presence_penalty e candidate_count ora generano un errore API attivo, quindi rimuovili anche dalle configurazioni legacy.

Come si configura l’API di Gemini 3.8 Flash?

Impostare l’ambiente richiede circa 2 minuti. Ti serve una API key da Google AI Studio e la libreria Python aggiornata google-genai.

Ottieni una API key da Google AI Studio

Visita Google AI Studio nel tuo browser ed effettua l’accesso con il tuo account Google. Clicca su Create API Key, seleziona o crea un progetto Google Cloud e copia la tua chiave segreta. 

Generazione di una API key per Google AI Studio

Apri il terminale e salva la chiave come variabile d’ambiente con export GEMINI_API_KEY=<your-key>.

Non passare mai la chiave come ?key= in una URL; le query string finiscono nei log del server, nella cronologia del browser e nelle cache dei proxy. Se vuoi esplorare il modello in un playground prima di scrivere codice, il Tutorial su Google AI Studio copre le modalità Chat, Build e Stream; questo articolo resta sull’API.

Per i sistemi in produzione, cambia la storia dell’autenticazione: Vertex AI (ora parte del Gemini Enterprise Agent Platform) ti offre OAuth, ruoli IAM ed endpoint regionali invece di una API key grezza. Tutto in questo tutorial usa le chiavi di AI Studio perché è il percorso più rapido per imparare, ma pianifica la migrazione a Vertex prima che qualcosa tocchi dati reali degli utenti.

Installa google-genai e crea un client

Molti tutorial dicono ancora di installare google-generativeai. Quello è l’SDK vecchio e non ha l’Interactions API. Installa google-genai (versione 2.3.0 o successiva):

pip install -U google-genai

Una volta installato, verifica che Python carichi la libreria e inizializzi il client senza errori:

from google import genai # reads GEMINI_API_KEY from the environment
client = genai.Client() 
print("Client initialized successfully.")

Esegui la tua prima chiamata all’Interactions API

Ogni richiesta all’Interactions API crea una risorsa Interaction che registra l’intero turno: il tuo input, i pensieri del modello, eventuali chiamate agli strumenti e l’output finale. L’SDK espone il testo finale tramite la proprietà di comodo output_text, quindi raramente devi attraversare i passaggi manualmente.

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=(
        "Write a pandas one-liner that adds a 7-day rolling average "
        "revenue column per store_id to a DataFrame with columns "
        "date, store_id, revenue. Reply with only the code, no explanation."
    ),
    generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
usage = interaction.usage
print(
    f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
    f"thinking={usage.total_thought_tokens} | total={usage.total_tokens}"
)

Sulla mia macchina, il modello ha risposto con una one-liner di pandas concatenata, e questa riga di utilizzo:

Esegui la prima chiamata all’Interactions API con Gemini Flash 3.8

Questi numeri nascondono la prima vera differenza rispetto alla 3.7. Ho eseguito lo stesso task con un prompt più lungo e senza restrizioni in output, e la 3.8 ha speso 1.436 token di thinking contro 870 token di output. Con la restrizione, ne ha spesi 1.515 contro 42. Il budget di ragionamento è quasi invariato, il contrario della 3.7, dove gli stessi 2 prompt spostavano il thinking da 838 a 1.530.

In altre parole, la 3.8 decide quanto “pensare” in base al task, non a come lo formuli, in linea con l’affermazione di Google che il modello ragiona e verifica di più. Il thinking è fatturato alla tariffa dell’output, quindi nella chiamata vincolata circa il 97% dei token fatturati erano ragionamenti che non ho visto. Ecco perché esiste la sezione successiva. 

Streamea la risposta

Per interfacce chat o qualsiasi cosa che una persona osserva, attendere diversi secondi per l’intera risposta sembra lento. Passa stream=True a client.interactions.create() e stampa i chunk man mano che arrivano:

	from google import genai

	client = genai.Client()

	stream = client.interactions.create(
	   model="gemini-3.8-flash",
	   input="Explain the difference between a JOIN and a correlated subquery in SQL.",
	   generation_config={"thinking_level": "low"},
	   stream=True,
	)

	for event in stream:
	   if event.event_type == "step.delta" and event.delta.type == "text":
	       print(event.delta.text, end="", flush=True)
	print() 

Quando l’ho eseguito, il modello ha restituito una risposta lunga e ben organizzata con thinking_level: "low": un confronto concettuale, una tabella riassuntiva e 2 esempi SQL per trovare l’ordine più recente di ogni cliente, 1 con una join su derived table e 1 con una correlated subquery nella lista SELECT. Le prime parole sono apparse quasi subito, che è il punto.

Quella print() finale c’è per un motivo. Senza di essa, l’ultimo chunk termina a metà riga e zsh mostra un % fuori posto prima del prompt, perché lo stream si ferma esattamente dove si ferma il testo del modello. Inoltre, le delta portano testo solo se registri i conteggi dei token per richiesta; leggili dall’evento di completamento finale invece di sommare i chunk.

Come cambia costo e qualità con thinking_level?

thinking_level imposta quanto ragionamento fa Gemini 3.8 Flash prima di scrivere la risposta. I token di ragionamento sono fatturati alla tariffa output di $3,75 per 1M, quindi il livello che scegli controlla direttamente costo e latenza, e Google dice che la 3.8 punta proprio su questo: fa passi extra su task complessi e può spendere più token a livelli di sforzo più alti rispetto alla 3.7.

Esegui un prompt a low, medium e high

Il test è una race condition in una funzione di ri-tentativo pagamento inviata con lo stesso prompt a tutti e 3 i livelli. I bug di concorrenza puniscono la lettura superficiale, quindi se i livelli differiscono, è qui che dovrebbe emergere. Se esegui solo 1 blocco di codice di questo articolo, fallo con questo, perché i numeri argomentano meglio di qualunque prosa.

import time

from google import genai

client = genai.Client()

BUGGY_CODE = '''
import threading

payment_attempts = {}

def retry_payment(order_id, charge_fn, max_retries=3):
    """Retry a failed payment up to max_retries times."""
    if order_id not in payment_attempts:
        payment_attempts[order_id] = 0

    while payment_attempts[order_id] < max_retries:
        success = charge_fn(order_id)
        if success:
            del payment_attempts[order_id]
            return True
        payment_attempts[order_id] += 1
    return False
'''

PROMPT = (
    "Two worker threads can call retry_payment() with the same order_id "
    "at the same time. Identify the concurrency bug that can double-charge "
    "a customer, and rewrite the function to fix it.\n\n" + BUGGY_CODE
)

for level in ["low", "medium", "high"]:
    start = time.perf_counter()
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        input=PROMPT,
        generation_config={"thinking_level": level},
    )
    elapsed = time.perf_counter() - start
    usage = interaction.usage
    print(f"\n=== thinking_level: {level} | {elapsed:.1f}s ===")
    print(interaction.output_text)
    print(
        f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
        f"thinking={usage.total_thought_tokens}"
    )

Per contesto, la vulnerabilità è un check-then-act non atomico su payment_attempts[order_id]. In concorrenza, 2 thread possono passare entrambi la condizione while e chiamare entrambi charge_fn() prima che uno dei due incrementi il contatore. La correzione implica racchiudere il flusso read-check-charge-increment in un lock per-ordine, o usare una idempotency key al gateway.

Confronto dei risultati

Risultati delle mie esecuzioni:

thinking_level

Ha individuato la race?

Fix corretto?

Design del fix

Latenza

Thinking token

Token output

Costo

low

Lock per-ordine + insieme dei completati

7,8 s

0

791

$0,0031

medium

Lock per-ordine + dict di stato per-ordine

16,6 s

3.158

627

$0,0143

high

Record per-ordine (lock, tentativi, completato) con percorso di failure documentato

25,5 s

4.512

896

$0,0204

Tutti e 3 i livelli hanno trovato la doppia addebito, e tutti e 3 hanno introdotto lock per-ordine, così gli ordini non correlati vanno in parallelo. Questa seconda parte è il titolo se confronti con la 3.7: lì, low avvolgeva tutto in un lock globale tenuto durante la chiamata di rete, e i lock per-ordine comparivano solo a medium. Su 3.8, low scrive quel design migliore con 0 token di thinking, in 7,8 secondi, per meno di un terzo di centesimo.

Quindi cosa compri ora con i livelli? Profondità di audit. Questo codice ha 4 modalità di failure distinte (la doppia addebito, un KeyError su delete concorrente, una ri-addebito dopo che il percorso di successo elimina lo stato e incrementi del contatore non atomici), e high è stato l’unico livello a nominarle tutte e 4; low ha mancato il caso di ri-addebito, e medium ha mancato il contatore. 

high è stato anche l’unico a esplicitare la semantica del percorso di failure del suo fix: una volta esauriti i tentativi, le chiamate successive ricevono False invece di addebitare di nuovo.

La colonna thinking è la prova, a terminale, dell’affermazione “3.8 lavora di più” di Google. Con lo stesso prompt su 3.7, medium è passato da 2.343 token di thinking a 3.158, e high da 2.217 a 4.512, circa il doppio, e i token extra hanno acquistato un’analisi più completa piuttosto che un verdetto diverso. La latenza è aumentata di pari passo in questo run (7,8 s, 16,6 s, 25,5 s), ma i tempi a singola esecuzione su questi modelli oscillano, quindi confronta i token, non i secondi.

Scegli un default e quando alzare il livello

Questa è la mia regola pratica per i livelli di ragionamento:

  • Su 3.8, low si è guadagnato un ruolo più grande di quanto suggerisca il default medium di Google: ha prodotto un fix corretto e ben progettato con 0 token di thinking, quindi parti da lì per qualsiasi cosa che un umano legge prima che conti (triage, bozze, riepiloghi, codice che rivedrai).

  • Tieni medium dove l’output viene distribuito senza essere letto, perché il thinking extra ha portato un’analisi delle modalità di failure più completa, e una pipeline non letta è esattamente dove scatterà la modalità di failure che non hai elencato.

  • Riserva high per output dove il percorso di failure è il prodotto stesso, come flussi di pagamento, migrazioni o qualsiasi cosa che un revisore auditerebbe riga per riga. Nel mio run, è stato l’unico livello a cogliere tutti e 4 i bug e a documentare cosa succede dopo l’esaurimento dei retry.

A 6.6 volte il costo di low per high, quel trade-off suona molto diverso a $3,75 per 1M token di output ora rispetto a $7,50 dopo il 31 dicembre 2026, quindi alza livello per richiesta, non globalmente.

Una scappatoia utile da conoscere è che Google afferma che la 3.7 Flash resta pienamente supportata per carichi orientati all’efficienza. Se la diligenza extra della 3.8 costa più di quanto ti serva, restare su gemini-3.7-flash per quel workload è una scelta supportata, non un hack.

Come si estraggono dati strutturati da un PDF?

Gemini 3.8 Flash legge i PDF direttamente come input, quindi puoi inviare una fattura o un report e porre domande. Ho usato una fattura vendor di 1 pagina con numero, date, 4 righe e un totale.

Allega un PDF al prompt

Carichiamo un PDF di fattura locale usando la Files API. La Files API gestisce l’archiviazione e la cache dei file sull’infrastruttura Google:

	from google import genai
	client = genai.Client()
	print("Uploading invoice...")
	doc = client.files.upload(file="invoice_aug_2026.pdf")
	print(f"File uploaded: {doc.uri}\n")

	interaction = client.interactions.create(
	   model="gemini-3.8-flash",
	   input=[
	       {
	           "type": "text",
	           "text": "Extract the invoice number, total amount due, and due date.",
	       },
	       {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
	   ],
	)
	print(interaction.output_text)

L’output dalla mia fattura:

Leggi un PDF con Gemini 3.8 Flash

Tutti e 3 i valori sono corretti. L’upload avviene una volta e il file resta disponibile per richieste successive, cosa importante non appena fai più di 1 domanda sullo stesso documento. La risposta torna come elenco in markdown, ottimo per la lettura e poco adatto a una pipeline.

Forza il JSON con uno schema di risposta

Per ottenere JSON al posto della prosa, passa uno schema in response_format. Sull’Interactions API, è un parametro di primo livello; l’impostazione responseMimeType dentro generationConfig che vedrai in tutorial più vecchi appartiene all’endpoint legacy generateContent.

import json

from google import genai
from pydantic import BaseModel

client = genai.Client()


class Invoice(BaseModel):
    invoice_number: str
    total_due_usd: float
    due_date: str  # ISO 8601


doc = client.files.upload(file="invoice_aug_2026.pdf")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "text",
            "text": "Extract the invoice number, total amount due in USD, and due date.",
        },
        {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Invoice.model_json_schema(),
    },
)

invoice = json.loads(interaction.output_text)
print(invoice)

Questo è l’output che ho ricevuto: 

Forza il formato JSON

La tua classe Pydantic definisce i campi richiesti e i tipi di dato, mentre model_json_schema() genera lo schema JSON richiesto dalla Gemini API. Una volta processato, json.loads() converte l’output del modello in un dizionario Python standard. Da qui, i dati strutturati sono pronti per essere trasformati in una riga di DataFrame, inseriti in un database o aggiunti a un Google Sheet.

Fai una follow-up con previous_interaction_id

Per una seconda domanda sullo stesso documento, passa l’id della prima interaction come previous_interaction_id. Il server ha già il PDF e il primo scambio, quindi non invii di nuovo nessuno dei due:

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input="List each line item on the invoice with its amount.",
)

print(follow_up.output_text)

Fai una follow up al PDF

Ha restituito tutte e 4 le voci in ordine, inclusa la riga compute ripetuta, senza commentare la ripetizione. È il comportamento giusto per la domanda posta; se vuoi che segnali anomalie, chiedilo.

Per quel che vale, la 3.7 si è comportata in modo identico qui, quindi la diligenza extra della 3.8 si applica al suo stesso ragionamento, non al fare audit non richiesti.

2 cose da sapere su questa chiamata: 

  • response_format non è stato riportato, perché ha scope di interaction, quindi questo turno ha restituito prosa. 

  • E le interaction sono archiviate per default (store=True) per 55 giorni sul tier a pagamento e 1 giorno su quello gratuito; store=False rende una chiamata stateless, ma poi non puoi concatenare un previous_interaction_id.

Come aggiungi il Function Calling a Gemini 3.8 Flash?

Il function calling su Gemini 3.8 Flash è un loop: il modello chiede uno strumento, il tuo codice lo esegue, rimandi il risultato e il modello scrive la risposta finale. In questa sezione costruiamo quel loop a mano.

Se vuoi che Google esegua il loop per te con agent multi-tool hosted, leggi dopo il nostro tutorial su  “Managed Agents” nella Gemini API. E se gli agent sono la tua direzione a lungo termine, il corso Building AI Agents with Google ADK costruisce un assistente di supporto clienti completo sugli stessi primitivi.

Definisci uno strumento ed esegui il loop di interaction

Lo strumento è lookup_exchange_rate(currency, date), supportato da un piccolo dict in memoria, così l’esempio gira senza API esterne. La dichiarazione è uno schema JSON. Il modello non esegue mai la funzione; restituisce uno step di function_call chiedendo al tuo codice di:

import json

from google import genai

client = genai.Client()

# Local "data source" standing in for a real FX API
RATES = {
    ("USD", "2026-08-03"): 87.42,
    ("USD", "2026-08-10"): 87.15,
    ("EUR", "2026-08-03"): 95.08,
}


def lookup_exchange_rate(currency: str, date: str) -> dict:
    rate = RATES.get((currency.upper(), date))
    if rate is None:
        return {"error": f"No rate for {currency} on {date}"}
    return {"currency": currency.upper(), "date": date, "inr_rate": rate}


rate_tool = {
    "type": "function",
    "name": "lookup_exchange_rate",
    "description": "Look up the INR exchange rate for a currency on a date (YYYY-MM-DD).",
    "parameters": {
        "type": "object",
        "properties": {
            "currency": {"type": "string", "description": "ISO code, e.g. USD"},
            "date": {"type": "string", "description": "YYYY-MM-DD"},
        },
        "required": ["currency", "date"],
    },
}

# Turn 1: the model decides to call the tool
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What was the USD to INR exchange rate on 2026-08-03?",
    tools=[rate_tool],
)

fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(f"Model requested: {fc_step.name}({fc_step.arguments})")

# Your code executes the function locally
result = lookup_exchange_rate(**fc_step.arguments)

# Turn 2: send the result back; tools must be re-specified (interaction-scoped)
final = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": json.dumps(result)}],
        }
    ],
    tools=[rate_tool],
)

print(final.output_text)

L’output: 

Function calling Gemini 3.8 Flash

Sono successe 3 cose:  

  1. Il turno 1 ha restituito uno step di function_call con nome, argomenti strutturati e un id.

  2. Il tuo Python ha eseguito la lookup.

  3. Il turno 2 ha inviato un blocco di function_result che fa riferimento a quella chiamata. 

Il parametro tools viene passato di nuovo al turno 2 per la stessa ragione per cui response_format è stato ripassato nella sezione PDF: previous_interaction_id porta la cronologia, non la config.

Errori di function calling su Gemini 3.x

Se un loop di strumenti si rompe, quasi sempre è 1 di 2 cose. 

Primo, ogni risultato deve mappare alla sua chiamata. Sull’Interactions API, sono call_id e name sul blocco function_result; sulla legacy generateContent API, il FunctionResponse deve corrispondere all’id e al name del precedente FunctionCall. Nessuno dei due è opzionale su Gemini 3.x.

Secondo, un errore Malformed_Function_Call di solito si verifica quando il modello emette commenti prima della chiamata allo strumento. La guida per sviluppatori della 3.8 di Google dice di ripulire il testo preliminare al tool, formattare le istruzioni inline con \n\n e racchiudere le note operative in una chiamata di funzione dedicata invece che in testo grezzo. Stringi la system instruction; non fare retry alla cieca.

Cosa si rompe quando passi a Gemini 3.8 Flash?

Dipende da dove parti. 

  • Da Gemini 3.7 Flash: nulla. Cambia la stringa del modello in gemini-3.8-flash e ogni snippet in questo articolo gira invariato, dato che la superficie API è identica. 

  • Da Gemini 3.6 Flash o precedenti, la configurazione del modello richiede lo stesso audit da 15 minuti di prima.

Checklist di migrazione (dalla 3.6 Flash o precedenti)

Lavora questi punti in ordine. Gli elementi 1-3 causano 400 immediati; gli elementi 4 e 5 causano problemi di qualità silenziosi.

  1. Cambia l’ID modello in gemini-3.8-flash.

  2. Elimina i parametri di sampling deprecati: temperature, top_p e top_k sono ignorati o rifiutati su Gemini 3.x, e frequency_penalty, presence_penalty e candidate_count generano un errore API attivo. Rimuovi tutti e 6 dalle config legacy.

  3. Sostituisci thinking_budget con thinking_level: usa solo low, medium o high. Il vecchio valore minimal restituisce un errore di validazione. Inviare sia thinking_budget sia thinking_level nella stessa richiesta restituisce un 400.

  4. Rimuovi i turni precompilati del modello: eliminali da qualsiasi conversazione che costruisci e assicurati che l’ultimo turno dell’utente abbia testo non vuoto. I payload di cronologia non possono terminare con un turno del modello.

  5. Standardizza i flussi multi-turn: fai affidamento su previous_interaction_id invece del replay della cronologia lato client. Devi ripassare i tuoi tools, system_instruction e generation_config a ogni turno in cui contano.

Google pubblica la versione ufficiale nelle documentazioni dei modelli Gemini API, inclusa una via automatizzata se il tuo coding agent supporta le skill. Leggila comunque tu stesso una volta; una migrazione automatica non ti dirà perché il tuo temperature=0.2 era lì in primo luogo.

Errori che incontrerai in produzione

Ecco i 4 status code per cui vale la pena collegare handler, e cosa significano su questa API:

Status

Causa tipica

Cosa fare

400 INVALID_ARGUMENT

Campi legacy residui: temperature, thinking_budget, thinking_level: "minimal", frequency_penalty, presence_penalty, candidate_count, turni del modello precompilati

Correggi la richiesta; ritentare è inutile

403 PERMISSION_DENIED

GEMINI_API_KEY errata, mancante o ristretta, o un progetto senza accesso al modello

Esporta di nuovo la chiave; verifica che sia impostata, non ristretta per questa API e non committata su git

429

Rate limit sul tuo tier, spesso durante job di estrazione batch

Riprova con backoff esponenziale e jitter; valuta di distribuire il carico

503

Sovraccarico transitorio lato Google

Stesso backoff con jitter; allerta solo se persiste per alcuni minuti

Altre 2 cose qui:

  • Imposta timeout espliciti del client quando combini thinking_level: "high" con loop di strumenti lunghi, perché una richiesta bloccata è peggio di una fallita, e la diligenza extra della 3.8 rende più probabili, non meno, run di ragionamento lunghi. 

  • E registra interaction.id con ogni richiesta; è il tuo handle per recuperare, fare debug o eliminare le interaction archiviate in seguito.

Considerazioni finali

Tutto in questo articolo risale a 3 cambi di fondo. L’Interactions API ha cambiato la convenzione di chiamata, thinking_level ha sostituito ogni manopola di sampling che usavi per il tuning, e lo stato lato server tramite previous_interaction_id è ciò che ha reso sia il follow-up sul PDF sia il loop degli strumenti turni one-liner invece di esercizi di replay della cronologia. Gemini 3.8 Flash non ha cambiato nulla di quella superficie; ha cambiato quanto il modello lavora al suo interno, motivo per cui le misurazioni in questo articolo sono state fatte ex novo sulla 3.8 invece di essere riprese dalla 3.7.

Prima di prendere per buone le mie raccomandazioni sui livelli, punta lo script di confronto su un task del tuo backlog; il livello che vince su una race di ri-tentativi di pagamento può perdere sul tuo workload di generazione SQL. 

Quando una singola chiamata API non basta più e vuoi sistemi di AI in produzione, il nostro percorso Associate AI Engineer for Developers copre l’intero percorso, e il percorso Associate AI Engineer for Data Scientists fa lo stesso dal lato data.

FAQ

Quale pacchetto Python devo installare per Gemini 3.8 Flash?

Installa google-genai usando pip (pip install -U google-genai). La libreria più vecchia google-generativeai è legacy e fallisce quando passi argomenti di configurazione di Gemini 3.x.

Gemini 3.8 Flash supporta temperature, top_p o top_k?

No. I parametri di sampling sono deprecati su Gemini 3.x, e la 3.8 in più genera un errore API attivo per frequency_penalty, presence_penalty e candidate_count. Controlli il comportamento dell’output con thinking_level.

Quali valori di thinking_level accetta Gemini 3.8 Flash?

Accetta low, medium (default) e high. Il valore minimal è non valido e restituisce un errore di validazione API.

Come fattura Google i token di ragionamento su Gemini 3.8 Flash?

Google conta i token di ragionamento come token standard di output a $3,75 per 1M token durante il periodo promozionale, che termina il 31 dicembre 2026. Google nota anche che la 3.8 può spendere più token di ragionamento a livelli di sforzo più alti, quindi paghi i cicli di verifica extra.

Cos’è Gemini 3.8 Flash Cyber e posso usarlo?

È una variante di cybersecurity ottimizzata per la scoperta di vulnerabilità e l’applicazione automatica di patch. Non è sulla API pubblica; l’accesso è limitato a difensori approvati tramite il Fairwind Program di Google. Gli sviluppatori generali usano gemini-3.8-flash.


Aryan Irani's photo
Author
Aryan Irani
Twitter

Scrivo e creo su internet. Google Developer Expert per Google Workspace, laureato in Informatica alla NMIMS e appassionato di automazione e di tecnologie di IA generativa.

Argomenti
Intelligenza artificiale
Large Language Models

Impara l’AI con DataCamp!

Corso

Introduction to Google Workspace with Gemini

30 min
2.2K
You learn about the key features of Gemini and how they can be used to improve productivity and efficiency in Google Workspace.
Vedi dettagliRight Arrow
Inizia Il Corso
Mostra altroRight Arrow
Correlato

blog

Tokenizzazione nel NLP: come funziona, sfide e casi d'uso

Guida al preprocessing NLP nel machine learning. Copriamo spaCy, i transformer di Hugging Face e come funziona la tokenizzazione in casi d'uso reali.
Abid Ali Awan's photo

Abid Ali Awan

10 min

blog

I 15 migliori server MCP remoti che ogni AI builder dovrebbe conoscere nel 2026

Scopri i 15 migliori server MCP remoti che stanno trasformando lo sviluppo AI nel 2026. Scopri come migliorano automazione, ragionamento, sicurezza e velocità dei workflow.
Abid Ali Awan's photo

Abid Ali Awan

15 min

blog

Che cos'è Snowflake? Guida per principianti alla piattaforma dati cloud

Esplora le basi di Snowflake, la piattaforma dati cloud. Scopri la sua architettura, le sue funzionalità e come integrarla nelle tue pipeline di dati.
Tim Lu's photo

Tim Lu

12 min

Mostra AltroMostra Altro