Google Gemini e' oggi una delle scelte piu' convenienti per costruire applicazioni con l'IA: modelli multimodali, una finestra di contesto enorme e un piano gratuito generoso per iniziare. In questa guida imparerai a usarne le API in Python, dalla prima chiamata fino a funzioni avanzate come lo streaming, l'analisi delle immagini e il function calling, con codice pronto da copiare.

A chi serve e cosa imparerai

La guida e' per chi sa scrivere un minimo di Python e vuole integrare Gemini in uno script, un bot o un'app. Al termine saprai: ottenere una chiave API gratis, fare una richiesta di base, ricevere risposte in streaming, inviare un'immagine da analizzare, far usare al modello i tuoi strumenti con il function calling e gestire errori e limiti. Non servono conoscenze di machine learning: usiamo il modello come un servizio, tramite chiamate.

Prerequisiti e come ottenere la chiave API gratis

Ti serve Python 3.9 o superiore e un account Google. Per la chiave:

  1. Vai su aistudio.google.com e accedi con l'account Google.
  2. Clicca su Get API key e poi su "Create API key".
  3. Copia la chiave e conservala. Non inserirla mai direttamente nel codice condiviso: usa una variabile d'ambiente.

Imposta la chiave come variabile d'ambiente nel terminale (cosi' non finisce nel codice):

export GEMINI_API_KEY="la-tua-chiave"     # Mac/Linux
setx GEMINI_API_KEY "la-tua-chiave"       # Windows (poi riapri il terminale)
Con poche righe di Python si chiama Gemini tramite l'SDK ufficiale.

Quale modello Gemini scegliere (e quanto costa)

Regola pratica: usa il modello Flash per quasi tutto, e passa a un modello Pro solo per i compiti di ragionamento piu' difficili. Gemini 3.6 Flash costa circa 1,50 dollari per milione di token in ingresso e 7,50 in uscita, e' velocissimo e multimodale: e' l'ideale per riassunti, estrazioni, chatbot e automazioni. I modelli della fascia Pro costano di piu' ma ragionano meglio su problemi complessi (matematica, codice difficile, analisi lunghe). Per i test hai comunque il piano gratuito di AI Studio, con limiti di richieste al minuto e al giorno. Verifica sempre i prezzi aggiornati sulla pagina ufficiale, perche' cambiano.

Installazione e prima chiamata in Python

Installa il pacchetto ufficiale e fai la prima richiesta:

pip install google-genai
import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Spiega la fotosintesi a un bambino di 8 anni, in 4 frasi."
)
print(resp.text)

Risultato atteso: quattro frasi semplici che spiegano la fotosintesi. Se vedi la risposta, la chiave funziona e sei pronto per il resto.

Risposte in streaming

Per app interattive (chatbot, interfacce) e' meglio mostrare il testo mentre viene generato, invece di attendere la risposta completa. Si usa il metodo di streaming:

for chunk in client.models.generate_content_stream(
    model="gemini-3.6-flash",
    contents="Scrivi una breve storia sulla luna."
):
    print(chunk.text, end="", flush=True)

Ogni chunk contiene un pezzo della risposta: stampandoli man mano ottieni l'effetto "macchina da scrivere" tipico dei chatbot.

Input multimodale: analizzare un'immagine

Gemini legge le immagini in modo nativo. Puoi inviargli una foto e farti descrivere cosa contiene o estrarre del testo:

from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

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

resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents=[
        types.Part.from_bytes(data=dati, mime_type="image/jpeg"),
        "Descrivi cosa vedi e trascrivi eventuale testo presente."
    ]
)
print(resp.text)

Risultato atteso: una descrizione dell'immagine e la trascrizione del testo eventualmente presente. E' utilissimo per digitalizzare scontrini, leggere cartelli o catalogare foto.

Gemini gestisce testo, immagini e chiamate a funzioni con lo stesso SDK.

Function calling: far usare a Gemini i tuoi strumenti

Il function calling permette al modello di chiamare funzioni che scrivi tu — per esempio per cercare in un database, controllare il meteo o fare un calcolo. Con l'SDK, basta passare la funzione Python: il modello decide quando usarla e con quali argomenti.

