Le API di Google Gemini sono uno dei modi piu' accessibili per aggiungere intelligenza artificiale a un programma: c'e' un piano gratuito generoso, un SDK Python moderno e la possibilita' di lavorare non solo con il testo ma anche con immagini, PDF e audio. In questa guida partiamo da zero — dalla chiave API — e arriviamo a script funzionanti per chat, streaming, analisi di immagini e output strutturato in JSON, il formato che serve quando l'IA deve dialogare con altro software.

A chi serve e cosa otterrai

La guida e' pensata per chi sa muovere i primi passi in Python e vuole integrare Gemini in uno script, un'automazione o un piccolo prodotto. Al termine avrai: una chiave API attiva, l'ambiente configurato, e cinque script pronti da adattare — dalla domanda singola all'estrazione di dati strutturati. Non serve una scheda grafica: tutto il calcolo avviene sui server di Google.

Prerequisiti

  • Python 3.9 o superiore installato (verifica con python --version).
  • Un account Google.
  • Un editor di testo o un ambiente come VS Code.

Passo 1 — Ottenere la chiave API gratis da AI Studio

La chiave si ottiene da Google AI Studio, gratuitamente:

  1. Vai su aistudio.google.com e accedi con il tuo account Google.
  2. Cerca la voce Get API key (Ottieni chiave API), di solito nel menu laterale o in alto.
  3. Clicca su Create API key e copia la stringa che viene generata.
  4. Conservala in un posto sicuro: e' come una password, non condividerla e non inserirla mai nel codice pubblico.

Il piano gratuito permette di sperimentare con limiti di richieste al minuto e al giorno; per usi intensivi o in produzione si passa al piano a pagamento, i cui costi sono indicati nella pagina prezzi ufficiale e variano a seconda del modello (le versioni "Flash" costano molto meno delle "Pro").

Passo 2 — Installare l'SDK e configurare la chiave

Installa la libreria ufficiale google-genai. Conviene lavorare in un ambiente virtuale.

python -m venv venv
# su macOS/Linux:
source venv/bin/activate
# su Windows:
venv\Scripts\activate

pip install google-genai

Non scrivere mai la chiave dentro il codice. Impostala come variabile d'ambiente, che l'SDK legge in automatico:

# macOS/Linux
export GEMINI_API_KEY="la-tua-chiave"

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

Passo 3 — Il primo script: una domanda, una risposta

from google import genai

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

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 nome_file.py: dopo pochi istanti vedrai stampata la spiegazione. Il modello gemini-2.5-flash e' veloce ed economico, ideale per la maggior parte dei compiti; per ragionamenti complessi si usano le varianti "Pro".

Con poche righe di Python si ottiene la prima risposta dal modello.

Passo 4 — Streaming: la risposta parola per parola

Per un'esperienza in stile chat, con il testo che compare mentre viene generato, usa lo streaming:

from google import genai

client = genai.Client()

stream = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents="Scrivi una breve storia sull'IA in un piccolo paese italiano."
)

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

Passo 5 — Analizzare un'immagine

Gemini e' multimodale: puo' "guardare" un'immagine e descriverla o rispondere a domande su di essa. E' utile, ad esempio, per estrarre testo da una foto o classificare contenuti.

from google import genai

client = genai.Client()

immagine = client.files.upload(file="foto.jpg")

risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=["Descrivi cosa vedi in questa immagine e leggi eventuale testo.", immagine]
)

print(risposta.text)

Passo 6 — Dare un'istruzione di sistema al modello

Per definire il "carattere" e le regole di comportamento del modello si usa l'istruzione di sistema, che vale per tutta la conversazione. E' il modo giusto per fissare tono, lingua e vincoli senza ripeterli a ogni richiesta.

from google import genai
from google.genai import types

client = genai.Client()

risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Come funziona una rete neurale?",
    config=types.GenerateContentConfig(
        system_instruction=(
            "Sei un divulgatore scientifico. Rispondi sempre in italiano, "
            "con frasi brevi e almeno un esempio concreto. Evita il gergo tecnico."
        )
    ),
)

print(risposta.text)

Passo 7 — Una chat con memoria del contesto

Gli esempi visti finora sono richieste singole: il modello non ricorda nulla del messaggio precedente. Per costruire un assistente conversazionale serve una sessione di chat, che mantiene la cronologia in automatico.

from google import genai

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

r1 = chat.send_message("Mi chiamo Marco e studio biologia.")
print(r1.text)

r2 = chat.send_message("Consigliami tre argomenti di tesi adatti a me.")
print(r2.text)   # ricorda che ti chiami Marco e studi biologia

La sessione chat conserva i turni precedenti, cosi' il secondo messaggio tiene conto del primo. E' la base di qualsiasi chatbot: da qui puoi costruire un ciclo che legge l'input dell'utente da tastiera e stampa la risposta, ottenendo un assistente da terminale in poche righe.

Un mini-progetto: assistente da riga di comando

