Le API di Google Gemini sono uno dei modi piu' economici per aggiungere intelligenza artificiale a un programma: c'e' un piano gratuito generoso per sperimentare, i modelli sono multimodali (testo, immagini, audio, video) e l'SDK Python ufficiale e' diventato semplice e coerente. In questa guida partiamo da zero: dalla chiave gratuita al primo programma, fino a chat, analisi di immagini e output strutturato in JSON. Tutto il codice e' pronto da copiare.

A chi serve e cosa otterrai

E' una guida per chi sa muovere i primi passi in Python (sai eseguire uno script e installare un pacchetto) e vuole costruire qualcosa con un modello di linguaggio: uno script che riassume documenti, un piccolo assistente, un classificatore di email, un estrattore di dati. Al termine saprai chiamare Gemini per testo, ricevere risposte in streaming, gestire una conversazione, analizzare immagini e ottenere JSON valido da usare nel tuo codice.

Prerequisiti reali:

  • Python 3.9 o superiore installato.
  • Un account Google (basta quello personale).
  • Connessione a Internet. Nessuna GPU: il calcolo avviene sui server di Google.

Quale modello e quanto costa: free tier e a pagamento

Gemini si usa in due modi: tramite Google AI Studio (semplice, con chiave personale e un piano gratuito) o tramite Vertex AI (la versione enterprise su Google Cloud, con fatturazione e controlli avanzati). Per imparare e per i progetti personali, AI Studio e' la scelta giusta.

I modelli principali oggi disponibili via API:

ModelloQuando usarlo
gemini-3.5-flashVeloce ed economico, ottimo per la maggior parte dei compiti: riassunti, classificazione, chat, estrazione dati. La prima scelta.
gemini-3.5-proRagionamenti complessi, contesto molto lungo, compiti difficili. Piu' lento e costoso.
gemini-2.0-flashGenerazione precedente, ancora valida e a basso costo.

Il piano gratuito di AI Studio permette di provare i modelli con limiti di richieste al minuto e al giorno: piu' che sufficienti per sviluppare e testare. Quando passi in produzione, attivi la fatturazione e paghi a consumo (un prezzo per milione di token in ingresso e uno in uscita), con Flash sensibilmente piu' economico di Pro.

Rispetto ai concorrenti: l'API di OpenAI (GPT) e quella di Anthropic (Claude) sono altrettanto solide, ma Gemini si distingue per il free tier piu' accessibile, il contesto molto ampio e la gestione nativa di immagini, audio e video. Se il tuo caso d'uso e' multimodale o sensibile ai costi, Gemini e' spesso la partenza piu' conveniente.

Passo 1: ottenere la chiave API (gratis)

  1. Vai su aistudio.google.com e accedi con il tuo account Google.
  2. Cerca la voce "Get API key" / "Crea chiave API".
  3. Genera la chiave e copiala subito in un posto sicuro: e' una password, non condividerla e non scriverla mai dentro il codice che pubblichi.

Passo 2: installare l'SDK e impostare la chiave

Installa il pacchetto ufficiale (il nome corretto e' google-genai, da non confondere con vecchie librerie):

pip install -U google-genai

Il modo piu' pulito per usare la chiave e' una variabile d'ambiente: l'SDK la legge in automatico da GEMINI_API_KEY, cosi' non la scrivi mai nel codice.

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

# Windows (PowerShell)
setx GEMINI_API_KEY "la-tua-chiave"
Con poche righe di Python il tuo programma puo' interrogare i modelli Gemini ospitati da Google.

Passo 3: il tuo primo programma

Crea un file gemini_test.py e incolla:

from google import genai

# Il client legge la chiave da GEMINI_API_KEY
client = genai.Client()

risposta = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Spiega in 3 frasi semplici cos'e' un'API, come a un principiante."
)

print(risposta.text)

Eseguilo con python gemini_test.py. Risultato atteso: tre frasi chiare che spiegano cos'e' un'API. Hai appena fatto la tua prima chiamata a un modello di frontiera.

Passo 4: risposte in streaming

Per applicazioni interattive (una chat, un'interfaccia) conviene mostrare il testo mentre viene generato, parola per parola, invece di aspettare la risposta completa:

from google import genai

client = genai.Client()

flusso = client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Scrivi una breve storia per bambini su un robot curioso."
)

for blocco in flusso:
    print(blocco.text, end="", flush=True)

