Utilizzo delle chiavi API Gemini

Per utilizzare l'API Gemini, devi avere una chiave API. Questa pagina descrive come creare e gestire le chiavi in Google AI Studio, nonché come configurare l'ambiente per utilizzarle nel codice.

Chiavi API

Una chiave API è una stringa criptata che puoi utilizzare quando chiami le API Google Cloud. Puoi creare e gestire tutte le tue chiavi API Gemini dalla pagina Chiavi API di Google AI Studio.

Una volta ottenuta una chiave API, hai le seguenti opzioni per connetterti all'API Gemini:

• Impostare la chiave API come variabile di ambiente
• Fornire esplicitamente la chiave API

Per i test iniziali, puoi codificare una chiave API, ma questa operazione deve essere temporanea perché non è sicura. Puoi trovare esempi di codifica hardcoded della chiave API nella sezione Fornire la chiave API in modo esplicito.

Progetti Google Cloud

I progetti Google Cloud sono fondamentali per utilizzare i servizi Google Cloud (come l'API Gemini), gestire la fatturazione e controllare collaboratori e autorizzazioni. Google AI Studio fornisce un'interfaccia leggera per i tuoi progetti Google Cloud.

Se non hai ancora creato progetti, devi crearne uno nuovo o importarne uno da Google Cloud in Google AI Studio. La pagina Progetti in Google AI Studio mostrerà tutte le chiavi che dispongono dell'autorizzazione sufficiente per utilizzare l'API Gemini. Per istruzioni, consulta la sezione Importare progetti.

Importare progetti

Ogni chiave API Gemini è associata a un progetto Google Cloud. Per impostazione predefinita, Google AI Studio non mostra tutti i tuoi progetti cloud. Devi importare i progetti che vuoi cercando il nome o l'ID progetto nella finestra di dialogo Importa progetti. Per visualizzare un elenco completo dei progetti a cui hai accesso, visita Cloud Console.

Se non hai ancora importato progetti, segui questi passaggi per importare un progetto Google Cloud e creare una chiave:

1. Vai a Google AI Studio.
2. Apri la dashboard dal riquadro a sinistra.
3. Seleziona Progetti.
4. Seleziona il pulsante Importa progetti nella pagina Progetti.
5. Cerca e seleziona il progetto Google Cloud che vuoi importare e fai clic sul pulsante Importa.

Una volta importato un progetto, vai alla pagina Chiavi API dal menu Dashboard e crea una chiave API nel progetto che hai appena importato.

Limitazioni

Di seguito sono riportate le limitazioni della gestione delle chiavi API e dei progetti Google Cloud in Google AI Studio.

• Puoi creare un massimo di 10 progetti alla volta dalla pagina Progetti di Google AI Studio.
• Puoi assegnare un nome e rinominare progetti e chiavi.
• Le pagine Chiavi API e Progetti mostrano un massimo di 100 chiavi e 100 progetti.
• Vengono visualizzate solo le chiavi API senza limitazioni o limitate all'API Generative Language.

Per un accesso di gestione aggiuntivo ai tuoi progetti, visita Google Cloud Console.

Impostazione della chiave API come variabile di ambiente

Se imposti la variabile di ambiente GEMINI_API_KEY o GOOGLE_API_KEY, la chiave API verrà rilevata automaticamente dal client quando utilizzi una delle librerie dell'API Gemini. Ti consigliamo di impostare solo una di queste variabili, ma se vengono impostate entrambe, GOOGLE_API_KEY ha la precedenza.

Se utilizzi l'API REST o JavaScript sul browser, devi fornire la chiave API in modo esplicito.

Ecco come impostare la chiave API localmente come variabile di ambiente GEMINI_API_KEY con sistemi operativi diversi.

~/.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

In alcuni casi, potresti voler fornire esplicitamente una chiave API. Ad esempio:

• Stai effettuando una semplice chiamata API e preferisci codificare la chiave API.
• Vuoi un controllo esplicito senza dover fare affidamento al rilevamento automatico delle variabili di ambiente da parte delle librerie dell'API Gemini
• Stai utilizzando un ambiente in cui le variabili di ambiente non sono supportate (ad es.web) o stai effettuando chiamate REST.

Di seguito sono riportati alcuni esempi di come puoi fornire una chiave API in modo esplicito:

from google import genai

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

response = client.models.generate_content(
    model="gemini-2.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-2.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-2.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-2.5-flash",
            "Explain how AI works in a few words",
            null);

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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"
          }
        ]
      }
    ]
  }'

Proteggere la chiave API

Tratta la chiave API Gemini come una password. Se viene compromesso, altri possono utilizzare la quota del tuo progetto, sostenere addebiti (se la fatturazione è abilitata) e accedere ai tuoi dati privati, come i file.

Regole di sicurezza critiche

• Non eseguire mai il commit delle chiavi API nel controllo del codice sorgente. Non archiviare la chiave API in sistemi di controllo della versione come Git.

• Non esporre mai le chiavi API lato client. Non utilizzare la chiave API direttamente nelle app web o mobile in produzione. Le chiavi nel codice lato client (incluse le nostre librerie JavaScript/TypeScript e le chiamate REST) possono essere estratte.

Best practice

• Utilizza chiamate lato server con chiavi API Il modo più sicuro per utilizzare la chiave API è chiamare l'API Gemini da un'applicazione lato server in cui la chiave può essere mantenuta riservata.

• Utilizzare token effimeri per l'accesso lato client (solo API Live): per l'accesso diretto lato client all'API Live, puoi utilizzare token effimeri. Presentano rischi per la sicurezza inferiori e possono essere adatti all'uso in produzione. Per ulteriori informazioni, consulta la guida sui token effimeri.

• Valuta la possibilità di aggiungere limitazioni alla chiave:puoi limitare le autorizzazioni di una chiave aggiungendo limitazioni relative alle chiavi API. Ciò riduce al minimo i potenziali danni in caso di perdita della chiave.

Per alcune best practice generali, puoi anche consultare questo articolo del Centro assistenza.