Mettiamo insieme i pezzi in un piccolo programma completo, che dialoga con l'utente finche' non scrive "esci":

from google import genai
from google.genai import types

client = genai.Client()
chat = client.chats.create(
    model="gemini-2.5-flash",
    config=types.GenerateContentConfig(
        system_instruction="Sei un assistente utile e conciso. Rispondi in italiano."
    ),
)

print("Assistente pronto. Scrivi 'esci' per terminare.")
while True:
    domanda = input("Tu: ")
    if domanda.strip().lower() == "esci":
        break
    risposta = chat.send_message(domanda)
    print("IA:", risposta.text)

Salvalo, eseguilo con python assistente.py e avrai un assistente conversazionale funzionante nel terminale, con memoria del contesto e comportamento definito dall'istruzione di sistema. E' lo scheletro su cui costruire strumenti piu' complessi.

Passo 8 — Output strutturato in JSON

Quando l'IA deve alimentare un altro programma, serve una risposta prevedibile, non un testo libero. Gemini permette di forzare l'output in JSON secondo uno schema. Esempio: estrarre dati da una recensione.

from google import genai
from pydantic import BaseModel

class Recensione(BaseModel):
    prodotto: str
    voto: int
    positiva: bool

client = genai.Client()

risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Le cuffie XZ suonano benissimo, le consiglio. Voto 5 su 5.",
    config={
        "response_mime_type": "application/json",
        "response_schema": Recensione,
    },
)

print(risposta.text)  # JSON valido conforme allo schema

Il risultato sara' un JSON come {"prodotto": "cuffie XZ", "voto": 5, "positiva": true}, pronto per essere salvato in un database o usato in un'altra parte del programma.

Passo 9 — Far chiamare al modello i tuoi strumenti (function calling)

Una delle capacita' piu' potenti e' il function calling: il modello, invece di rispondere solo a parole, puo' decidere di richiamare una funzione che scrivi tu, per esempio per leggere dati aggiornati o eseguire un calcolo. Tu definisci la funzione, l'SDK la espone al modello e Gemini, quando serve, la invoca passando i parametri giusti.

from google import genai

def prezzo_spedizione(peso_kg: float) -> str:
    "Calcola il costo di spedizione dato il peso in kg."
    costo = 5 + peso_kg * 1.2
    return f"{costo:.2f} euro"

client = genai.Client()

risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Quanto costa spedire un pacco da 3 kg?",
    config={"tools": [prezzo_spedizione]},
)

print(risposta.text)  # il modello usa la funzione e risponde 8.60 euro

Con questo meccanismo l'assistente smette di essere isolato e puo' agire sui tuoi dati e sistemi reali: e' la base per costruire veri agenti, capaci di consultare un database, interrogare un'API meteo o gestire un ordine.

Consigli per prompt efficaci

  • Sii specifico su formato, lunghezza e lingua della risposta: "in italiano, massimo 100 parole, in elenco puntato".
  • Fornisci un esempio del risultato atteso quando la struttura e' importante: il modello lo imita.
  • Per compiti complessi, chiedi di ragionare per passi prima di dare la risposta finale.
  • Usa l'istruzione di sistema per le regole fisse e il messaggio utente per la richiesta specifica.

Prompt di prova da riutilizzare

Agisci come revisore. Correggi grammatica e refusi del testo seguente, poi elenca in tre punti le modifiche principali che hai fatto.
Estrai da questo testo tutte le date, gli importi e i nomi di persona e restituiscili in JSON con tre liste separate.

Errori comuni e soluzioni

  • "API key not valid": la variabile d'ambiente non e' impostata o la chiave e' errata. Verifica con echo $GEMINI_API_KEY (o echo %GEMINI_API_KEY% su Windows) e riapri il terminale dopo averla impostata.
  • "429 Resource exhausted": hai superato i limiti del piano gratuito. Attendi, riduci le chiamate o passa al piano a pagamento.
  • "ModuleNotFoundError: google": l'ambiente virtuale non e' attivo o il pacchetto non e' installato. Riattiva venv e rilancia pip install google-genai.
  • Modello non trovato: il nome del modello puo' cambiare nel tempo. Controlla i nomi aggiornati nella documentazione ufficiale.

Gemini o gli altri? Quando conviene

Gemini brilla per il piano gratuito, la multimodalita' nativa e l'integrazione con l'ecosistema Google. Se lavori gia' con Anthropic o OpenAI, l'approccio e' molto simile e le competenze sono trasferibili: cambiano soprattutto i nomi dei modelli e qualche dettaglio dell'SDK. Per compiti che richiedono la massima capacita' di ragionamento potresti confrontare i risultati con Claude o GPT; per volumi elevati a basso costo, i modelli "Flash" di Gemini e i modelli aperti eseguibili in locale con Ollama restano opzioni molto competitive. La scelta migliore, come sempre, dipende dal caso d'uso: parti dal piano gratuito, misura la qualita' sulle tue richieste reali e scala solo quando serve.