Vedrai il testo comparire progressivamente nel terminale, come accade nelle chat IA.

Passo 5: una conversazione con memoria

La singola chiamata non ricorda nulla. Per un dialogo che mantiene il contesto, usa l'oggetto chat, che conserva la cronologia per te:

from google import genai

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

r1 = chat.send_message("Ho in casa 2 cani e 1 gatto.")
print(r1.text)

r2 = chat.send_message("Quante zampe ci sono in totale?")
print(r2.text)  # Il modello ricorda gli animali della frase precedente

Risultato atteso: alla seconda domanda Gemini risponde "12 zampe", perche' ha tenuto a mente il messaggio precedente.

Passo 6: dare istruzioni e regolare il comportamento

Con un system instruction imposti il "ruolo" del modello, e con la temperature regoli quanto e' creativo (valori bassi = risposte piu' prevedibili, alti = piu' fantasiose):

from google import genai
from google.genai import types

client = genai.Client()

risposta = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Consigliami un nome per una gelateria artigianale a Torino.",
    config=types.GenerateContentConfig(
        system_instruction="Sei un esperto di branding. Rispondi in italiano, conciso.",
        temperature=0.9,
    ),
)
print(risposta.text)

Passo 7: analizzare un'immagine

Qui Gemini brilla: puoi passargli un'immagine insieme al testo. Installa Pillow (pip install pillow) e prova:

from google import genai
from PIL import Image

client = genai.Client()
immagine = Image.open("scontrino.jpg")

risposta = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=["Estrai data, totale e nome del negozio da questo scontrino.", immagine],
)
print(risposta.text)

Risultato atteso: i dati richiesti estratti dalla foto. Lo stesso schema funziona per descrivere immagini, leggere grafici o trascrivere testo da una foto.

Passo 8: ottenere JSON pulito da usare nel codice

Quando l'output deve finire in un programma, non vuoi testo libero ma dati strutturati. Gemini puo' restituire JSON garantito che rispetta uno schema:

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

class Ricetta(BaseModel):
    nome: str
    minuti: int
    vegetariana: bool

client = genai.Client()

risposta = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Dammi una ricetta veloce di pasta.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=Ricetta,
    ),
)
print(risposta.text)        # JSON valido
ricetta = risposta.parsed   # gia' come oggetto Python
print(ricetta.nome, ricetta.minuti)

In questo modo elimini il parsing fragile del testo: ottieni direttamente un oggetto pronto da usare.

Errori comuni e soluzioni

  • "API key not valid" / 400: la chiave e' sbagliata o non e' nell'ambiente. Verifica con echo $GEMINI_API_KEY (o riapri il terminale dopo setx su Windows).
  • "429 RESOURCE_EXHAUSTED": hai superato i limiti del piano gratuito. Attendi qualche minuto, riduci la frequenza delle chiamate o attiva la fatturazione per limiti piu' alti.
  • "404 model not found": il nome del modello e' errato o non disponibile per la tua chiave. Controlla l'identificativo esatto (es. gemini-3.5-flash) nella documentazione.
  • "ModuleNotFoundError: google": non hai installato il pacchetto giusto. Esegui di nuovo pip install -U google-genai nell'ambiente Python corretto.
  • Risposta vuota o bloccata: i filtri di sicurezza possono fermare alcuni contenuti. Controlla l'attributo del risultato che indica il motivo dell'interruzione.

Varianti, casi avanzati e quando non usare Gemini

Da qui puoi andare oltre: il function calling permette al modello di richiamare funzioni del tuo programma (cercare in un database, chiamare un'altra API); gli embeddings (via client.models.embed_content) trasformano i testi in vettori per costruire una ricerca semantica o un sistema RAG sui tuoi documenti; con Vertex AI porti tutto in un contesto enterprise con controlli di sicurezza e fatturazione aziendale.

Quando conviene un altro strumento? Se hai bisogno di privacy totale e dati che non escono dal tuo computer, valuta un modello locale (Ollama, LM Studio). Se sei gia' immerso nell'ecosistema di un altro fornitore o ti servono funzioni specifiche di GPT o Claude, le rispettive API restano ottime alternative. Per la maggior parte dei progetti che partono da zero, pero', la combinazione di costo, free tier e capacita' multimodali rende Gemini un punto di partenza difficile da battere. Il consiglio finale: parti da gemini-3.5-flash, fai funzionare il flusso completo e passa a Pro solo se il compito lo richiede davvero.