Hai un account Google Cloud, un progetto attivo e l'API Gemini abilitata. Però quando provi a fare la prima chiamata, ottieni errori 403, 429 o semplicemente non trovi la chiave giusta da usare. Succede a tutti.
Noi, di Meteora Web, abbiamo integrato Gemini in diversi progetti per clienti — chatbot, analisi testi, generazione contenuti. Il primo passo è sempre lo stesso: impostare l'autenticazione in modo corretto. Se sbagli qui, perdi tempo e soldi. Sei pronto? Partiamo dal problema concreto e arriviamo al codice funzionante in pochi minuti.
Perché l'autenticazione è il tallone d'Achille
L'API Gemini non è pubblica come un open endpoint. Serve una chiave strettamente personale (API Key) oppure un account di servizio OAuth 2.0. Per chi inizia, la strada più rapida è l'API Key. Ma attenzione: una chiave esposta in un repository pubblico o in un frontend mobile viene usata da altri a tue spese. Lo abbiamo visto su controlli di sicurezza per clienti: chiavi hardcoded in codice JavaScript, pronte per essere rubate da bot scraper.
La seconda cosa da sapere: l'API Key non è gratis. Anche se Google offre un tier gratuito (60 richieste al minuto per Gemini 1.5 Flash, fino a 1.000 batch al giorno), serve una modalità di pagamento configurata. Senza fatturazione abilitata, la chiamata cade su un 403 con messaggio "Billing account not found". Fastidioso, ma risolvibile.
Passo 1: Ottenere la chiave API da Google AI Studio
Collega il progetto Google Cloud
Vai su Google AI Studio API Keys. Se non hai ancora un progetto, clicca su Create API Key e scegli Create new project. Ti verrà chiesto di attivare la fatturazione. Fallo subito: anche se non superi la quota gratuita, è obbligatoria. Noi consigliamo di creare un progetto dedicato solo per Gemini, separato da altri servizi Google Cloud, per tenere traccia dei costi.
Genera la chiave
Una volta creato il progetto, clicca Create API Key. Copia la stringa che inizia con AIza.... Non chiudere la finestra senza averla salvata — Google non la mostra più una volta chiusa. Se succede, puoi rigenerarla dalla stessa pagina.
Proteggi la chiave
Mai scrivere la chiave nel codice sorgente. La soluzione più comune: variabili d'ambiente. Su Linux/macOS: export GEMINI_API_KEY='la_tua_chiave', su Windows PowerShell: $env:GEMINI_API_KEY='la_tua_chiave'. In produzione, usa un vault o un servizio di secret management (es. Google Secret Manager, AWS Secrets Manager). Noi, in Laravel, usiamo il file .env con GEMINI_API_KEY=... e lo escludiamo dal repository via .gitignore.
Passo 2: Scegliere la libreria client — Python vs cURL
Google mette a disposizione SDK ufficiali per Python, Node.js, Go, Java. La libreria Python google-generativeai è la più semplice per iniziare. Se preferisci testare via REST, puoi usare cURL. Mostriamo entrambe, così impari anche la logica di base.
Installazione della libreria Python
pip install google-generativeaiIn un ambiente virtuale (consigliato):
python -m venv venv
source venv/bin/activate # su Windows: venv\Scripts\activate
pip install google-generativeaiPrima richiesta con Python
import google.generativeai as genai
import os
# Legge la chiave dall'ambiente
api_key = os.environ.get("GEMINI_API_KEY")
if not api_key:
raise ValueError("Manca la variabile d'ambiente GEMINI_API_KEY")
genai.configure(api_key=api_key)
# Scegli il modello - qui usiamo gemini-1.5-flash per velocità
model = genai.GenerativeModel("gemini-1.5-flash")
# Risposta testuale
response = model.generate_content("Spiega cos'è un API key in due righe.")
print(response.text)Se tutto funziona, vedrai una spiegazione breve. Questo è il tuo primo contatto operativo con Gemini. Se ottieni un errore google.api_core.exceptions.PermissionDenied: 403, controlla:
- La chiave è copiata correttamente?
- La fatturazione è abilitata nel progetto?
- L'API Generative Language (gemini.googleapis.com) è abilitata? Puoi verificarlo dalla console Google Cloud → API e servizi → Libreria.
Prima richiesta con cURL (REST)
A volte vuoi testare direttamente via terminale, per debug o automazione.
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=LA_TUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts":[{"text": "Come si dice API key in italiano?"}]
}]
}'L'endpoint usa generateContent sul modello specificato. La risposta sarà un JSON con candidates[0].content.parts[0].text. Questo approccio è utile per linguaggi senza SDK ufficiale.
Passo 3: Gestire gli errori e i limiti di quota
Anche con l'autenticazione corretta, puoi incappare in 429 Resource exhausted se superi i limiti. Google fornisce quote per richieste al minuto e per giorno. Nella console Cloud, puoi monitorare l'utilizzo e richiedere aumenti (a pagamento). Noi consigliamo di implementare un retry con backoff esponenziale lato client, e di loggare ogni errore per capire se serve alzare la quota.
Esempio di retry Python
import time
from google.api_core.exceptions import ResourceExhausted
max_retries = 3
for attempt in range(max_retries):
try:
response = model.generate_content("Test")
break
except ResourceExhausted:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # 1,2,4 secondiPasso 4: Autenticazione con OAuth 2.0 per ambienti server-to-server
Se sviluppi un'applicazione che deve agire per conto di un account di servizio (es. batch di generazione in cron job), l'API Key non basta per sicurezza. Servono le credenziali OAuth 2.0. Vai su Google Cloud Console → IAM e Admin → Account di servizio → Crea. Scarica il file JSON della chiave privata. Poi usa la libreria google-auth per ottenere un token di accesso.
from google.oauth2 import service_account
SCOPES = ["https://www.googleapis.com/auth/cloud-platform"]
credentials = service_account.Credentials.from_service_account_file(
"path/to/service-account-key.json", scopes=SCOPES)
genai.configure(credentials=credentials)
# Il resto ugualeNoi lo usiamo per processi automatici in Laravel: il cron job esegue uno script con le credenziali del service account, senza esporre la chiave API in chiaro.
In sintesi — cosa fare adesso
- Ottieni la chiave da Google AI Studio, con fatturazione attiva.
- Salva la chiave in una variabile d'ambiente, mai nel codice.
- Esegui la prima richiesta con Python o cURL, testando il modello
gemini-1.5-flash. - Controlla errori: 403 → autorizzazione, 429 → quota, 404 → modello sbagliato.
- Per produzione usa OAuth 2.0 con account di servizio e implementa retry.
Se ti blocchi su un passaggio specifico, scrivici. Noi, di Meteora Web, affrontiamo questi setup ogni giorno per i nostri clienti. L'importante è che il tuo codice parli con Gemini, non che tu combatta con l'autenticazione.
Sponsored Protocol
