Utilizzo delle chiavi API Gemini

Per utilizzare l'API Gemini, devi autenticare le tue richieste. Puoi autenticarti utilizzando una chiave API standard o di autorizzazione.

Creare o visualizzare una chiave API Gemini

Tipi di chiavi API: standard e autorizzazione

Le chiavi API forniscono l'accesso all'API Gemini, ma le loro caratteristiche di sicurezza sono diverse. L'API Gemini sta passando dalle chiavi API standard alle chiavi di autorizzazione per migliorare la sicurezza:

• Chiavi API standard: associano le richieste a un progetto Google Cloud ai fini di fatturazione e quota. Le chiavi standard non identificano un chiamante, il che limita la granularità delle autorizzazioni e del controllo dell'accesso che possono supportare.
• Chiavi di autorizzazione: associate direttamente a un service account Google Cloud. Quando utilizzi una chiave di autorizzazione, le tue richieste vengono elaborate con l'identità di questo service account associato, consentendo un controllo granulare dell'accesso. Per impostazione predefinita, le chiavi di autorizzazione sono limitate all'API Generative Language (API Gemini) e forniscono un'applicazione rapida delle chiavi compromesse che interrompe rapidamente l'utilizzo delle chiavi compromesse rilevate dai nostri sistemi.

Per garantire un utilizzo sicuro, l'API Gemini passerà dalle chiavi standard alle chiavi di autenticazione:

• Chiavi di autenticazione predefinite: tutte le nuove chiavi API create in Google AI Studio vengono create automaticamente come chiavi di autenticazione.
• Il 19 giugno 2026: l'API Gemini rifiuterà le richieste provenienti da chiavi standard senza limitazioni. Le chiavi API standard a cui sono state applicate restrizioni esplicite continueranno a funzionare. Questa limitazione impedisce l'uso non autorizzato di chiavi che potrebbero essere condivise pubblicamente o collegate ad altri servizi.
• A settembre 2026: l'API Gemini rifiuterà le richieste provenienti da chiavi standard. Devi eseguire la migrazione a chiavi di autenticazione prima di questa data per evitare interruzioni del servizio. Assicurati di eseguire la migrazione a chiavi di autenticazione prima di settembre 2026.

Gestione delle chiavi API in Google AI Studio

Puoi gestire i tuoi progetti e le tue chiavi direttamente in Google AI Studio.

Progetti Google Cloud

Ogni chiave API Gemini è associata a un progetto Google Cloud. I progetti Google Cloud gestiscono la fatturazione, i collaboratori e le autorizzazioni. Google AI Studio fornisce un'interfaccia leggera per accedere a questi progetti.

• Progetto predefinito: se sei un nuovo utente, Google AI Studio crea automaticamente un progetto Google Cloud e una chiave API predefiniti dopo che hai accettato i Termini di servizio. Puoi rinominare questo progetto andando alla visualizzazione Progetti nella dashboard.
• Progetti esistenti: se hai già un account Google Cloud, AI Studio non crea un progetto predefinito. Devi invece importare i tuoi progetti esistenti.

Importazione dei progetti in corso…

Per impostazione predefinita, Google AI Studio non mostra tutti i tuoi progetti Google Cloud. Devi importare i progetti che vuoi utilizzare:

1. Vai a Google AI Studio.
2. Apri la dashboard dal pannello a sinistra e seleziona Progetti.
3. Fai clic sul pulsante Importa progetti.
4. Cerca e seleziona il progetto Google Cloud da importare, poi fai clic su Importa.
5. Una volta importato, vai alla pagina Chiavi API nella dashboard per creare una chiave nel progetto.

Risoluzione dei problemi relativi alle autorizzazioni di creazione delle chiavi

Se il pulsante Crea chiave API non è disponibile e viene visualizzato il messaggio: "Non hai l'autorizzazione per creare una chiave in questo progetto", non disponi delle autorizzazioni IAM richieste.

