Gemini API reference

Ten dokument referencyjny interfejsu API opisuje standardowe interfejsy API, interfejsy API do przesyłania strumieniowego i interfejsy API w czasie rzeczywistym, których możesz używać do interakcji z modelami Gemini. Interfejsów API REST możesz używać w dowolnym środowisku, które obsługuje żądania HTTP. Informacje o tym, jak wykonać pierwsze wywołanie interfejsu API, znajdziesz w przewodniku dla początkujących. Jeśli szukasz informacji o bibliotekach i pakietach SDK w określonych językach, kliknij link do danego języka w menu po lewej stronie w sekcji Dokumentacja pakietu SDK.

Podstawowe punkty końcowe

Interfejs Gemini API jest zorganizowany wokół tych głównych punktów końcowych:

  • Standardowe generowanie treści (generateContent): standardowy punkt końcowy REST, który przetwarza Twoje żądanie i zwraca pełną odpowiedź modelu w jednym pakiecie. Ta opcja najlepiej sprawdza się w przypadku zadań nieinteraktywnych, w których możesz poczekać na cały wynik.
  • Generowanie treści strumieniowych (streamGenerateContent): wykorzystuje zdarzenia wysyłane przez serwer (SSE) do przesyłania do Ciebie fragmentów odpowiedzi w miarę ich generowania. Zapewnia to szybsze i bardziej interaktywne działanie aplikacji, takich jak chatboty.
  • Live API (BidiGenerateContent): interfejs API oparty na protokole WebSocket z zachowywaniem stanu, przeznaczony do dwukierunkowego przesyłania strumieniowego i używania w przypadkach związanych z rozmowami w czasie rzeczywistym.
  • Tryb wsadowy (batchGenerateContent): standardowy punkt końcowy REST do przesyłania partii generateContent żądań.
  • Wektory dystrybucyjne (embedContent): standardowy punkt końcowy REST, który generuje wektor dystrybucyjny tekstu na podstawie danych wejściowych Content.
  • Interfejsy Gen Media API: punkty końcowe do generowania multimediów za pomocą naszych specjalistycznych modeli, takich jak Imagen do generowania obrazów i Veo do generowania filmów. Gemini ma też wbudowane te funkcje, do których możesz uzyskać dostęp za pomocą interfejsu generateContent API.
  • Interfejsy API platformy: punkty końcowe narzędziowe, które obsługują podstawowe funkcje, takie jak przesyłanie plików i zliczanie tokenów.

Uwierzytelnianie

Wszystkie żądania wysyłane do interfejsu Gemini API muszą zawierać nagłówek x-goog-api-key z kluczem API. Utwórz go kilkoma kliknięciami w Google AI Studio.

Oto przykładowe żądanie z kluczem interfejsu API w nagłówku:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Instrukcje przekazywania klucza do interfejsu API za pomocą pakietów SDK Gemini znajdziesz w przewodniku Korzystanie z kluczy interfejsu Gemini API.

Generowanie treści

Jest to centralny punkt końcowy do wysyłania promptów do modelu. Istnieją 2 punkty końcowe do generowania treści. Różnią się one sposobem otrzymywania odpowiedzi:

  • generateContent (REST): Otrzymuje żądanie i po zakończeniu generowania przez model całej odpowiedzi zwraca pojedynczą odpowiedź.
  • streamGenerateContent (SSE): otrzymuje dokładnie to samo żądanie, ale model przesyła strumieniowo fragmenty odpowiedzi w miarę ich generowania. Zapewnia to lepsze wrażenia użytkownikom aplikacji interaktywnych, ponieważ umożliwia natychmiastowe wyświetlanie częściowych wyników.

Struktura treści żądania

Treść żądania to obiekt JSON, który jest identyczny w przypadku trybu standardowego i strumieniowego. Składa się z kilku podstawowych obiektów:

Na najwyższym poziomie treść żądania zawiera obiekt contents, który jest listą obiektów Content. Każdy z nich reprezentuje turę w rozmowie. W większości przypadków w przypadku podstawowego generowania tekstu będziesz mieć jeden obiekt Content, ale jeśli chcesz zachować historię rozmowy, możesz użyć wielu obiektów Content.

