Google Gemini è la famiglia di modelli generativi di Google, accessibile con poche righe di Python tramite l'SDK ufficiale google-genai. Questa guida ti porta dalla creazione della chiave API al primo programma funzionante, fino a tre casi che userai davvero: lo streaming della risposta, l'analisi di un'immagine e l'output JSON strutturato. Ogni esempio è testabile passo passo: se hai Python installato, alla fine avrai codice che gira sul tuo computer.

A chi serve questa guida e cosa ti serve prima di iniziare

Il tutorial è pensato per chi conosce le basi di Python (funzioni, cicli, gestione di file) e vuole integrare un modello linguistico in uno script, un backend o un piccolo prototipo. Non servono conoscenze di machine learning: Gemini si usa come un servizio remoto a cui invii testo o immagini e da cui ricevi testo. I prerequisiti reali sono pochi:

  • Python 3.9 o successivo installato (verifica con python --version). Il sistema operativo è indifferente: Windows, macOS e Linux vanno bene.
  • Un account Google qualsiasi (lo stesso di Gmail).
  • Una chiave API gratuita ottenuta da Google AI Studio, che creeremo nel primo passo.
  • Una connessione a Internet: i modelli girano sui server di Google, non sul tuo computer.

Al termine saprai fare una richiesta testuale, ricevere la risposta in streaming, far analizzare un'immagine al modello e ottenere dati in formato JSON pronti da usare nel tuo programma.

Quali modelli Gemini usare: Flash, Pro e Flash-Lite

Google pubblica più modelli, e la scelta influisce su velocità, qualità e costo. I nomi esatti cambiano nel tempo: puoi sempre elencare quelli disponibili sulla tua chiave con for m in client.models.list(): print(m.name). Al momento della scrittura, i modelli di riferimento della serie 2.5 sono questi.

ModelloPunti di forzaQuando usarlo
gemini-2.5-flashOttimo rapporto qualità/prezzo, bassa latenzaPrima scelta per quasi tutto: chatbot, riassunti, estrazione dati
gemini-2.5-proRagionamento profondo, compiti complessiAnalisi articolate, codice difficile, ragionamento a più passi
gemini-2.5-flash-liteIl più veloce ed economicoClassificazione, task semplici ad alto volume

Quando usare Gemini Flash e quando Pro

La regola pratica: parti sempre da Flash. È sorprendentemente capace, costa poco e risponde in fretta, quindi copre la stragrande maggioranza dei casi (assistenti, generazione di testo, estrazione di informazioni, chiamate a funzioni). Passa a Pro solo quando noti che Flash sbaglia su compiti che richiedono ragionamento articolato: dimostrazioni logiche, refactoring complesso, analisi di documenti lunghi con molti vincoli. Per task banali e ripetuti su grandi volumi (etichettare migliaia di frasi), Flash-Lite abbatte ulteriormente costo e latenza.

Costi e limiti del piano gratuito

Il grande vantaggio per iniziare è il piano gratuito di Google AI Studio: puoi usare i modelli Gemini senza inserire una carta di credito, entro limiti di richieste al minuto e al giorno che variano per modello. Sono più che sufficienti per imparare e prototipare. I valori esatti dei limiti cambiano nel tempo: controllali nella pagina ufficiale sui limiti d'uso. Quando passi al piano a pagamento, il prezzo è a consumo per milione di token; a titolo indicativo, gemini-2.5-flash parte da circa 0,30 $ per milione di token in input e 2,50 $ in output, mentre gemini-2.5-pro costa di più (indicativamente 1,25 $ in input e 10 $ in output per milione di token sotto i 200k di contesto). Verifica sempre le cifre aggiornate nella pagina dei prezzi, perché possono cambiare.

Gemini a confronto con OpenAI e Claude

Rispetto a OpenAI (GPT) e Anthropic (Claude), Gemini si distingue per tre aspetti: un piano gratuito generoso ideale per iniziare, una finestra di contesto molto ampia (utile per documenti lunghi) e la multimodalità nativa su testo, immagini, audio e video con la stessa API. In pratica: se vuoi partire senza costi e lavorare con contenuti multimediali, Gemini è spesso la porta d'ingresso più comoda. OpenAI e Claude restano ottime alternative con ecosistemi maturi; ne parliamo alla fine.

Ottenere la chiave API in Google AI Studio

Segui questi passi:

  1. Apri Google AI Studio ed effettua l'accesso con il tuo account Google.
  2. Nel menu, cerca la voce Get API key (Ottieni chiave API), di solito in alto o nella barra laterale.
  3. Clicca su Create API key (Crea chiave API). Ti verrà chiesto di associarla a un progetto Google Cloud: puoi lasciare che ne crei uno automaticamente.
  4. Copia la chiave generata (una stringa che inizia con AIza...) e conservala in un posto sicuro. Trattala come una password: non inserirla nel codice condiviso, non pubblicarla su GitHub.