Chiedi all'amministratore del progetto o dell'organizzazione Google Cloud di concederti un ruolo contenente le seguenti autorizzazioni (ad esempio Editor progetto):

• resourcemanager.projects.get: consente ad AI Studio di verificare il progetto.
• apikeys.keys.create: consente la generazione di chiavi.
• serviceusage.services.enable: garantisce che l'API Generative Language sia abilitata.
• iam.serviceAccounts.create: obbligatorio per creare il service account collegato.
• iam.serviceAccountApiKeyBindings.create: associa il service account alla chiave API.

Se non riesci a ottenere l'accesso amministrativo, puoi creare un nuovo progetto Google Cloud non associato a un'organizzazione per generare le chiavi.

Configurazione dell'ambiente

Una volta ottenuta una chiave, configura l'ambiente in modo da utilizzarla in modo sicuro nelle tue applicazioni.

Utilizzare le variabili di ambiente (scelta consigliata)

Imposta la variabile di ambiente GEMINI_API_KEY o GOOGLE_API_KEY. Le librerie client dell'API Gemini rilevano e utilizzano automaticamente queste variabili. Se entrambi sono impostati, GOOGLE_API_KEY ha la precedenza.

Seleziona il tuo sistema operativo per impostare la variabile:

~/.bashrc

touch ~/.bashrc && open ~/.bashrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.bashrc

~/.zshrc

touch ~/.zshrc && open ~/.zshrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.zshrc

Fornisci la chiave API in modo esplicito nel codice

Puoi passare la chiave API in modo esplicito durante l'inizializzazione del client. Esegui questa operazione solo se non puoi utilizzare le variabili di ambiente.

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how AI works in a few words"
)
print(response.text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

main();

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey:  "YOUR_API_KEY",
        Backend: genai.BackendGeminiAPI,
    })
    if err != nil {
        log.Fatal(err)
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.5-flash",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

package com.example;

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().apiKey("YOUR_API_KEY").build();

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-3.5-flash",
            "Explain how AI works in a few words",
            null);

    System.out.println(response.text());
  }
}

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent"       -H 'Content-Type: application/json'       -H "x-goog-api-key: YOUR_API_KEY"       -X POST       -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Sicurezza e gestione dei secret

Tratta la chiave API Gemini come una password. Se compromesse, altre persone possono consumare la quota del tuo progetto, incorrere in addebiti di fatturazione imprevisti e accedere a risorse private.

Regole di sicurezza critiche

• Mantieni riservate le chiavi: non archiviare mai le chiavi API nei sistemi di controllo del codice sorgente come Git.
• Non esporre mai le chiavi lato client in produzione: non codificare le chiavi API direttamente nelle app web o mobile. Le chiavi compilate nel codice lato client possono essere estratte dagli utenti. Per proteggere le app lato client, esegui un server proxy di backend per effettuare le chiamate API effettive.

Best practice per la gestione dei secret

• Variabili di ambiente: leggi le chiavi dalle variabili di ambiente anziché dai file di configurazione.
• Secret Manager: per la produzione, archivia le chiavi in un archivio dei secret sicuro come Google Cloud Secret Manager.
• Avvisi di fatturazione: configura gli avvisi di fatturazione nella console Google Cloud per ricevere una notifica in caso di picchi di utilizzo o costi.

Elenco di controllo per la risposta alle perdite di dati

Se sospetti che la tua chiave API sia stata divulgata:

1. Genera una nuova chiave: crea una chiave sostitutiva in Google AI Studio o nella console Google Cloud.
2. Aggiorna l'applicazione: esegui il deployment del codice utilizzando la nuova chiave.
3. Disattiva o elimina la chiave compromessa: disattiva la chiave compromessa in Cloud Console una volta verificata la nuova chiave. Non eliminare la vecchia chiave finché la nuova chiave non è completamente attiva per evitare tempi di inattività dell'applicazione.
4. Controlla l'utilizzo: controlla i log di fatturazione e l'utilizzo delle API nella console Google Cloud per identificare attività non autorizzate.

