Gemini API reference

Ta dokumentacja interfejsu API opisuje standardowe, strumieniowe i działające w czasie rzeczywistym interfejsy API, których możesz używać do interakcji z modelami Gemini. Możesz używać interfejsów API REST w dowolnym środowisku obsługującym żądania HTTP. Więcej informacji o tym, jak rozpocząć pierwsze wywołanie interfejsu API, znajdziesz w przewodniku Krótkie wprowadzenie. Jeśli szukasz materiałów referencyjnych dotyczących naszych bibliotek i pakietów SDK w konkretnych językach, kliknij link do danego języka w menu po lewej stronie w sekcji Materiały referencyjne pakietu SDK.

Podstawowe punkty końcowe

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

  • Interakcje (CreateInteraction) (zalecane): zalecany standardowy element pierwotny do tworzenia aplikacji z Gemini, zoptymalizowany pod kątem przepływów pracy agenta, zarządzania stanem po stronie serwera oraz złożonych rozmów wielomodalnych, wieloetapowych.
  • Standardowe generowanie treści (generateContent): standardowy punkt końcowy REST, który przetwarza Twoje żądanie i zwraca pełną odpowiedź modelu w jednym pakiecie. Najlepiej sprawdza się w przypadku zadań nieinteraktywnych, w których możesz poczekać na cały wynik.
  • Strumieniowe generowanie treści (streamGenerateContent): używa zdarzeń wysyłanych przez serwer (SSE), aby przesyłać do Ciebie fragmenty odpowiedzi w miarę ich generowania. Zapewnia to szybsze i bardziej interaktywne działanie aplikacji, takich jak chatboty.
  • Interfejs Live API (BidiGenerateContent): interfejs API oparty na protokole WebSocket z obsługą stanu do strumieniowania dwukierunkowego, przeznaczony do zastosowań konwersacyjnych w czasie rzeczywistym.
  • Tryb wsadowy (batchGenerateContent): standardowy punkt końcowy REST do przesyłania partii żądań generateContent.
  • Osadzanie (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 modeli specjalistycznych , takich jak Imagen do generowania obrazów i Veo do generowania filmów. Gemini ma też wbudowane te możliwości, do których możesz uzyskać dostęp za pomocą interfejsu generateContent API.
  • Interfejsy Platform API: punkty końcowe narzędziowe, które obsługują podstawowe funkcje, takie jak przesyłanie plików i zliczanie tokenów.

Uwierzytelnianie

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

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.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 dotyczące 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, a główna różnica polega na sposobie otrzymywania odpowiedzi:

  • generateContent (REST): odbiera żądanie i po zakończeniu generowania przez model zwraca pojedynczą odpowiedź.
  • streamGenerateContent (SSE): odbiera dokładnie to samo żądanie, ale model przesyła strumieniowo fragmenty odpowiedzi w miarę ich generowania. Zapewnia to lepsze wrażenia użytkownika w przypadku 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 i jest tworzony na podstawie kilku podstawowych obiektów:

  • Content obiekt: reprezentuje pojedynczą turę w rozmowie.
  • Part obiekt: fragment danych w turze Content (np. tekst lub obraz).
  • inline_data (Blob): kontener na surowe bajty multimediów i ich typ MIME.

Na najwyższym poziomie treść żądania zawiera obiekt contents, który jest listą obiektów Content, z których każdy 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-3.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 trybie strumieniowym i standardowym, z wyjątkiem tych różnic:

Na wysokim poziomie treść odpowiedzi zawiera obiekt candidates, który jest listą obiektów Candidate. Obiekt Candidate zawiera obiekt Content z wygenerowaną odpowiedzią zwróconą przez model.

Przykłady żądań

Z przykładów poniżej dowiesz się, jak te komponenty współpracują ze sobą w przypadku różnych typów żądań.

Prompt zawierający tylko tekst

Prosty prompt tekstowy składa się z tablicy contents z jednym obiektem Content. Tablica parts tego obiektu zawiera z kolei jeden obiekt Part z polem text.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.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 w prompcie podać zarówno tekst, jak i obraz, tablica parts powinna zawierać 2 obiekty Part: jeden na tekst, a drugi na inline_data obrazu.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.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ę wieloetapową, zdefiniuj tablicę contents z wieloma obiektami Content. Interfejs API użyje całej tej historii jako kontekstu do następnej odpowiedzi. W przypadku każdego obiektu Content wartość role powinna się zmieniać między user a model.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.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 multimodalność: użyj wielu obiektów Part w jednym obiekcie Content, aby połączyć różne typy danych (tekst, obraz, adres URI filmu itp.).
  • Wybierz metodę danych:
    • W przypadku małych, bezpośrednio osadzonych multimediów (takich jak większość obrazów) użyj elementu Part z elementem inline_data.
    • W przypadku większych plików lub plików, których chcesz używać ponownie w różnych żądaniach, użyj interfejsu File API, aby przesłać plik, i odwołaj się do niego za pomocą elementu file_data.
  • Zarządzaj historią rozmowy: w przypadku aplikacji czatu korzystających z interfejsu API REST utwórz tablicę contents, dodając Content obiekty 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ą rozmowy.

Przykłady odpowiedzi

Z przykładów poniżej dowiesz się, jak te komponenty współpracują ze sobą w przypadku różnych typów żądań.

Odpowiedź zawierająca tylko tekst

Domyślna odpowiedź tekstowa składa się z tablicy candidates z co najmniej 1 obiektem content, który zawiera odpowiedź 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 element responseId, który łączy całą odpowiedź:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-3.5-flash",
  "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-3.5-flash",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Interfejs Live API (BidiGenerateContent) WebSockets API

Interfejs Live API udostępnia interfejs API oparty na protokole WebSocket z obsługą stanu do strumieniowania dwukierunkowego, co umożliwia korzystanie ze strumieniowania w czasie rzeczywistym. Więcej informacji znajdziesz w przewodniku po interfejsie Live API i w dokumentacji interfejsu Live API.

Modele specjalizowane

Oprócz rodziny modeli Gemini interfejs Gemini API udostępnia punkty końcowe dla modeli specjalistycznych, takich jak Imagen, Lyria i modele osadzania. Te przewodniki znajdziesz w sekcji Modele.

Interfejsy Platform API

Pozostałe punkty końcowe umożliwiają korzystanie z dodatkowych funkcji z głównymi punktami końcowymi opisanymi do tej pory. Więcej informacji znajdziesz w sekcji Przewodniki w artykułach Tryb wsadowy i 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: