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.

Po uzyskaniu klucza 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 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.
3. Kliknij Projekty.
4. Na stronie Projekty kliknij przycisk Importuj projekty.
5. Wyszukaj i wybierz projekt 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 interfejsu 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, zmienna GOOGLE_API_KEY będzie miała pierwszeństwo.

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

Poniżej znajdziesz instrukcje ustawiania klucza interfejsu API lokalnie jako zmiennej środowiskowejGEMINI_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 chcieć jawnie 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.
• Korzystasz ze ś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 Gemini API mogą uzyskiwać dostęp do danych wrażliwych, od których zależy Twoja aplikacja.

  • Nigdy nie zapisuj kluczy interfejsu API w systemie 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 Gemini API z aplikacji po stronie serwera, w której klucz może być przechowywany w poufności.

• Używaj tokenów tymczasowych do uzyskiwania dostępu po stronie klienta (tylko interfejs Live API): w przypadku bezpośredniego dostępu do interfejsu Live API po stronie klienta możesz używać tokenów tymczasowych. Są one mniej ryzykowne pod względem bezpieczeństwa i mogą być odpowiednie do użytku produkcyjnego. 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.