Korzystanie z kluczy interfejsu Gemini API

Aby korzystać z interfejsu Gemini API, musisz uwierzytelnić swoje żądania. Możesz uwierzytelnić się za pomocą standardowego klucza interfejsu API lub klucza autoryzacji.

Tworzenie lub wyświetlanie klucza interfejsu Gemini API

Typy kluczy interfejsu API: standardowy i autoryzacji

Klucze interfejsu API zapewniają dostęp do interfejsu Gemini API, ale różnią się pod względem bezpieczeństwa. Aby zwiększyć bezpieczeństwo, interfejs Gemini API przechodzi ze standardowych kluczy interfejsu API na klucze autoryzacji:

• Standardowe klucze interfejsu API: powiązują żądania z projektem w chmurze Google Cloud na potrzeby rozliczeń i limitów. Standardowe klucze nie identyfikują wywołującego, co ogranicza szczegółowość uprawnień i kontroli dostępu, które mogą obsługiwać.
• Klucze autoryzacji: są powiązane bezpośrednio z kontem usługi Google Cloud. Gdy używasz klucza autoryzacji, Twoje żądania są przetwarzane w ramach tożsamości powiązanego konta usługi, co umożliwia szczegółową kontrolę dostępu. Klucze autoryzacji są domyślnie ograniczone do interfejsu Generative Language API (Gemini API) i zapewniają szybkie egzekwowanie zasad dotyczących wycieku kluczy, które szybko blokuje użycie wyciekłych kluczy wykrytych przez nasze systemy.

Aby zapewnić bezpieczne korzystanie, interfejs Gemini API przejdzie ze standardowych kluczy na klucze autoryzacji:

• Domyślne klucze autoryzacji: wszystkie nowe klucze interfejsu API utworzone w Google AI Studio są automatycznie tworzone jako klucze autoryzacji.
• Odrzucanie kluczy bez ograniczeń: interfejs Gemini API odrzuca żądania z nieograniczonych standardowych kluczy. Standardowe klucze interfejsu API, do których zastosowano wyraźne ograniczenia, nadal działają. To ograniczenie uniemożliwia nieautoryzowane użycie kluczy, które mogą być udostępniane publicznie lub powiązane z innymi usługami.
• We wrześniu 2026 r.: interfejs Gemini API będzie odrzucać żądania z kluczy standardowych. Aby uniknąć przerw w działaniu usługi, musisz przeprowadzić migrację na klucze autoryzacji przed tą datą. Pamiętaj, aby przeprowadzić migrację na klucze autoryzacji przed wrześniem 2026 r.

Zarządzanie kluczami interfejsu API w Google AI Studio

Projektami i kluczami możesz zarządzać bezpośrednio w Google AI Studio.

Projekty Google Cloud

Każdy klucz interfejsu Gemini API jest powiązany z projektem Google Cloud. Projekty Google Cloud zarządzają rozliczeniami, współpracownikami i uprawnieniami. Google AI Studio udostępnia uproszczony interfejs do uzyskiwania dostępu do tych projektów.

• Projekt domyślny: jeśli jesteś nowym użytkownikiem, po zaakceptowaniu Warunków korzystania z usługi Google AI Studio automatycznie utworzy domyślny projekt w chmurze Google Cloud i klucz interfejsu API. Możesz zmienić nazwę tego projektu, otwierając widok Projekty na panelu.
• Istniejące projekty: jeśli masz już konto Google Cloud, AI Studio nie utworzy domyślnego projektu. Zamiast tego musisz zaimportować istniejące projekty.

Importowanie projektów

Domyślnie Google AI Studio nie wyświetla wszystkich Twoich projektów Google Cloud. Musisz zaimportować projekty, których chcesz używać:

1. Otwórz Google AI Studio.
2. W panelu po lewej stronie otwórz Panel i wybierz Projekty.
3. Kliknij przycisk Importuj projekty.
4. Wyszukaj i wybierz projekt Google Cloud, który chcesz zaimportować, a potem kliknij Importuj.
5. Po zaimportowaniu otwórz stronę Klucze interfejsu API na panelu, aby utworzyć klucz w tym projekcie.

Rozwiązywanie problemów z uprawnieniami do tworzenia kluczy

Jeśli przycisk Utwórz klucz interfejsu API jest niedostępny i wyświetla się komunikat „Nie masz uprawnień do tworzenia klucza w tym projekcie”, oznacza to, że nie masz wymaganych uprawnień IAM.

Poproś administratora projektu w chmurze lub administratora organizacji Google Cloud o przyznanie Ci roli zawierającej te uprawnienia (np. Edytujący projekt):

