Le API di Gemini sono uno dei modi più economici per portare un modello potente nelle proprie applicazioni Python, soprattutto da quando Gemini 3.5 Flash offre un buon equilibrio tra qualità, velocità e prezzo. In questa guida costruiamo, passo dopo passo, le funzioni che servono davvero in un progetto reale: prima chiamata, risposta in streaming, input multimodale (immagini e PDF), output JSON strutturato e function calling.

A chi serve e cosa ti serve prima di iniziare

Questa guida è pensata per chi sa già scrivere un minimo di Python (variabili, funzioni, installare pacchetti con pip) e vuole integrare Gemini in uno script o in un piccolo servizio. Prerequisiti reali:

  • Python 3.9 o superiore installato sul tuo sistema (Windows, macOS o Linux).
  • Un account Google per ottenere una chiave API gratuita da Google AI Studio.
  • Connessione a Internet: i modelli girano sui server di Google, non in locale.

Perché Gemini e non altro? Per molti casi d'uso il piano gratuito di AI Studio basta per sviluppare e testare, la finestra di contesto da 1 milione di token semplifica il lavoro con documenti lunghi e l'SDK è pulito. Se invece ti serve il massimo del ragionamento puoi valutare GPT di OpenAI o Claude di Anthropic; per l'uso in locale e offline, modelli aperti via Ollama. Per la maggior parte delle integrazioni, però, Gemini 3.5 Flash è una prima scelta sensata per costo ed equilibrio.

Passo 1: ottenere la chiave API (gratis)

  1. Vai su aistudio.google.com e accedi con il tuo account Google.
  2. Apri la sezione "API keys" (Chiavi API) e clicca su "Create API key".
  3. Copia la chiave e conservala: non condividerla e non inserirla mai in un repository pubblico.

Il piano gratuito ha limiti di frequenza (richieste al minuto e al giorno) ed è perfetto per imparare. Per il passaggio in produzione attiverai la fatturazione e userai il modello a consumo.

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

Installa il pacchetto ufficiale, chiamato google-genai (attenzione a non confonderlo con vecchie librerie ormai deprecate):

pip install -q -U google-genai

Imposta la chiave come variabile d'ambiente, così non la scrivi nel codice. Su macOS/Linux:

export GEMINI_API_KEY="la_tua_chiave"

Su Windows (PowerShell):

setx GEMINI_API_KEY "la_tua_chiave"

La prima chiamata è di tre righe. Se la variabile d'ambiente è impostata, il client la legge da solo:

from google import genai

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

resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Spiega in 3 punti cos'e' una finestra di contesto"
)
print(resp.text)

Risultato atteso: un elenco di tre punti, restituito tipicamente in meno di un secondo. Se ottieni un errore di autenticazione, controlla che la chiave sia corretta e che la variabile d'ambiente sia visibile nel terminale in cui esegui lo script.

Passo 3: risposte in streaming

Per un'esperienza simile a una chat, conviene mostrare la risposta man mano che viene generata, invece di attendere il testo completo:

for chunk in client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Scrivi una breve email di benvenuto per un nuovo cliente"
):
    print(chunk.text, end="")

Ogni chunk contiene un pezzo di testo: stamparlo subito dà la sensazione di "scrittura in diretta" tipica degli assistenti.

Passo 4: input multimodale (immagini e PDF)

Gemini 3.5 Flash accetta anche immagini, audio, video e PDF. Per analizzare un'immagine locale puoi caricarla con il client e passarla insieme alla domanda:

img = client.files.upload(file="grafico.png")

resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=["Descrivi cosa mostra questo grafico e indica il trend principale", img]
)
print(resp.text)

Lo stesso schema funziona con un PDF: utile, ad esempio, per estrarre i punti chiave di un contratto o di un bando. Per documenti molto lunghi, ricorda che il contesto da 1 milione di token ti permette di passare l'intero file in un'unica richiesta.

Passo 5: output JSON strutturato

Quando il risultato deve essere usato da un programma (non letto da un umano), conviene chiedere un JSON con uno schema preciso. Con l'SDK puoi definire lo schema con Pydantic e passarlo nella configurazione:

from pydantic import BaseModel

class Contatto(BaseModel):
    nome: str
    email: str
    azienda: str

resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Estrai i dati di contatto da: 'Sono Anna Rossi di Berto Srl, anna@berto.it'",
    config={
        "response_mime_type": "application/json",
        "response_schema": Contatto,
    },
)
print(resp.text)  # JSON valido e conforme allo schema

Risultato atteso: un JSON come {"nome": "Anna Rossi", "email": "anna@berto.it", "azienda": "Berto Srl"}. Imporre lo schema riduce drasticamente gli errori di formato rispetto al chiedere "rispondi in JSON" a parole.

Passo 6: function calling (far agire il modello)

Il function calling permette al modello di chiamare funzioni che scrivi tu, ad esempio per consultare un database o un'API meteo. Con il nuovo SDK basta passare la funzione Python come strumento: il client gestisce in automatico la chiamata.

def prezzo_spedizione(paese: str, peso_kg: float) -> dict:
    '''Restituisce il costo di spedizione in euro dato paese e peso.'''
    tariffe = {"IT": 5.0, "FR": 9.0, "DE": 9.0}
    base = tariffe.get(paese, 15.0)
    return {"costo_eur": base + peso_kg * 1.5}

resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Quanto costa spedire 2 kg in Francia?",
    config={"tools": [prezzo_spedizione]},
)
print(resp.text)

Il modello capisce che deve usare la funzione, la chiama con i parametri estratti dalla domanda (paese="FR", peso_kg=2) e formula la risposta finale in linguaggio naturale usando il risultato. È il mattone di base degli agenti.

Errori comuni e come risolverli

  • "API key not valid" / 401: chiave errata o variabile d'ambiente non caricata. Riapri il terminale dopo averla impostata e verifica con un'istruzione di stampa.
  • "429 Resource exhausted": hai superato i limiti del piano gratuito. Rallenta le richieste, aspetta, oppure attiva la fatturazione.
  • "model not found": identificativo errato. Usa esattamente gemini-3.5-flash (senza suffissi tipo "preview").
  • JSON malformato: non chiederlo a parole, usa response_schema come nel Passo 5.

Costi, limiti e prossimi passi

In sviluppo, il piano gratuito di AI Studio copre quasi tutto. In produzione, Gemini 3.5 Flash costa circa 1,50 dollari per milione di token in ingresso e 9 per milione in uscita, con forti sconti sui token serviti dalla cache: per questo conviene strutturare i prompt riutilizzando le parti fisse. Da qui puoi proseguire costruendo un piccolo agente che combina più funzioni, oppure un sistema RAG che passa a Gemini i tuoi documenti come contesto. La documentazione ufficiale di Google resta il riferimento per le funzioni più avanzate, come l'esecuzione di codice e la ricerca come strumento.