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.

Klucze API

Klucz interfejsu API to zaszyfrowany ciąg znaków, którego możesz używać do wywoływania interfejsów API Google Cloud. Wszystkie klucze interfejsu Gemini API możesz tworzyć i nimi zarządzać na stronie Klucze interfejsu API w Google AI Studio.

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.

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 Google Cloud. Musisz zaimportować wybrane projekty, wyszukując ich nazwę lub identyfikator 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 na panelu po lewej stronie.
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 interfejsu API w menu Panel i utwórz klucz interfejsu API w zaimportowanym projekcie.

Ograniczenia

Poniżej znajdziesz ograniczenia dotyczące zarządzania kluczami interfejsu 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 100 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, otwórz Google Cloud Console.

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, zmienna GOOGLE_API_KEY będzie miała pierwszeństwo.

Jeśli używasz interfejsu REST API lub JavaScript 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ę i nie polegać 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-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"
          }
        ]
      }
    ]
  }'

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ń

• 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 interfejsu API bezpośrednio w aplikacjach internetowych lub mobilnych w wersji produkcyjnej. Klucze w kodzie po stronie klienta (w tym w naszych bibliotekach JavaScript/TypeScript i wywołaniach REST) mogą zostać wyodrębnione.

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ć poufny.

• 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ć 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.