• resourcemanager.projects.get: umożliwia AI Studio weryfikację projektu.
• apikeys.keys.create: umożliwia generowanie kluczy.
• serviceusage.services.enable: zapewnia włączenie interfejsu Generative Language API.
• iam.serviceAccounts.create: wymagane do utworzenia połączonego konta usługi.
• iam.serviceAccountApiKeyBindings.create: wiąże konto usługi z kluczem interfejsu API.

Jeśli nie możesz uzyskać dostępu administracyjnego, możesz utworzyć nowy projekt Google Cloud, który nie jest powiązany z organizacją, aby wygenerować klucze.

Konfiguruję środowisko

Gdy masz już klucz, skonfiguruj środowisko, aby bezpiecznie używać go w aplikacjach.

Opcja 1. Użyj zmiennych środowiskowych (zalecane)

Ustaw zmienną środowiskową GEMINI_API_KEY lub GOOGLE_API_KEY. Biblioteki klienta interfejsu Gemini API automatycznie wykrywają i używają tych zmiennych. Jeśli obie są ustawione, pierwszeństwo ma GOOGLE_API_KEY.

Aby ustawić zmienną, wybierz system operacyjny:

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

Opcja 2. Podaj klucz interfejsu API bezpośrednio w kodzie

Klucz interfejsu API możesz przekazać bezpośrednio podczas inicjowania klienta. Zrób to tylko wtedy, gdy nie możesz używać zmiennych środowiskowych.

from google import genai

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

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)

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

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

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.output_text);
}

main();

package main

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

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)
    }

    interaction, err := client.Interactions.NewModel(ctx, interactions.NewModelParams{
        Model: "gemini-3.5-flash",
        Input: interactions.Input{
            String: "Explain how AI works in a few words",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range interaction.Steps {
        if step.ModelOutput != nil {
            for _, content := range step.ModelOutput.Content {
                if content.Text != nil {
                    fmt.Println(content.Text.Text)
                }
            }
        }
    }
}

package com.example;

import com.google.genai.Client;
import com.google.genai.interactions.models.interactions.CreateModelInteractionParams;
import com.google.genai.interactions.models.interactions.Interaction;

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

    CreateModelInteractionParams params =
        CreateModelInteractionParams.builder()
            .input("Explain how AI works in a few words")
            .model("gemini-3.5-flash")
            .build();

    Interaction interaction = client.interactions.create(params);

    interaction.steps().forEach(step -> {
      if (step.isModelOutput()) {
        step.asModelOutput().content().ifPresent(contents -> {
          contents.forEach(content -> {
            content.text().ifPresent(text -> System.out.println(text.text()));
          });
        });
      }
    });
  }
}

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -X POST \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Explain how AI works in a few words"
  }'

Bezpieczeństwo i zarządzanie obiektami tajnymi

Traktuj klucz interfejsu Gemini API jak hasło. Jeśli zostanie on naruszony, inne osoby mogą wykorzystać limit projektu, ponieść nieoczekiwane opłaty i uzyskać dostęp do zasobów prywatnych.

Krytyczne reguły bezpieczeństwa

• Zachowaj klucze w tajemnicy: nigdy nie zapisuj kluczy interfejsu API w systemach kontroli źródła takich jak Git.
• Nigdy nie udostępniaj kluczy po stronie klienta w środowisku produkcyjnym: nie koduj na stałe kluczy interfejsu API bezpośrednio w aplikacjach internetowych ani mobilnych. Klucze skompilowane w kodzie po stronie klienta mogą zostać wyodrębnione przez użytkowników. Aby zabezpieczyć aplikacje po stronie klienta, uruchom serwer proxy backendu, który będzie wykonywać rzeczywiste wywołania interfejsu API.

Sprawdzone metody zarządzania obiektami tajnymi

• Zmienne środowiskowe: odczytuj klucze ze zmiennych środowiskowych, a nie z plików konfiguracyjnych.
• Secret Manager: w środowisku produkcyjnym przechowuj klucze w bezpiecznym magazynie obiektów tajnych takim jak Google Cloud Secret Manager.
• Alerty rozliczeniowe: skonfiguruj w konsoli Google Cloud alerty rozliczeniowe, które będą Cię informować o nagłym wzroście wykorzystania lub kosztów.

Lista kontrolna dotycząca reagowania na wyciek danych

Jeśli podejrzewasz, że Twój klucz interfejsu API wyciekł:

1. Wygeneruj nowy klucz: utwórz klucz zastępczy w Google AI Studio lub w konsoli Cloud.
2. Zaktualizuj aplikację: wdróż kod, używając nowego klucza.
3. Wyłącz lub usuń naruszony klucz: po zweryfikowaniu nowego klucza wyłącz wyciekły klucz w konsoli Cloud. Aby uniknąć przestoju aplikacji, nie usuwaj starego klucza, dopóki nowy klucz nie będzie w pełni aktywny.
4. Sprawdź wykorzystanie: sprawdź logi rozliczeń i wykorzystanie interfejsu API w konsoli Google Cloud , aby zidentyfikować nieautoryzowaną aktywność.