Poniżej przedstawiono typową treść żądania generateContent:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

Struktura treści odpowiedzi

Treść odpowiedzi jest podobna w przypadku obu trybów (strumieniowego i standardowego), z wyjątkiem tych różnic:

Na najwyższym poziomie treść odpowiedzi zawiera obiekt candidates, który jest listą obiektów Candidate. Obiekt Candidate zawiera obiekt Content, który ma wygenerowaną odpowiedź zwróconą przez model.

Przykłady żądań

Poniższe przykłady pokazują, jak te komponenty działają w przypadku różnych typów żądań.

Prompt tekstowy

Prosty prompt tekstowy składa się z tablicy contents zawierającej pojedynczy obiekt Content. Tablica parts tego obiektu zawiera z kolei pojedynczy obiekt Part z polem text.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

Prompt multimodalny (tekst i obraz)

Aby podać w prompcie zarówno tekst, jak i obraz, tablica parts powinna zawierać 2 obiekty Part: jeden dla tekstu i jeden dla obrazu inline_data.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

Rozmowy wieloetapowe (czat)

Aby utworzyć rozmowę z wieloma turami, zdefiniuj tablicę contents z wieloma obiektami Content. Interfejs API użyje całej tej historii jako kontekstu dla następnej odpowiedzi. Wartość role dla każdego obiektu Content powinna być na przemian równa user i model.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

Najważniejsze punkty

  • Content to koperta: jest to kontener najwyższego poziomu dla tury wiadomości, niezależnie od tego, czy pochodzi ona od użytkownika, czy od modelu.
  • Part umożliwia wielomodalność: używaj wielu obiektów Part w ramach jednego obiektu Content, aby łączyć różne typy danych (tekst, obraz, identyfikator URI filmu itp.).
  • Wybierz metodę danych:
    • W przypadku małych mediów osadzonych bezpośrednio (takich jak większość obrazów) użyj elementu Part z atrybutem inline_data.
    • W przypadku większych plików lub plików, których chcesz używać w wielu żądaniach, użyj interfejsu File API, aby przesłać plik i odwołać się do niego za pomocą części file_data.
  • Zarządzanie historią rozmów: w przypadku aplikacji do czatowania korzystających z interfejsu API REST utwórz tablicę contents, dodając do niej obiekty Content dla każdej tury, na przemian z rolami "user" i "model". Jeśli używasz pakietu SDK, zapoznaj się z jego dokumentacją, aby dowiedzieć się, jak zarządzać historią rozmów.

Przykłady odpowiedzi

Poniższe przykłady pokazują, jak te komponenty działają w przypadku różnych typów żądań.

Odpowiedź tekstowa

Prosta odpowiedź tekstowa składa się z tablicy candidates zawierającej co najmniej 1 obiekt content z odpowiedzią modelu.

Oto przykład standardowej odpowiedzi:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

Poniżej znajdziesz serię odpowiedzi strumieniowych. Każda odpowiedź zawiera responseId, który łączy całą odpowiedź:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets API

Interfejs Live API to stanowy interfejs API oparty na protokole WebSocket, który umożliwia dwukierunkowe strumieniowanie i realizację przypadków użycia strumieniowania w czasie rzeczywistym. Więcej informacji znajdziesz w przewodniku po interfejsie Live API i dokumentacji interfejsu Live API.

Modele specjalizowane

Oprócz modeli z rodziny Gemini interfejs Gemini API oferuje punkty końcowe dla modeli specjalistycznych, takich jak Imagen, Lyria i modele embeddingu. Możesz zapoznać się z tymi przewodnikami w sekcji Modele.

Interfejsy API platformy

Pozostałe punkty końcowe umożliwiają korzystanie z dodatkowych funkcji w połączeniu z opisanymi do tej pory głównymi punktami końcowymi. Więcej informacji znajdziesz w sekcji Przewodniki w tematach Tryb wsadowy i Interfejs File API.

Co dalej?

Jeśli dopiero zaczynasz, zapoznaj się z tymi przewodnikami, które pomogą Ci zrozumieć model programowania interfejsu Gemini API:

Możesz też zapoznać się z przewodnikami po funkcjach, które przedstawiają różne funkcje interfejsu Gemini API i zawierają przykłady kodu: