Le API di Google Gemini sono uno dei modi piu' economici per integrare un modello di IA potente nei propri programmi: il piano gratuito permette di sperimentare senza spendere nulla e l'SDK Python ufficiale rende tutto sorprendentemente semplice. In questa guida partiamo da zero - ottenere la chiave, installare la libreria - e arriviamo a esempi reali: testo, streaming, istruzioni di sistema, analisi di immagini e output strutturato in JSON.

A chi serve e prerequisiti

La guida e' pensata per chi sa scrivere un minimo di Python e vuole costruire qualcosa con l'IA: uno script di automazione, un piccolo chatbot, un classificatore di testi, un'analisi di documenti. Ti serve:

  • un account Google;
  • Python 3.9 o superiore installato;
  • una chiave API gratuita da Google AI Studio;
  • connessione a internet (le chiamate vanno ai server di Google).

Quale modello usare: Flash, Flash-Lite o Pro

La famiglia Gemini offre piu' modelli pensati per esigenze diverse:

  • Gemini 2.5 Flash (la prima scelta per iniziare): veloce, economico e abbastanza capace per la grande maggioranza dei compiti. A listino costa circa 0,30 dollari per milione di token in input e 2,50 in output, ed e' disponibile anche nel piano gratuito con quote giornaliere ridotte.
  • Gemini 2.5 Flash-Lite: ancora piu' economico e rapido, ideale per volumi alti e compiti semplici (classificazione, estrazione, risposte brevi).
  • Gemini 2.5 Pro: il piu' capace per ragionamento complesso e contesti lunghi, ma a partire da aprile 2026 e' accessibile solo a pagamento.

Rispetto alla concorrenza, il punto di forza di Gemini e' il rapporto qualita'/prezzo e il piano gratuito generoso sui modelli Flash; le API di OpenAI e Claude restano alternative valide, spesso scelte per esigenze specifiche di qualita' o di ecosistema. Per imparare e prototipare, Gemini 2.5 Flash e' difficile da battere.

Gemini 2.5 Flash e' il modello consigliato per iniziare. Foto: Pexels

Passo 1: ottenere la chiave API

Vai su Google AI Studio (aistudio.google.com), accedi con il tuo account Google e cerca la voce "Get API key" / "Crea chiave API". Genera una nuova chiave e copiala. Trattala come una password: non inserirla nel codice condiviso e non pubblicarla su GitHub. Il modo corretto e' salvarla in una variabile d'ambiente:

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

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

Passo 2: installare l'SDK

Google fornisce un SDK Python unificato e moderno, google-genai. Installalo con pip:

pip install google-genai

Attenzione a non confonderlo con la vecchia libreria google-generativeai: oggi quella consigliata e' google-genai, con un'interfaccia basata su un oggetto Client.

Passo 3: la tua prima chiamata

Ecco lo script minimo che invia un prompt e stampa la risposta. Se hai impostato la variabile d'ambiente, il client la trova da solo:

from google import genai

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

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

print(risposta.text)

Il risultato atteso e' una spiegazione chiara in tre frasi. Se preferisci passare la chiave esplicitamente: genai.Client(api_key="...").

Passo 4: risposte in streaming

Per un'esperienza tipo chat, dove il testo compare man mano, usa lo streaming:

stream = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents="Scrivi una breve storia per bambini su un robot curioso."
)
for chunk in stream:
    print(chunk.text, end="")

Ogni chunk contiene un pezzo della risposta: ideale per stamparlo a video in tempo reale.

Passo 5: istruzioni di sistema e parametri

Per dare al modello un "ruolo" o regolare la creativita', usa la configurazione:

from google import genai
from google.genai import types

client = genai.Client()
risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Consigliami un piatto veloce per cena.",
    config=types.GenerateContentConfig(
        system_instruction="Sei uno chef italiano. Rispondi in modo conciso e pratico.",
        temperature=0.7,
    ),
)
print(risposta.text)

La system_instruction definisce il comportamento; la temperature (da 0 a 2) regola quanto le risposte siano deterministiche o creative.

Con poche righe gestisci streaming, ruoli, immagini e output JSON. Foto: Pexels

Passo 6: analizzare un'immagine (multimodale)

Gemini e' nativamente multimodale: puo' leggere immagini. Passando un file insieme al testo, puoi chiedere una descrizione o un'estrazione di dati:

from google import genai
from PIL import Image

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

risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=["Estrai l'importo totale e la data da questo scontrino.", img]
)
print(risposta.text)

Passo 7: output strutturato in JSON

Per usare le risposte in un programma serve un formato prevedibile. Puoi chiedere a Gemini di restituire JSON valido e perfino imporre uno schema:

from google import genai
from google.genai import types

client = genai.Client()
risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Estrai nome, citta' ed eta' da: 'Marco vive a Torino e ha 34 anni.'",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema={
            "type": "object",
            "properties": {
                "nome": {"type": "string"},
                "citta": {"type": "string"},
                "eta": {"type": "integer"}
            }
        },
    ),
)
print(risposta.text)  # JSON pronto da elaborare

Il risultato atteso e' un oggetto JSON con i tre campi nome, citta ed eta, che puoi caricare con json.loads() e usare direttamente nel tuo programma.

Errori comuni e soluzioni

  • 429 RESOURCE_EXHAUSTED: hai superato i limiti del piano gratuito (richieste al minuto o al giorno). Rallenta le chiamate, attendi, oppure passa a un piano a pagamento.
  • 400 / API key not valid: chiave errata o non impostata. Verifica la variabile d'ambiente e che la chiave sia attiva su AI Studio.
  • 404 model not found: nome del modello sbagliato. Controlla che sia esattamente gemini-2.5-flash (o il modello che intendi usare).
  • Risposta vuota o bloccata: puo' dipendere dai filtri di sicurezza; controlla il campo dei "safety ratings" nella risposta.

Varianti, alternative e come proseguire

Da qui puoi crescere in molte direzioni: gestire conversazioni con memoria usando le sessioni di chat (client.chats.create(...)), collegare il modello a strumenti esterni con il function calling, o caricare PDF e file lunghi con l'API dei file per fare domande sui tuoi documenti. Se i tuoi volumi crescono, valuta il Batch mode, che dimezza i costi per i lavori non urgenti.

Quando non usare l'API direttamente? Se ti serve solo chattare ogni tanto, l'app o il sito di Gemini bastano. Se invece stai costruendo un prodotto, vorrai confrontare anche le API di OpenAI e di Anthropic per qualita', latenza e costi sul tuo caso d'uso. La documentazione completa, con tutti i modelli e i prezzi aggiornati, e' sul sito ufficiale Google AI for Developers.