Suggerimento: se sospetti che una chiave sia stata esposta, torna in AI Studio ed eliminala; puoi generarne una nuova in qualsiasi momento.

Installare l'SDK e impostare la chiave

L'SDK ufficiale e attuale è il pacchetto google-genai (il vecchio google-generativeai è deprecato: non usarlo per progetti nuovi). Installalo con pip:

pip install google-genai

Ora imposta la chiave come variabile d'ambiente, così non finisce nel codice. L'SDK legge automaticamente GEMINI_API_KEY (o in alternativa GOOGLE_API_KEY).

# macOS / Linux (shell corrente)
export GEMINI_API_KEY="la-tua-chiave-AIza..."

# Windows (PowerShell)
setx GEMINI_API_KEY "la-tua-chiave-AIza..."

Su Windows chiudi e riapri il terminale dopo setx. Per verificare che sia impostata: echo $GEMINI_API_KEY (macOS/Linux) o echo %GEMINI_API_KEY% (Windows cmd).

Il primo programma in Python

Creiamo gemini_hello.py. Il client, se non gli passi esplicitamente la chiave, la prende dalla variabile d'ambiente che hai appena impostato.

from google import genai

# Legge automaticamente GEMINI_API_KEY dall'ambiente
client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Spiega in due frasi cos'è un'API, come se parlassi a un principiante.",
)

print(response.text)

Eseguilo con python gemini_hello.py. L'output atteso è simile a questo (il testo esatto varia a ogni esecuzione):

Un'API è un insieme di regole che permette a due programmi di
comunicare tra loro, un po' come un cameriere che porta la tua
ordinazione dalla cucina al tavolo. Tu chiedi qualcosa in un
formato concordato e ricevi indietro una risposta prevedibile.

Se vedi questo output, tutto funziona: hai appena chiamato Gemini dal tuo computer. Se preferisci passare la chiave nel codice (sconsigliato in produzione) puoi scrivere genai.Client(api_key="AIza...").

Con l'SDK google-genai bastano poche righe di Python per la prima chiamata a Gemini. Foto: ThisIsEngineering / Pexels.

Streaming: risposte parola per parola

Per risposte lunghe, aspettare il testo completo dà una sensazione di lentezza. Con lo streaming ricevi il testo a pezzi (chunk) man mano che il modello lo genera, esattamente come nell'interfaccia di ChatGPT o Gemini. Il metodo è generate_content_stream.

from google import genai

client = genai.Client()

stream = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents="Racconta una breve storia (circa 150 parole) su un robot che impara a cucinare.",
)

for chunk in stream:
    print(chunk.text, end="", flush=True)
print()

Eseguendolo vedrai il testo comparire progressivamente nel terminale invece che tutto insieme. È la scelta giusta per chatbot e interfacce dove la reattività percepita conta. Ogni chunk contiene un pezzo di testo in chunk.text; concatenandoli ottieni la risposta completa.

Analizzare un'immagine con Gemini

Gemini è multimodale: puoi inviare un'immagine insieme a una domanda testuale. Ti serve un file immagine locale (per esempio foto.jpg). Si usa types.Part.from_bytes per allegare i byte dell'immagine indicando il mime_type.

from google import genai
from google.genai import types

client = genai.Client()

with open("foto.jpg", "rb") as f:
    image_bytes = f.read()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        "Descrivi questa immagine e dimmi che oggetti contiene.",
        types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
    ],
)

print(response.text)

Il parametro contents accetta una lista: puoi mischiare testo e parti multimediali nell'ordine che preferisci. Per un PNG usa mime_type="image/png". Lo stesso schema funziona con PDF, audio e video: cambia il tipo MIME e, per file grandi, valuta la File API descritta nella documentazione.

Ottenere un JSON strutturato

Quando integri Gemini in un programma, spesso non vuoi testo libero ma dati strutturati da elaborare. L'SDK permette di forzare l'output in JSON impostando response_mime_type="application/json" e uno schema. Il modo più pulito è definire lo schema con Pydantic e passarlo a response_schema: il modello restituirà JSON conforme.

from google import genai
from google.genai import types
from pydantic import BaseModel

class Ricetta(BaseModel):
    nome: str
    tempo_minuti: int
    ingredienti: list[str]

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Dammi una ricetta veloce per una carbonara.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=Ricetta,
    ),
)

print(response.text)          # stringa JSON
ricetta = response.parsed     # oggetto Ricetta già validato
print(ricetta.nome, ricetta.tempo_minuti)

L'output atteso è un JSON valido, per esempio:

{"nome": "Spaghetti alla carbonara", "tempo_minuti": 20,
 "ingredienti": ["spaghetti", "guanciale", "uova", "pecorino", "pepe"]}

