Le API di Gemini permettono di usare i modelli di Google dentro i propri programmi Python: chatbot, script di automazione, analisi di documenti, assistenti su misura. Questa guida ti porta dalla chiave API gratuita al primo programma funzionante, fino a streaming, immagini, output JSON e chiamata di funzioni. È il terzo capitolo, dopo le guide alle API di OpenAI e di Claude, di una serie pensata per chi vuole imparare a costruire con i grandi modelli.

A chi serve questa guida e cosa ti serve prima

È pensata per chi sa scrivere un minimo di Python (variabili, funzioni, installare pacchetti con pip) e vuole integrare Gemini in un progetto. Prerequisiti: Python 3.9 o superiore installato, un account Google e cinque minuti per ottenere la chiave. Non serve una carta di credito per iniziare: il piano gratuito di Google AI Studio è sufficiente per imparare e prototipare.

Ottenere la chiave API gratis su Google AI Studio

  1. Vai su aistudio.google.com e accedi con il tuo account Google.
  2. Cerca la voce "Get API key" (Ottieni chiave API) nel menu.
  3. Crea una nuova chiave e copiala: è una stringa che inizia in genere con AIza...
  4. Conservala in modo sicuro. Non incollarla mai nel codice pubblico né in un repository su GitHub.

Il piano gratuito ha limiti di richieste al minuto e al giorno che variano per modello, ma sono più che sufficienti per fare pratica. Per andare in produzione con volumi alti si passa al piano a pagamento, collegando la fatturazione.

Installare l'SDK e la prima chiamata

Google offre l'SDK ufficiale google-genai. Installalo e imposta la chiave come variabile d'ambiente (più sicuro che scriverla nel codice):

pip install google-genai

# Linux/macOS
export GEMINI_API_KEY="la-tua-chiave"
# Windows (PowerShell)
setx GEMINI_API_KEY "la-tua-chiave"

Ora il primo programma. L'SDK legge automaticamente la variabile GEMINI_API_KEY:

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 tre frasi cos'è un modello linguistico, per un pubblico non tecnico."
)
print(risposta.text)

Esegui lo script: dovresti vedere una spiegazione in tre frasi. Se ottieni un errore di autenticazione, controlla che la variabile d'ambiente sia impostata nella stessa sessione del terminale.

Quale modello scegliere: Flash o Pro

La famiglia Gemini si divide grossomodo in due linee. I modelli Flash (per esempio gemini-2.5-flash, o le versioni più recenti come Gemini 3.6 Flash) sono veloci ed economici, ideali per la maggior parte dei compiti: riassunti, classificazione, chatbot, estrazione dati. I modelli Pro sono più potenti sul ragionamento complesso, il codice e i problemi in più passaggi, ma costano di più e sono più lenti. Come prima scelta consiglio Flash: nella pratica risolve gran parte dei casi d'uso a una frazione del costo, e si passa a Pro solo quando serve davvero più capacità di ragionamento. Controlla sempre la documentazione ufficiale per l'identificatore esatto del modello aggiornato, perché i nomi cambiano con le nuove versioni.

Risposte in streaming

Per mostrare il testo mentre viene generato — come fa l'interfaccia di ChatGPT — usa lo streaming, che migliora molto l'esperienza in un'app interattiva:

from google import genai

client = genai.Client()
stream = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents="Scrivi una breve fiaba della buonanotte, in italiano."
)
for chunk in stream:
    print(chunk.text, end="", flush=True)

Immagini e input multimodale

Gemini è multimodale: puoi passargli un'immagine e farci domande sopra. Basta includere il file tra i contenuti insieme al testo:

from google import genai
from PIL import Image

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

risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[immagine, "Elenca gli articoli e il totale di questo scontrino."]
)
print(risposta.text)

È utilissimo per estrarre dati da foto di documenti, descrivere immagini o fare da assistente visivo. Il risultato atteso è un elenco degli articoli con i relativi prezzi e il totale.

Output JSON strutturato con Pydantic

Se il testo ti serve dentro un programma, chiedere JSON con uno schema preciso evita di dover "ripulire" la risposta. Con l'SDK puoi imporre uno schema tramite Pydantic:

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

class Prodotto(BaseModel):
    nome: str
    prezzo: float

client = genai.Client()
risposta = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Estrai i prodotti: 2 caffè 2,60 euro, 1 brioche 1,20 euro.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=list[Prodotto],
    ),
)
print(risposta.text)  # JSON valido, pronto per json.loads()

Chiamare funzioni (function calling)

Il function calling permette al modello di invocare funzioni del tuo codice — per esempio per leggere dati aggiornati o eseguire un'azione. Definisci una normale funzione Python e passala come strumento: l'SDK gestisce automaticamente la chiamata.

from google import genai

def meteo(citta: str) -> str:
    """Restituisce il meteo attuale per una città."""
    # qui chiameresti una vera API meteo
    return f"A {citta} è sereno, 28 gradi."

client = genai.Client()
chat = client.chats.create(model="gemini-2.5-flash", config={"tools": [meteo]})
risposta = chat.send_message("Che tempo fa a Bologna?")
print(risposta.text)

Il modello capisce che deve usare la funzione meteo, la chiama con l'argomento giusto e integra il risultato nella risposta.

Errori comuni e soluzioni

  • "API key not valid": la chiave è sbagliata o non impostata. Verifica la variabile d'ambiente e di averla copiata per intero.
  • "429 Resource exhausted": hai superato i limiti del piano gratuito. Aspetta qualche minuto, riduci le richieste o passa al piano a pagamento.
  • "model not found": il nome del modello è cambiato. Controlla l'ID corrente nella documentazione ufficiale.
  • ModuleNotFoundError: google: hai installato il pacchetto sbagliato. Serve google-genai, non altri pacchetti dal nome simile.

Varianti, costi e come proseguire

Con queste basi puoi costruire molto: un chatbot che mantiene la cronologia con client.chats.create(), un analizzatore di PDF che combina estrazione testo e riassunto, un piccolo agente che usa più funzioni. Tieni d'occhio i costi impostando limiti di spesa nella console di fatturazione e preferendo Flash quando basta. Il passo successivo naturale è il RAG — collegare il modello ai tuoi documenti — e la costruzione di agenti che concatenano più strumenti. La documentazione di Google AI for Developers e il repository dell'SDK restano i riferimenti da tenere aperti mentre sviluppi.