Ograniczanie i zabezpieczanie kluczy

Dodanie ograniczeń do kluczy interfejsu API minimalizuje potencjalne szkody w przypadku naruszenia bezpieczeństwa klucza.

Stosowanie ograniczeń dotyczących pochodzenia żądania

Ograniczenia dotyczące pochodzenia ograniczają, które adresy IP, witryny lub aplikacje mogą używać Twojego klucza.

1. Otwórz stronę Dane logowania w konsoli Google Cloud.
2. Wybierz projekt i kliknij nazwę klucza interfejsu API, który chcesz ograniczyć.
3. W sekcji Ograniczenia aplikacji wybierz Adresy IP (lub odpowiedni typ ograniczenia dla Twojego środowiska).
4. Określ dozwolone adresy IP lub zakresy, a potem kliknij Zapisz.

Zabezpieczanie standardowych kluczy interfejsu API bez ograniczeń

Aby nadal korzystać z interfejsu Gemini API, musisz zabezpieczyć wszystkie klucze bez ograniczeń.

Metoda A. Ogranicz klucz tylko do interfejsu Gemini API (AI Studio)

Jeśli używasz klucza tylko w interfejsie Gemini API, zabezpiecz go bezpośrednio w AI Studio:

1. Na stronie Klucze interfejsu API w Google AI Studio znajdź klucze oznaczone etykietą Bez ograniczeń.
2. Najedź kursorem na etykietę i w oknie kliknij Dodaj ograniczenia.
3. Wybierz Ogranicz tylko do interfejsu Gemini API.
4. Aby potwierdzić, kliknij Ogranicz klucz.

Metoda B. Ogranicz klucz do innych usług (konsola Google Cloud)

Jeśli klucz jest udostępniany innym interfejsom API Google (niezalecane), ogranicz go w konsoli Cloud. Uwaga: po zastosowaniu tych ograniczeń żądania do interfejsu Gemini API używające tego klucza będą kończyć się niepowodzeniem.

1. Otwórz stronę Dane logowania w konsoli Google Cloud.
2. Wybierz projekt i klucz interfejsu API.
3. W sekcji Ograniczenia interfejsów API użyj menu Wybierz ograniczenia interfejsu API , aby wybrać interfejsy API, do których ten klucz ma mieć dostęp. Nie wybieraj interfejsu Generative Language API.
4. Kliknij Zapisz. Aby nadal korzystać z interfejsu Gemini API, utwórz w AI Studio osobny klucz z ograniczeniami.

Zablokowane nieaktywne klucze

Od 7 maja 2026 r. interfejs Gemini API będzie blokować nieograniczone klucze interfejsu API, które były nieaktywne przez dłuższy czas. Te klucze będą oznaczone w AI Studio tagiem Zablokowany. Aby kontynuować, musisz wygenerować nowy klucz lub użyć istniejącego klucza z ograniczeniami.

Migracja na klucz autoryzacji

Aby utworzyć nowy klucz interfejsu API autoryzacji i zaktualizować aplikacje, wykonaj te czynności:

1. Otwórz stronę Klucze interfejsu API w AI Studio.
2. Sprawdź kolumnę Typ klucza , aby zidentyfikować klucze oznaczone jako Standardowy.
3. Aby wygenerować nowy klucz, kliknij Utwórz klucz interfejsu API. Wszystkie nowe klucze utworzone w AI Studio są automatycznie tworzone jako klucze autoryzacji.
4. Skopiuj nowy klucz interfejsu API autoryzacji.
5. Zaktualizuj kod aplikacji, zmienne środowiskowe i konfiguracje wdrożenia, aby używać nowego klucza interfejsu API autoryzacji.
6. Przetestuj aplikację, aby sprawdzić, czy działa prawidłowo z nowym kluczem.
7. Po sprawdzeniu usuń lub unieważnij stary klucz ruchu, aby zapobiec jego nadużyciu.

Ograniczenia

Google AI Studio nakłada te ograniczenia dotyczące zarządzania projektami i kluczami:

• Na stronie Projekty w Google AI Studio możesz utworzyć maksymalnie 10 projektów naraz.
• Na stronach Klucze interfejsu API i Projekty wyświetla się maksymalnie 100 kluczy i 50 projektów.
• Wyświetlane są tylko klucze interfejsu API, które nie mają ograniczeń lub są ograniczone do interfejsu Generative Language API (Gemini API).

Aby korzystać z zaawansowanego zarządzania projektami lub modyfikować klucze z innymi ograniczeniami, użyj strony Dane logowania w konsoli Google Cloud.