Le API di Google Gemini sono uno dei modi più economici per integrare un modello linguistico potente nelle proprie applicazioni: il piano gratuito di Google AI Studio permette di iniziare senza carta di credito, e il modello gemini-3.5-flash offre buona qualità a costi e latenza contenuti. Questa guida ti accompagna dalla creazione della chiave fino allo streaming, alle immagini e all'output in formato JSON, con codice che puoi copiare e far girare subito.

A chi serve questa guida e cosa ti occorre

È pensata per chi sa programmare almeno un po' in Python e vuole usare Gemini via codice, non dall'interfaccia web: sviluppatori, data analyst, makers che costruiscono automazioni o piccoli prodotti. I prerequisiti sono pochi:

  • Python 3.9 o superiore installato (verifica con python --version).
  • Un account Google per ottenere la chiave API da Google AI Studio.
  • Dimestichezza con il terminale e con pip.

Per questo compito — chiamare Gemini da Python — lo strumento ufficiale è l'SDK google-genai, che sostituisce le vecchie librerie. In alternativa Gemini espone anche un endpoint compatibile con le librerie di OpenAI, comodo se hai già codice scritto per quelle; ma per sfruttare tutte le funzioni conviene l'SDK nativo, che useremo qui come prima scelta.

Passo 1: ottenere la chiave e installare l'SDK

Vai su Google AI Studio, accedi con l'account Google e genera una chiave API dalla sezione dedicata. Copiala e — regola d'oro — non scriverla mai dentro il codice che condividi: usala come variabile d'ambiente.

# installa l'SDK ufficiale
pip install google-genai

# imposta la chiave come variabile d'ambiente (Linux/macOS)
export GEMINI_API_KEY="la_tua_chiave"

Su Windows (PowerShell) il comando è $env:GEMINI_API_KEY="la_tua_chiave". In un progetto reale conviene usare un file .env e la libreria python-dotenv per caricarlo.

Passo 2: la prima chiamata a Gemini

Ecco il programma minimo che invia un prompt e stampa la risposta:

from google import genai

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

resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Spiega in 3 frasi semplici cos'e' un'API, per un principiante.",
)
print(resp.text)

Il risultato atteso è una spiegazione breve e chiara stampata a terminale. La struttura è sempre questa: si crea un Client, si chiama models.generate_content indicando il modello e il contenuto, e si legge resp.text.

Con poche righe e l'SDK google-genai si effettua la prima chiamata a Gemini. Foto: Pexels

Passo 3: streaming, per risposte che appaiono parola per parola

Per chat e interfacce conversazionali conviene lo streaming: il testo arriva a pezzi (chunk) man mano che il modello lo genera, invece di aspettare la risposta completa. Migliora di molto la percezione di velocità.

for chunk in client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Scrivi una breve storia di 200 parole su un robot curioso.",
):
    print(chunk.text, end="", flush=True)

Ogni iterazione del ciclo riceve un frammento di testo che viene stampato subito. Se sviluppi un'app asincrona, esiste la variante await client.aio.models.generate_content_stream(...) da usare dentro un ciclo async for.

Passo 4: analizzare un'immagine (multimodale)

Gemini è nativamente multimodale: può ricevere testo e immagini insieme. Questo apre casi d'uso concreti come descrivere una foto, leggere uno scontrino o classificare un'immagine. Ecco come passare un file locale:

from google import genai
from google.genai import types

client = genai.Client()

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

resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        types.Part.from_bytes(data=immagine, mime_type="image/jpeg"),
        "Descrivi questa immagine in italiano e indica eventuale testo presente.",
    ],
)
print(resp.text)

Il modello restituisce una descrizione dell'immagine. Lo stesso schema vale per PDF e altri formati supportati: si passa una lista di «parti», mescolando dati e istruzioni testuali.

Passo 5: ottenere un output JSON affidabile

Quando l'IA deve alimentare un'altra parte del programma, non vuoi testo libero ma dati strutturati. Gemini permette di forzare una risposta in JSON. L'approccio più semplice è chiederlo nel prompt e impostare il tipo di risposta:

from google.genai import types

resp = client.models.generate_content(
    model="gemini-3.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",
    ),
)
print(resp.text)  # es. {"nome": "Marco", "citta": "Torino", "eta": 34}

Impostare response_mime_type="application/json" dice al modello di rispondere solo con JSON valido, che puoi poi caricare con json.loads(resp.text). Per garanzie più forti si può fornire anche uno schema esplicito.

Passo 6: tenere d'occhio i token e i costi

I modelli si pagano a token (frammenti di parole). Sapere quanti ne consuma una richiesta aiuta a stimare i costi e a non superare i limiti di contesto:

conteggio = client.models.count_tokens(
    model="gemini-3.5-flash",
    contents="Quanti token consuma questa frase di prova?",
)
print(conteggio.total_tokens)

Il piano gratuito di AI Studio impone limiti di richieste al minuto e al giorno; per andare oltre si passa a un progetto con fatturazione attiva. Conviene sempre verificare le tariffe aggiornate nella documentazione ufficiale, perché cambiano nel tempo e variano tra i modelli Flash (economici) e Pro (più potenti).

Errori comuni e come risolverli

  • «API key not valid» o errore 401/403: la chiave è sbagliata o non è stata caricata. Controlla che la variabile d'ambiente sia impostata nello stesso terminale da cui lanci lo script.
  • Errore 429 (Resource exhausted): hai superato i limiti del piano gratuito. Rallenta le richieste, aggiungi una breve pausa tra le chiamate o passa a un piano a pagamento.
  • ModuleNotFoundError: No module named 'google': l'SDK non è installato nell'ambiente attivo. Verifica con pip show google-genai e, se usi un ambiente virtuale, assicurati che sia attivo.
  • Risposta vuota o bloccata: può dipendere dai filtri di sicurezza. Controlla l'attributo con le informazioni sul blocco nella risposta e riformula il prompt.

Varianti, alternative e prossimi passi

Se ti serve più potenza per ragionamento e codice, sostituisci il modello con la versione Pro della stessa famiglia, accettando costi e tempi maggiori. Se invece lavori già con strumenti pensati per OpenAI, l'endpoint compatibile di Gemini ti permette di riusare quel codice cambiando solo l'URL di base e la chiave. Per applicazioni enterprise su Google Cloud, lo stesso SDK funziona anche con Vertex AI, con autenticazione tramite account di servizio.

Da qui puoi proseguire costruendo una piccola chat con memoria della conversazione, aggiungendo il «function calling» per far chiamare al modello le tue funzioni, oppure integrando Gemini in un'app web. Il pattern resta sempre lo stesso che hai imparato: client, modello, contenuti, risposta. Una volta interiorizzato, passare da un esempio giocattolo a un prodotto reale è soprattutto questione di gestione degli errori, dei costi e dei dati — non di nuove API da imparare.