Korzystanie z kluczy interfejsu Gemini API

Aby korzystać z interfejsu Gemini API, musisz uwierzytelnić swoje żądania. Możesz to zrobić 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. Klucze standardowe nie identyfikują osoby wywołującej, 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.
• 19 czerwca 2026 r.: interfejs Gemini API będzie odrzucać żądania z nieograniczonych kluczy standardowych. Standardowe klucze interfejsu API, do których zastosowano wyraźne ograniczenia, będą nadal działać. 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 przed tą datą przejść na klucze autoryzacji. Pamiętaj, aby przejść 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 służą do zarządzania płatnościami, współpracownikami i uprawnieniami. Google AI Studio udostępnia uproszczony interfejs umożliwiający dostęp 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. roli 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.

Konfigurowanie środowiska

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

Używanie 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

Jawne podawanie klucza interfejsu API w kodzie

Klucz interfejsu API możesz przekazać jawnie 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")

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"
          }
        ]
      }
    ]
  }'

Bezpieczeństwo i zarządzanie obiektami tajnymi

Traktuj klucz interfejsu Gemini API jak hasło. Jeśli klucz zostanie 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 dotyczące płatności: skonfiguruj alerty dotyczące płatności w konsoli Google Cloud, aby otrzymywać powiadomienia 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 Cloud Console.
2. Zaktualizuj aplikację: wdróż kod, używając nowego klucza.
3. Wyłącz lub usuń naruszony klucz: gdy nowy klucz zostanie zweryfikowany, wyłącz wyciekły klucz w Cloud Console. Aby uniknąć przestoju aplikacji, nie usuwaj starego klucza, dopóki nowy klucz nie będzie w pełni aktywny.
4. Sprawdź wykorzystanie: sprawdź logi płatności i wykorzystanie interfejsu API w Google Cloud Console, 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 nieograniczonych standardowych kluczy interfejsu API

Aby nadal korzystać z interfejsu Gemini API po 19 czerwca 2026 r., musisz zabezpieczyć wszystkie nieograniczone klucze.

Ograniczanie klucza tylko do interfejsu Gemini API za pomocą AI Studio

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

1. Na stronie Klucze interfejsu API w Google AI Studio znajdź klucze oznaczone etykietą Nieograniczone.
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.

Ogranicz klucz do innych usług za pomocą konsoli Google Cloud

Jeśli klucz jest udostępniany innym interfejsom API Google (co nie jest zalecane), ogranicz go w Cloud Console. 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 kliknij Ogranicz klucz.
4. Z menu wybierz interfejsy API, do których ten klucz ma mieć dostęp. Nie wybieraj interfejsu Generative Language API.
5. 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 przez dłuższy czas były nieaktywne. Te klucze są oznaczone w AI Studio tagiem Zablokowane. Aby kontynuować, musisz wygenerować nowy klucz lub użyć istniejącego klucza z ograniczeniami.

Przechodzenie na klucz autoryzacji

Aby utworzyć nowy klucz 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 autoryzacji.
5. Zaktualizuj kod aplikacji, zmienne środowiskowe i konfiguracje wdrożenia, aby używać nowego klucza 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 tylko 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.