Korzystanie z kluczy interfejsu Gemini API

Aby korzystać z interfejsu Gemini API, potrzebujesz klucza interfejsu API. Na tej stronie dowiesz się, jak tworzyć klucze w Google AI Studio i nimi zarządzać oraz jak skonfigurować środowisko, aby używać ich w kodzie.

Tworzenie lub wyświetlanie klucza interfejsu Gemini API

Klucze API

Wszystkie klucze interfejsu Gemini API możesz tworzyć i nimi zarządzać na stronie Google AI Studio – Klucze interfejsu API.

Gdy uzyskasz klucz interfejsu API, możesz połączyć się z interfejsem Gemini API na te sposoby:

• Ustawianie klucza interfejsu API jako zmiennej środowiskowej
• Jawne podawanie klucza interfejsu API

Na potrzeby wstępnych testów możesz zakodować klucz interfejsu API na stałe, ale powinno to być tylko rozwiązanie tymczasowe, ponieważ nie jest bezpieczne. Przykłady zakodowania klucza interfejsu API znajdziesz w sekcji Jawne podawanie klucza interfejsu API.

Projekty Google Cloud

Projekty Google Cloud są niezbędne do korzystania z usług Google Cloud (takich jak Gemini API), zarządzania płatnościami oraz kontrolowania współpracowników i uprawnień. Google AI Studio udostępnia uproszczony interfejs do projektów Google Cloud.

Jeśli nie masz jeszcze utworzonych projektów, musisz utworzyć nowy projekt lub zaimportować projekt z Google Cloud do Google AI Studio. Na stronie Projekty w Google AI Studio będą wyświetlane wszystkie klucze, które mają wystarczające uprawnienia do korzystania z interfejsu Gemini API. Instrukcje znajdziesz w sekcji Importowanie projektów.

Projekt domyślny

Nowi użytkownicy po zaakceptowaniu Warunków korzystania z usługi mogą łatwo zacząć korzystać z Google AI Studio, ponieważ usługa tworzy domyślny projekt Google Cloud i klucz interfejsu API. Możesz zmienić nazwę tego projektu w Google AI Studio. W tym celu otwórz widok Projekty w panelu, kliknij przycisk ustawień z 3 kropkami obok projektu i wybierz Zmień nazwę projektu. W przypadku obecnych użytkowników lub użytkowników, którzy mają już konta Google Cloud, nie zostanie utworzony projekt domyślny.

Importowanie projektów

Każdy klucz interfejsu Gemini API jest powiązany z projektem Google Cloud. Domyślnie Google AI Studio nie wyświetla wszystkich Twoich projektów w Cloud. Musisz zaimportować wybrane projekty, wyszukując ich nazwę lub identyfikator projektu w oknie Importuj projekty. Aby wyświetlić pełną listę projektów, do których masz dostęp, otwórz Cloud Console.

Jeśli nie masz jeszcze zaimportowanych projektów, wykonaj te czynności, aby zaimportować projekt Google Cloud i utworzyć klucz:

1. Otwórz Google AI Studio.
2. Otwórz Panel z panelu bocznego po lewej stronie.
3. Kliknij Projekty.
4. Na stronie Projekty kliknij przycisk Importuj projekty.
5. Wyszukaj i wybierz projekt w chmurze Google Cloud, który chcesz zaimportować, a następnie kliknij przycisk Importuj.

Po zaimportowaniu projektu otwórz stronę Klucze interfejsów API w menu Panel i utwórz klucz interfejsu API w zaimportowanym projekcie.

Ograniczenia

Poniżej znajdziesz ograniczenia dotyczące zarządzania kluczami API i projektami Google Cloud w Google AI Studio.

• Możesz utworzyć maksymalnie 10 projektów naraz na stronie Projekty w Google AI Studio.
• Możesz nadawać nazwy projektom i kluczom oraz je zmieniać.
• 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.

Aby uzyskać dodatkowy dostęp do zarządzania projektami, w tym modyfikowania i ograniczania kluczy interfejsu API, otwórz stronę danych logowania w konsoli Google Cloud. W konsoli Cloud możesz wybrać projekt, kliknąć istniejący klucz interfejsu API, a następnie ograniczyć go do interfejsu Generative Language API.

Ustawianie klucza interfejsu API jako zmiennej środowiskowej

Jeśli ustawisz zmienną środowiskową GEMINI_API_KEY lub GOOGLE_API_KEY, klucz API zostanie automatycznie pobrany przez klienta podczas korzystania z jednej z bibliotek interfejsu Gemini API. Zalecamy ustawienie tylko jednej z tych zmiennych, ale jeśli ustawisz obie, pierwszeństwo ma zmienna GOOGLE_API_KEY.