from google import genai
from google.genai import types

def meteo(citta: str) -> str:
    """Restituisce il meteo attuale per una citta'."""
    # Qui in un caso reale chiameresti una vera API meteo
    return f"A {citta} ci sono 25 gradi e cielo sereno."

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Che tempo fa a Roma?",
    config=types.GenerateContentConfig(tools=[meteo])
)
print(resp.text)

Il modello capisce che deve chiamare meteo("Roma"), ottiene il risultato e lo integra nella risposta finale, per esempio: "A Roma ci sono 25 gradi e cielo sereno." E' il mattone di base per costruire agenti che agiscono, non solo che chiacchierano.

Gestire errori, limiti e sicurezza

  • Errore 429: hai superato i limiti del piano gratuito. Inserisci una pausa tra le richieste o passa al piano a pagamento.
  • Risposta vuota o bloccata: il modello puo' rifiutare contenuti che violano le sue regole di sicurezza. Controlla i metadati della risposta per capire il motivo del blocco.
  • Chiave esposta: non mettere mai la chiave nel codice pubblico (GitHub compreso). Usa variabili d'ambiente o un file di configurazione escluso dal versionamento.
  • Costi a sorpresa: imposta un budget e degli avvisi nella console, soprattutto se metti in produzione un servizio con molte chiamate.

System instruction: dare a Gemini un ruolo fisso

Spesso vuoi che il modello mantenga sempre lo stesso comportamento: rispondere in italiano, essere conciso, non inventare. Invece di ripeterlo in ogni prompt, lo imposti una volta con la system instruction:

from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Chi ha scritto la Divina Commedia?",
    config=types.GenerateContentConfig(
        system_instruction="Sei un tutor scolastico. Rispondi in italiano, in modo breve e chiaro, e ammetti quando non sai qualcosa."
    )
)
print(resp.text)

Da quel momento tutte le risposte seguiranno quel ruolo, senza doverlo ricordare ogni volta. E' il modo giusto per costruire un assistente con una personalita' e delle regole coerenti.

Structured output: forzare una risposta in JSON

Se il modello alimenta un altro programma, non vuoi testo libero ma dati strutturati. Gemini permette di imporre un formato JSON, cosi' la risposta e' sempre analizzabile dal codice:

import json
from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Estrai nome e citta' da: 'Sono Luca e vivo a Torino.'",
    config=types.GenerateContentConfig(response_mime_type="application/json")
)
dati = json.loads(resp.text)
print(dati)

Il risultato atteso e' un oggetto JSON come nome: Luca, citta: Torino, gia' pronto per essere usato nel resto del programma. Impostare response_mime_type su "application/json" riduce drasticamente il rischio che il modello aggiunga frasi di contorno che manderebbero in errore il parsing. Per casi piu' complessi puoi anche definire uno schema esatto dei campi attesi, cosi' la risposta rispetta sempre la struttura che ti serve.

Prompt di prova pronti

Sei un assistente che risponde solo in JSON. Estrai da questo testo nome, email e azienda. Testo: "..."
Riassumi questo documento in 5 punti chiave, poi elenca 3 domande a cui il testo NON risponde.
Traduci il seguente testo in inglese mantenendo il tono formale, poi indica 2 alternative per la frase piu' difficile.

Alternative: OpenAI, Anthropic e DeepSeek

Gemini non e' l'unica opzione, e la struttura del codice e' simile per tutti. OpenAI (GPT) offre un ecosistema molto ricco e strumenti maturi; Anthropic (Claude) eccelle nella scrittura e nei compiti lunghi; DeepSeek e altri modelli cinesi hanno prezzi molto competitivi ed esistono versioni aperte da ospitare in locale con Ollama. Il consiglio pratico e' scegliere in base al compito e al budget, e strutturare il codice in modo da poter cambiare fornitore con poche modifiche. Per iniziare, pero', il piano gratuito di Gemini e la semplicita' dell'SDK google-genai ne fanno un ottimo punto di partenza. La documentazione ufficiale su ai.google.dev contiene esempi aggiornati per ogni funzione.