Il campo response.parsed ti restituisce direttamente un oggetto Python già validato secondo lo schema: niente più parsing manuale né sorprese di formato. È il modo consigliato per collegare Gemini al resto del tuo codice.

Con response_schema Gemini restituisce JSON conforme, pronto da usare nel codice. Foto: RealToughCandy.com / Pexels.

Prompt pronti da copiare

Ecco alcuni prompt da incollare nel campo contents per provare subito i concetti visti.

Estrai da questo testo nome, email e azienda in formato JSON. Testo: "Buongiorno, sono Luca Bianchi di Rossi SpA, mi trovate a luca.bianchi@rossispa.it".

Risultato atteso (con output strutturato attivo): un JSON con i tre campi popolati correttamente.

Riassumi il seguente articolo in 3 punti elenco, ognuno di massimo 15 parole. Poi indica il tono complessivo (positivo, neutro, negativo).

Risultato atteso: tre bullet brevi seguiti da un'etichetta di tono.

Sei un tutor di Python. Correggi questo codice e spiega l'errore in una frase: for i in range(10) print(i)

Risultato atteso: la versione corretta con i due punti dopo range(10): e una spiegazione della sintassi mancante.

Varianti e casi avanzati

System instruction e temperature

Puoi dare al modello un ruolo fisso e controllare la creatività tramite GenerateContentConfig. La temperature va da 0 (risposte deterministiche e prevedibili) verso valori più alti (più varietà e creatività).

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Consigliami un nome per un'app di ricette.",
    config=types.GenerateContentConfig(
        system_instruction="Rispondi sempre in italiano, in tono professionale e conciso.",
        temperature=0.9,
    ),
)
print(response.text)

Function calling: collegare Gemini ai tuoi strumenti

Con il function calling il modello può decidere di chiamare una tua funzione Python (per esempio per leggere il meteo o interrogare un database). Nell'SDK basta passare la funzione tra i tools: Gemini genera la chiamata con gli argomenti, tu la esegui e restituisci il risultato. È il mattone base per costruire agenti. I dettagli e gli esempi completi sono nella documentazione ufficiale, che aggiorna la firma esatta a ogni versione.

Chiamare l'API via REST con curl

Se non usi Python, la stessa richiesta funziona via HTTP. L'endpoint REST usa l'header x-goog-api-key per la chiave:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Ciao, chi sei?"}]}]}'

Riceverai un JSON con il testo della risposta dentro candidates[0].content.parts[0].text.

Errori comuni e come risolverli

  • Chiave mancante o non trovata. Se ottieni un errore tipo "API key not found" o "Missing key", la variabile d'ambiente non è impostata nel terminale corrente. Reimpostala con export/setx e, su Windows, riapri il terminale. In alternativa passa la chiave con genai.Client(api_key="...") per un test rapido.
  • Chiave non valida (errore 400, "API key not valid"). Hai copiato la chiave in modo incompleto o è stata revocata. Rigenerala in Google AI Studio e ricopiala per intero.
  • Quota superata (errore 429, "RESOURCE_EXHAUSTED"). Hai raggiunto il limite di richieste al minuto o al giorno del piano gratuito. Soluzioni: attendi qualche istante, riduci la frequenza delle chiamate, usa un modello più leggero come gemini-2.5-flash-lite, oppure passa al piano a pagamento per limiti più alti.
  • Modello inesistente (errore 404, "model not found"). Hai scritto male il nome del modello o quel modello non è disponibile sulla tua chiave. Elenca i modelli reali con for m in client.models.list(): print(m.name) e usa un nome della lista.
  • Blocco per sicurezza. Se la risposta arriva vuota, potrebbe essere stata filtrata: controlla response.candidates[0].finish_reason e i safety_ratings per capire il motivo.

Quando scegliere OpenAI o Claude e come proseguire

Gemini è un'ottima prima scelta per iniziare grazie al piano gratuito, alla multimodalità nativa e al contesto ampio. Ma le alternative hanno i loro punti forti: OpenAI ha un ecosistema molto maturo, tantissime librerie di terze parti e strumenti come funzioni e assistenti ben rodati; Claude di Anthropic è spesso apprezzato per la scrittura di testi lunghi, il rispetto delle istruzioni e i task di programmazione. Una regola pratica: prototipa con Gemini Flash (gratis e veloce), e valuta OpenAI o Claude se un caso d'uso specifico rende migliori i loro risultati o se il tuo team è già investito in quegli ecosistemi. Nulla vieta di usarli in parallelo e scegliere il migliore per ogni compito.

Per approfondire, parti dalla documentazione ufficiale: la guida agli sviluppatori della Gemini API, la pagina dei modelli per l'elenco aggiornato e la pagina dei prezzi per costi e limiti. Da qui puoi passare a temi avanzati come la File API per file grandi, l'embedding per la ricerca semantica e la costruzione di agenti con il function calling. Buon lavoro con Gemini.