Utilizzo delle chiavi API Gemini

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

Creare o visualizzare una chiave API Gemini

Tipi di chiavi API: standard e di autorizzazione

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

• Chiavi API standard: associa le richieste a un progetto Google Cloud per la fatturazione e la 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à del service account associato, consentendo un controllo dell'accesso granulare. 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 autorizzazione:

• Chiavi di autorizzazione predefinite: tutte le nuove chiavi API create in Google AI Studio vengono create automaticamente come chiavi di autorizzazione.
• 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 limitazioni esplicite continueranno a funzionare. Questa limitazione impedisce l'utilizzo 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. Prima di questa data, devi eseguire la migrazione a una chiave di autorizzazione per evitare interruzioni del servizio. Assicurati di eseguire la migrazione alle chiavi di autorizzazione prima di settembre 2026.

Gestire le chiavi API in Google AI Studio

Puoi gestire i progetti e le 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 accedendo 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 progetti esistenti.

Importare progetti

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 riquadro a sinistra e seleziona Progetti.
3. Fai clic sul pulsante Importa progetti.
4. Cerca e seleziona il progetto Google Cloud che vuoi importare, poi fai clic su Importa.
5. Una volta importato, vai alla pagina Chiavi API nella dashboard per creare una chiave nel progetto.

Risolvere i 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 cloud 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 delle chiavi.
• serviceusage.services.enable: garantisce che l'API Generative Language sia abilitata.
• iam.serviceAccounts.create: necessaria 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 per utilizzarla in modo sicuro nelle tue applicazioni.

Utilizzare le variabili di ambiente (opzione 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 vengono impostate entrambe, 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

Fornire 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 viene compromessa, altri utenti possono consumare la quota del tuo progetto, generare addebiti di fatturazione imprevisti e accedere a risorse private.

Regole di sicurezza critiche

• Mantieni riservate le chiavi: non eseguire mai il check-in delle 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. Gli utenti possono estrarre le chiavi compilate nel codice lato client. 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 di secret sicuro come Google Cloud Secret Manager.
• Avvisi di fatturazione: configura gli avvisi di fatturazione nella console Google Cloud per ricevere una notifica se l'utilizzo o i costi aumentano.

Elenco di controllo per la risposta alla perdita di dati

Se sospetti che la tua chiave API sia stata compromessa:

1. Genera una nuova chiave: crea una chiave sostitutiva in Google AI Studio o nella console Cloud.
2. Aggiorna l'applicazione: esegui il deployment del codice utilizzando la nuova chiave.
3. Disabilita o elimina la chiave compromessa: disabilita la chiave compromessa nella console Cloud dopo aver verificato 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 in Google Cloud Console 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.

Applicare le limitazioni all'origine delle richieste

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

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

Proteggere le chiavi API standard senza limitazioni

Per continuare a utilizzare l'API Gemini dopo il 19 giugno 2026, devi proteggere tutte 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.

Limitare la chiave per altri servizi tramite console Google Cloud

Se la chiave è condivisa con altre API di Google (opzione non consigliata), 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. Vai alla pagina Credenziali della console Google Cloud.
2. Seleziona il progetto e la chiave API.
3. In Limitazioni delle API, seleziona Limita chiave.
4. Dal 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 limitata separata in AI Studio per continuare a utilizzare l'API Gemini.

Chiavi inattive bloccate

A partire dal 7 maggio 2026, l'API Gemini bloccherà le chiavi API senza limitazioni che sono inattive da un periodo di tempo prolungato. Queste chiavi mostrano un tag Bloccato in AI Studio. Per continuare, devi generare una nuova chiave o utilizzare una chiave limitata esistente.

Eseguire la migrazione a una chiave di autorizzazione

Segui questi passaggi per creare una nuova chiave API di autorizzazione 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 autorizzazione.
4. Copia la nuova chiave API di autorizzazione.
5. Aggiorna il codice dell'applicazione, le variabili di ambiente e le configurazioni di deployment per utilizzare la nuova chiave API di autorizzazione.
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 un utilizzo improprio.

Limitazioni

Google AI Studio impone le seguenti limitazioni di 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 limitazioni 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.