L'API di Google Gemini e' uno dei modi piu' rapidi (e con un piano gratuito generoso) per mettere un modello multimodale dentro le tue applicazioni. In questa guida costruiamo, passo dopo passo, l'uso pratico in Python: dalla chiave gratuita alla prima risposta, fino a streaming, analisi di immagini, output JSON strutturato e function calling. E' il complemento naturale alle nostre guide gia' pubblicate sulle API di OpenAI, Anthropic e DeepSeek.

A chi serve e cosa otterrai

E' pensata per sviluppatori (anche alle prime armi con le API) che vogliono integrare Gemini in script, bot o backend. Al termine saprai fare una chiamata base, ricevere le risposte in streaming, far "leggere" un'immagine al modello, ottenere dati in formato JSON pulito e collegare il modello a funzioni del tuo codice. Prerequisiti: Python 3.9 o superiore, un account Google e qualche minuto per generare la chiave.

Perche' Gemini e quando preferirlo

Gemini ha tre punti di forza per chi inizia: un piano gratuito ampio tramite Google AI Studio, ottime capacita' multimodali (testo, immagini, audio, video) e finestre di contesto molto grandi. Rispetto ai concorrenti:

  • Pro: generosa fascia gratuita per provare e prototipare; forte sul multimodale; contesto lungo; SDK semplice.
  • Contro: i limiti del piano gratuito (richieste al minuto e al giorno) e il fatto che, nel piano gratuito, i dati possono essere usati per migliorare i prodotti — quindi non inviarci informazioni riservate finche' non passi a un piano a pagamento con tutele adeguate.

Come prima scelta per imparare e prototipare lo consigliamo proprio per la fascia gratuita: ti permette di sperimentare sul serio senza inserire subito una carta di credito.

Passo 1: ottenere la chiave API gratuita

Vai su Google AI Studio (aistudio.google.com), accedi con l'account Google e cerca la voce Get API key / Crea chiave API. Genera la chiave e copiala. Non scriverla mai dentro il codice che condividi: impostala come variabile d'ambiente.

# su Linux/Mac (terminale)
export GEMINI_API_KEY="la-tua-chiave"

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

Una nota importante di sicurezza: dal 19 giugno 2026 l'API non accetta piu' richieste da chiavi prive di restrizioni e risponde con errore 403. Conviene quindi, dalla console, limitare la chiave (per applicazione/IP) appena possibile.

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

Installa la libreria ufficiale:

pip install -U google-genai

La prima richiesta di testo:

import os
from google import genai

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

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

Il risultato atteso e' una spiegazione breve e chiara in tre frasi. Il modello gemini-2.5-flash e' veloce ed economico, ideale per la maggior parte dei compiti; per ragionamenti piu' complessi esistono varianti "Pro" piu' potenti.

Con poche righe e la chiave gratuita si ottiene la prima risposta da Gemini.

Passo 3: risposte in streaming

Per app interattive conviene mostrare il testo man mano che arriva, come fa ChatGPT:

stream = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents="Scrivi una breve filastrocca sull'estate."
)
for chunk in stream:
    print(chunk.text, end="")

Vedrai la filastrocca comparire parola per parola, invece di attendere l'intera risposta. Migliora molto la percezione di velocita' per l'utente.

Passo 4: far leggere un'immagine al modello

Il bello di Gemini e' la multimodalita'. Puoi inviare un'immagine e fare domande su di essa:

from google.genai import types

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

resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        types.Part.from_bytes(data=dati, mime_type="image/jpeg"),
        "Descrivi cosa c'e' in questa foto e indica eventuali testi presenti."
    ]
)
print(resp.text)

Il risultato atteso e' una descrizione dell'immagine con l'elenco degli oggetti riconosciuti e l'eventuale testo letto. E' utilissimo per catalogare foto, estrarre informazioni da scontrini o analizzare schermate.

Passo 5: ottenere output JSON strutturato

Quando il modello deve alimentare un altro programma, serve un output prevedibile. Gemini permette di forzare uno schema JSON:

from google.genai import types

resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Estrai nome, citta' e professione: 'Sono Luca, faccio l'architetto a Milano.'",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema={
            "type": "object",
            "properties": {
                "nome": {"type": "string"},
                "citta": {"type": "string"},
                "professione": {"type": "string"}
            },
            "required": ["nome","citta","professione"]
        }
    )
)
print(resp.text)   # JSON valido, pronto da convertire con json.loads()

Il risultato atteso e' un JSON del tipo {"nome":"Luca","citta":"Milano","professione":"architetto"}, che puoi caricare direttamente con json.loads() senza ripuliture manuali.

Passo 6: collegare il modello alle tue funzioni (function calling)

Il function calling permette al modello di chiedere al tuo codice di eseguire un'azione, per esempio interrogare un database o un'API meteo. Definisci una funzione Python e lasci che il modello decida quando usarla:

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

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

L'SDK gestisce automaticamente il ciclo: il modello capisce che serve la funzione meteo, la chiama con l'argomento "Bologna", riceve il risultato e formula la risposta finale. Abbiamo dedicato una guida specifica al function calling per chi vuole approfondire questo meccanismo, che e' la base degli agenti.

Errori comuni e come risolverli

  • 403 Forbidden / API key not valid: chiave errata, scaduta o senza restrizioni configurate. Rigenera la chiave da AI Studio e imposta le restrizioni richieste.
  • 429 Resource exhausted: hai superato i limiti del piano gratuito (richieste al minuto o al giorno). Rallenta, aggiungi una pausa tra le chiamate o passa a un piano a pagamento.
  • ModuleNotFoundError: google.genai: SDK non installato o ambiente sbagliato; ripeti pip install -U google-genai nello stesso ambiente che esegue lo script.
  • Il JSON non e' valido: assicurati di aver impostato response_mime_type="application/json" e uno schema corretto; senza schema il modello puo' aggiungere testo extra.

Buone pratiche e come proseguire

Tieni la chiave sempre fuori dal codice e dai repository pubblici; imposta limiti di spesa quando passi al piano a pagamento; parti da gemini-2.5-flash e sali ai modelli Pro solo se il compito lo richiede, perche' costano di piu'. Da qui puoi proseguire costruendo un piccolo assistente che combina ricerca, lettura di immagini e function calling: e' di fatto l'ossatura di un agente. La documentazione ufficiale per sviluppatori e il changelog restano i riferimenti per modelli, limiti e novita' aggiornate.