Google Gemini e' oggi uno dei modelli piu' usati per chi sviluppa applicazioni IA, complice un piano gratuito generoso e un'ottima gestione di testo lungo, immagini e output strutturati. In questa guida vediamo passo passo come usarlo in Python: dalla chiave API gratuita alla prima chiamata, fino a immagini, JSON strutturato, streaming e gestione degli errori. Al termine avrai una base solida da riusare in progetti reali.

A chi serve e cosa ti serve prima di iniziare

Questa guida e' per chi conosce le basi di Python e vuole integrare Gemini nei propri script o applicazioni. Prerequisiti reali: Python 3.9 o superiore installato; un account Google; una connessione a internet. Non serve carta di credito per iniziare: il piano gratuito di Google AI Studio consente un numero di richieste al minuto e al giorno sufficiente per sviluppare e testare, con limiti che variano a seconda del modello.

Quale modello scegliere

La famiglia Gemini offre varianti diverse. Per iniziare conviene un modello Flash, veloce ed economico, adatto alla maggior parte dei compiti: chat, riassunti, classificazione, estrazione dati. I modelli Pro costano di piu' ma ragionano meglio su problemi complessi. Consiglio pratico come prima scelta: parti da un modello Flash e passa a Pro solo se ti accorgi che la qualita' non basta. Cosi' tieni bassi costi e latenza.

Passo 1: ottenere la chiave API gratuita

Vai su Google AI Studio, accedi con il tuo account Google e cerca la voce "Get API key" (Ottieni chiave API). Crea una nuova chiave e copiala. Trattala come una password: non inserirla mai direttamente nel codice che condividi o pubblichi.

Il modo corretto e' salvarla in una variabile d'ambiente. Su Linux o macOS:

export GEMINI_API_KEY="la-tua-chiave"

Su Windows (PowerShell):

setx GEMINI_API_KEY "la-tua-chiave"

Passo 2: installare l'SDK e fare la prima chiamata

Installa la libreria ufficiale:

pip install google-genai

Ora la prima chiamata. Crea un file prima_chiamata.py:

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Spiega in tre frasi semplici cos'e' un modello linguistico."
)

print(risposta.text)

Esegui con python prima_chiamata.py. Il risultato atteso e' una spiegazione di tre frasi in italiano. Se la vedi, la tua configurazione funziona.

Con poche righe e la libreria google-genai si effettua la prima chiamata a Gemini.

Passo 3: dare istruzioni di sistema e controllare la creativita'

Puoi guidare il comportamento del modello con istruzioni di sistema e parametri. Ecco un esempio che imposta un ruolo e riduce la creativita' per risposte piu' precise:

from google.genai import types

risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Elenca tre rischi dell'uso dell'IA nella pubblica amministrazione.",
    config=types.GenerateContentConfig(
        system_instruction="Sei un esperto di policy digitali. Rispondi in italiano, con elenchi puntati concisi.",
        temperature=0.2,
    ),
)
print(risposta.text)

Il parametro temperature va da 0 a 1 circa: valori bassi danno risposte piu' deterministiche e affidabili, valori alti piu' varie e creative.

Passo 4: analizzare un'immagine

Gemini e' multimodale: puo' leggere le immagini. Ecco come farsi descrivere una foto locale:

from google.genai import types

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

risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        types.Part.from_bytes(data=immagine, mime_type="image/jpeg"),
        "Descrivi cosa c'e' in questa immagine e leggi eventuali testi.",
    ],
)
print(risposta.text)

Il risultato atteso e' una descrizione testuale del contenuto della foto, inclusa la trascrizione di eventuali scritte. Utile per catalogare immagini, estrarre dati da scontrini o descrivere contenuti per l'accessibilita'.

Passo 5: ottenere output in JSON strutturato

Per integrare Gemini in un programma, spesso serve una risposta in un formato preciso, non testo libero. Puoi chiedere direttamente un JSON conforme a uno schema:

from google.genai import types

risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Estrai nome, citta' e professione da: 'Sono Giulia, faccio l'architetta a Torino'.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema={
            "type": "object",
            "properties": {
                "nome": {"type": "string"},
                "citta": {"type": "string"},
                "professione": {"type": "string"},
            },
        },
    ),
)
print(risposta.text)

La risposta attesa e' un JSON pulito del tipo {"nome": "Giulia", "citta": "Torino", "professione": "architetta"}, che puoi caricare con json.loads() e usare nel tuo codice senza doverlo ripulire.

L'output JSON strutturato rende Gemini facile da integrare in un programma.

Passo 6: streaming per risposte in tempo reale

Per interfacce di chat conviene mostrare la risposta man mano che viene generata, invece di aspettare la fine:

for pezzo in client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents="Scrivi una breve storia sulla nebbia in pianura padana.",
):
    print(pezzo.text, end="")

Passo 7: mantenere una conversazione con memoria

Per costruire una chat vera, il modello deve ricordare i messaggi precedenti. L'SDK offre un oggetto di sessione che gestisce automaticamente la cronologia, cosi' non devi ricostruirla a mano a ogni richiesta:

chat = client.chats.create(model="gemini-2.5-flash")

r1 = chat.send_message("Mi chiamo Andrea e vivo a Bologna.")
print(r1.text)

r2 = chat.send_message("In che citta' vivo?")
print(r2.text)  # Il modello ricorda: Bologna

Il risultato atteso e' che alla seconda domanda il modello risponda "Bologna", perche' mantiene il contesto della conversazione. Attenzione pero': ogni messaggio precedente viene rinviato al modello e conta nel conteggio dei token, quindi conversazioni molto lunghe costano di piu' e vanno eventualmente troncate.

Errori comuni e come risolverli

  • "API key not valid": la chiave e' errata o non caricata. Verifica la variabile d'ambiente con echo $GEMINI_API_KEY e rigenerala se necessario da AI Studio.
  • "429 Resource exhausted": hai superato i limiti del piano gratuito (richieste al minuto o al giorno). Attendi, rallenta le chiamate o passa a un piano a pagamento.
  • Blocchi di sicurezza (safety): se il contenuto viene filtrato, la risposta puo' arrivare vuota. Controlla i metadati della risposta e riformula il prompt.
  • ModuleNotFoundError: hai installato il pacchetto sbagliato. La libreria corretta e' google-genai, non le vecchie versioni deprecate.

Quando conviene Gemini e come proseguire

Gemini e' un'ottima scelta quando lavori con testi molto lunghi, immagini o hai bisogno di un piano gratuito per prototipare. Per progetti in cui usi gia' l'ecosistema OpenAI o Anthropic, valuta se la migrazione vale lo sforzo: le API sono simili nei concetti ma diverse nei dettagli. Il passo successivo naturale e' costruire qualcosa di reale: un assistente sui tuoi documenti (RAG), un classificatore di email o un agente. Per approfondire, la documentazione ufficiale di Google AI e' completa e aggiornata, con esempi per ogni funzione. Con le basi di questa guida, sei pronto a integrare Gemini nei tuoi progetti Python.