Jeśli używasz interfejsu REST API lub JavaScriptu w przeglądarce, musisz podać klucz interfejsu API.

Oto jak możesz ustawić klucz interfejsu API lokalnie jako zmienną środowiskową GEMINI_API_KEY w różnych systemach operacyjnych.

~/.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 niektórych przypadkach możesz podać klucz interfejsu API. Na przykład:

• Wykonujesz proste wywołanie interfejsu API i wolisz zakodować klucz interfejsu API na stałe.
• Chcesz mieć pełną kontrolę bez konieczności polegania na automatycznym wykrywaniu zmiennych środowiskowych przez biblioteki interfejsu Gemini API.
• Używasz środowiska, w którym zmienne środowiskowe nie są obsługiwane (np.internet), lub wykonujesz wywołania REST.

Poniżej znajdziesz przykłady, jak jawnie podać klucz interfejsu API:

from google import genai

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

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

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

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

Zabezpiecz klucz interfejsu API

Traktuj klucz interfejsu Gemini API jak hasło. Jeśli zostanie on przejęty, inne osoby mogą wykorzystać limit projektu, ponieść opłaty (jeśli włączono płatności) i uzyskać dostęp do Twoich danych prywatnych, takich jak pliki.

Krytyczne reguły zabezpieczeń

• Zachowaj poufność kluczy: klucze interfejsu API do Gemini mogą uzyskiwać dostęp do danych wrażliwych, od których zależy Twoja aplikacja.

  • Nigdy nie przesyłaj kluczy interfejsu API do systemu kontroli wersji. Nie sprawdzaj klucza interfejsu API w systemach kontroli wersji, takich jak Git.

  • Nigdy nie udostępniaj kluczy interfejsu API po stronie klienta. Nie używaj klucza API bezpośrednio w aplikacjach internetowych ani mobilnych w środowisku produkcyjnym. Klucze w kodzie po stronie klienta (w tym w naszych bibliotekach JavaScript/TypeScript i wywołaniach REST) mogą zostać wyodrębnione.

• Ogranicz dostęp: w miarę możliwości ogranicz użycie klucza interfejsu API do określonych adresów IP, odsyłających adresów HTTP lub aplikacji na Androida/iOS.

• Ogranicz wykorzystanie: włącz tylko niezbędne interfejsy API dla każdego klucza.

• Regularnie przeprowadzaj audyty: regularnie sprawdzaj klucze interfejsu API i okresowo je zmieniaj.

Sprawdzone metody

• Używaj wywołań po stronie serwera z kluczami interfejsu API Najbezpieczniejszym sposobem używania klucza interfejsu API jest wywoływanie interfejsu Gemini API z aplikacji po stronie serwera, w której klucz może być poufny.

• Używaj tymczasowych tokenów do uzyskiwania dostępu po stronie klienta (tylko w przypadku interfejsu Live API): w celu uzyskania bezpośredniego dostępu do interfejsu Live API po stronie klienta możesz używać tymczasowych tokenów. Są one mniej ryzykowne pod względem bezpieczeństwa i mogą być używane w środowisku produkcyjnym. Więcej informacji znajdziesz w przewodniku dotyczącym tokenów tymczasowych.

• Rozważ dodanie ograniczeń do klucza: możesz ograniczyć uprawnienia klucza, dodając ograniczenia klucza interfejsu API. Minimalizuje to potencjalne szkody w przypadku wycieku klucza.

Ogólne sprawdzone metody znajdziesz też w tym artykule pomocy.

Rozwiązywanie problemów z tworzeniem klucza interfejsu API

W Google AI Studio przycisk Utwórz klucz interfejsu API może być niedostępny i wyświetlać komunikat: „Nie masz uprawnień do tworzenia klucza w tym projekcie”.

Dzieje się tak, gdy nie masz w projekcie uprawnień niezbędnych do wygenerowania nowego klucza:

• resourcemanager.projects.get: umożliwia AI Studio weryfikację istnienia projektu.
• apikeys.keys.create: umożliwia wygenerowanie klucza interfejsu API.
• serviceusage.services.enable: wymagane, aby interfejs Gemini API był aktywny w projekcie.
• iam.serviceAccounts.create: każdy nowy klucz interfejsu API wymaga teraz powiązanego konta usługi, które jest generowane podczas tworzenia klucza interfejsu API.

Aby naprawić uprawnienia, poproś administratora projektu lub administratora organizacji (jeśli projekt należy do organizacji) o przypisanie Ci roli z uprawnieniami wymienionymi powyżej (np. Edytujący projekt lub roli niestandardowej).

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