Korzystanie z kluczy interfejsu Gemini API

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

Tworzenie lub wyświetlanie klucza interfejsu Gemini API

Klucze interfejsu API

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

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

• Ustawienie klucza interfejsu API jako zmiennej środowiskowej
• Podanie klucza interfejsu API w sposób jawny

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 kodowania klucza interfejsu API na stałe znajdziesz w sekcji Podawanie klucza interfejsu API w sposób jawny.

Projekty Google Cloud

Projekty Google Cloud są podstawą 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 wyświetlą się wszystkie klucze, które mają wystarczające uprawnienia do korzystania z interfejsu Gemini API. Instrukcje znajdziesz w sekcji Importowanie projektów.

Projekt domyślny

Nowym użytkownikom, którzy zaakceptują Warunki korzystania z usługi, Google AI Studio utworzy domyślny projekt Google Cloud i klucz interfejsu API, aby ułatwić korzystanie z usługi. Możesz zmienić nazwę tego projektu w Google AI Studio. W tym celu otwórz widok Projekty w Panelu, kliknij przycisk ustawień (3 kropki) obok projektu i wybierz Zmień nazwę projektu. Użytkownicy, którzy już mają konta Google Cloud, nie będą mieli utworzonego projektu domyślnego.

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 projektów Cloud. Musisz zaimportować projekty, które chcesz używać. W tym celu wyszukaj 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, 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 projekcie, który został właśnie zaimportowany.

Ograniczenia

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

• Na stronie Projekty w Google AI Studio możesz utworzyć maksymalnie 10 projektów naraz.
• Możesz nadawać nazwy projektom i kluczom oraz zmieniać ich nazwy.
• 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 do modyfikowania i ograniczania kluczy interfejsu API, otwórz stronę danych logowania w konsoli Google Cloud. W Cloud Console 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 Gemini API. Zalecamy ustawienie tylko jednej z tych zmiennych, ale jeśli ustawisz obie, pierwszeństwo będzie mieć zmienna GOOGLE_API_KEY.

Jeśli używasz interfejsu REST API lub JavaScript w przeglądarce, musisz podać klucz interfejsu API w sposób jawny.

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

Podawanie klucza interfejsu API w sposób jawny

W niektórych przypadkach możesz chcieć podać klucz interfejsu API w sposób jawny. 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 chcesz polegać na automatycznym wykrywaniu zmiennych środowiskowych przez biblioteki Gemini API.
• Używasz środowiska, w którym zmienne środowiskowe nie są obsługiwane (np.w internecie), lub wykonujesz wywołania REST.

Poniżej znajdziesz przykłady podawania klucza interfejsu API w sposób jawny za pomocą interfejsu Interactions API:

from google import genai

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

interaction = client.interactions.create(
    model="gemini-3-flash-preview", 
    input="Explain how AI works in a few words"
)
print(interaction.steps[-1].content[0].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-flash-preview",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

main();

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-flash-preview",
    "input": "Explain how AI works in a few words"
  }'

Zabezpieczanie klucza interfejsu API

Traktuj klucz interfejsu Gemini API jak hasło. Jeśli klucz zostanie naruszony, inne osoby mogą wykorzystać limit Twojego projektu, naliczać opłaty (jeśli włączone są płatności) i uzyskiwać dostęp do Twoich danych prywatnych, np. plików.

Krytyczne reguły bezpieczeństwa

• Zachowaj klucze w tajemnicy: klucze interfejsu Gemini API mogą uzyskiwać dostęp do poufnych danych, od których zależy Twoja aplikacja.

  • Nigdy nie przesyłaj kluczy interfejsu API do kontroli źródła. 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 ani mobilnych w środowisku produkcyjnym. Klucze w kodzie po stronie klienta (w tym w naszych bibliotekach JavaScript/TypeScript i wywołaniach REST) można wyodrębnić.

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

• Ogranicz użycie: włączaj tylko te interfejsy API, które są niezbędne 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ć przechowywany w tajemnicy.

• Używaj tymczasowych tokenów do uzyskiwania dostępu po stronie klienta (tylko w przypadku interfejsu Live API): w przypadku bezpośredniego dostępu po stronie klienta do interfejsu Live API możesz używać tymczasowych tokenów. Są one mniej narażone na zagrożenia bezpieczeństwa i mogą być używane w środowisku produkcyjnym. Więcej informacji znajdziesz w przewodniku po tymczasowych tokenach.

• Rozważ dodanie ograniczeń do klucza: możesz ograniczyć uprawnienia klucza dodając ograniczenia klucza interfejsu API. Zminimalizuje 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, a obok niego może się 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 sprawdzenie, czy projekt istnieje.
• apikeys.keys.create: umożliwia wygenerowanie samego klucza interfejsu API.
• serviceusage.services.enable: wymagane, aby interfejs Gemini API był aktywny w projekcie.

Aby naprawić uprawnienia, poproś administratora projektu lub administratora organizacji (jeśli projekt należy do organizacji) o przyznanie 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.