Limitare e proteggere le chiavi

L'aggiunta di limitazioni alle chiavi API riduce al minimo i potenziali danni in caso di compromissione di una chiave.

Applica limitazioni all'origine delle richieste

Le limitazioni di origine limitano gli indirizzi IP, i siti web o le applicazioni che possono utilizzare la tua chiave.

1. Vai alla pagina Credenziali della console Google Cloud.
2. Seleziona il tuo progetto e fai clic sul nome della chiave API che vuoi limitare.
3. In Restrizioni delle applicazioni, seleziona Indirizzi IP (o il tipo di restrizione appropriato per il tuo ambiente).
4. Specifica gli indirizzi o gli intervalli IP consentiti, quindi fai clic su Salva.

Protezione delle chiavi API standard senza limitazioni

Per continuare a utilizzare l'API Gemini dopo il 19 giugno 2026, devi proteggere le chiavi senza limitazioni.

Limitare la chiave solo all'API Gemini tramite AI Studio

Se utilizzi la chiave solo per l'API Gemini, proteggila direttamente in AI Studio:

1. Nella pagina Chiavi API di Google AI Studio, individua le chiavi contrassegnate con l'etichetta Senza limitazioni.
2. Passa il mouse sopra l'etichetta e fai clic su Aggiungi limitazioni nella finestra di dialogo.
3. Seleziona Limita solo all'API Gemini.
4. Fai clic su Limita chiave per confermare.

Limita la chiave per altri servizi tramite la console Google Cloud

Se la chiave è condivisa con altre API di Google (non consigliato), limitala nella console Cloud. Nota: le richieste dell'API Gemini che utilizzano questa chiave non andranno a buon fine dopo l'applicazione di queste limitazioni.

1. Visita la pagina Credenziali della console Google Cloud.
2. Seleziona il progetto e la chiave API.
3. In Restrizioni delle API, seleziona Limita chiave.
4. Nel menu a discesa, seleziona le API a cui vuoi che questa chiave acceda. Non selezionare l'API Generative Language.
5. Fai clic su Salva. Crea una chiave separata e limitata in AI Studio per continuare a utilizzare l'API Gemini.

Chiavi inattive bloccate

A partire dal 7 maggio 2026, l'API Gemini blocca le chiavi API senza limitazioni che sono rimaste inattive per un periodo prolungato. Queste chiavi mostrano un tag Bloccato in AI Studio. Per continuare, devi generare una nuova chiave o utilizzarne una esistente con limitazioni.

Esegui la migrazione a una chiave di autenticazione

Per creare una nuova chiave API di autenticazione e aggiornare le tue applicazioni:

1. Vai alla pagina Chiavi API di AI Studio.
2. Controlla la colonna Tipo di chiave per identificare le chiavi elencate come Standard.
3. Fai clic su Crea chiave API per generare una nuova chiave. Tutte le nuove chiavi create in AI Studio vengono create automaticamente come chiavi di autenticazione.
4. Copia la nuova chiave API di autenticazione.
5. Aggiorna il codice dell'applicazione, le variabili di ambiente e qualsiasi configurazione di deployment per utilizzare la nuova chiave API di autenticazione.
6. Testa l'applicazione per verificare che funzioni correttamente con la nuova chiave.
7. Una volta verificata, elimina o revoca la vecchia chiave di traffico per evitare abusi.

Limitazioni

Google AI Studio impone le seguenti limitazioni alla gestione di progetti e chiavi:

• Puoi creare un massimo di 10 progetti alla volta dalla pagina Progetti di Google AI Studio.
• Le pagine Chiavi API e Progetti mostrano un massimo di 100 chiavi e 50 progetti.
• Vengono visualizzate solo le chiavi API senza restrizioni o limitate specificamente all'API Generative Language (API Gemini).

Per la gestione avanzata dei progetti o per modificare le chiavi con altre limitazioni, utilizza la pagina delle credenziali di console Google Cloud.