Interactions API

Interactions API to najlepszy sposób na tworzenie aplikacji z wykorzystaniem modeli i agentów Gemini. Od czerwca 2026 r. jest ogólnie dostępna i zalecana we wszystkich nowych projektach. Chociaż jest on obecnie uważany za starszy, oryginalny interfejs generateContent API jest nadal w pełni obsługiwany.

Dlaczego warto korzystać z interfejsu Interactions API?

  • Uniwersalny interfejs dla wszystkich aplikacji: zaprojektowany jako standardowy interfejs dla każdego przypadku użycia, w tym generowania tekstu w jednej turze, rozpoznawania multimodalnego, danych wyjściowych o strukturze, orkiestracji narzędzi i przepływów pracy agenta.
  • Jeden interfejs API dla modeli i agentów: jeden ujednolicony punkt końcowy i wzorzec do bezpośredniego wywoływania standardowych modeli Gemini oraz wyspecjalizowanych agentów (takich jak Deep Research i niestandardowi agenci zarządzani).
  • Nowe funkcje od razu po wyjęciu z pudełka: funkcje takie jak opcjonalny stan konwersacji po stronie serwera za pomocą previous_interaction_id, widoczne kroki wykonywania do debugowania i renderowania interfejsu oraz wykonywanie w tle długotrwałych zadań za pomocą background=true.
  • Niższe koszty dzięki wyższym współczynnikom trafień w pamięci podręcznej: w przypadku rozmów wieloetapowych opcjonalne zarządzanie stanem po stronie serwera umożliwia wydajniejsze buforowanie kontekstu między etapami, co zmniejsza koszty tokenów.
  • Miejsce wprowadzania nowych funkcji: wszystkie nowe modele, funkcje multimodalne, narzędzia i funkcje oparte na agentach będą od teraz wprowadzane w interfejsie Interactions API.

Domyślnie interfejs Interactions API przechowuje żądania, dzięki czemu możesz korzystać z funkcji zarządzania stanem po stronie serwera za pomocą previous_interaction_id. Możesz włączyć działanie bezstanowe, ustawiając store=false. Więcej informacji znajdziesz w sekcji Przechowywanie danych.

Rozpocznij

Przewodniki po funkcjach

Z tych przewodników dowiesz się więcej o konkretnych możliwościach interfejsu Interactions API. Na tych stronach możesz przełączać się między interfejsami generateContent i Interactions API za pomocą przełącznika:

Jak działa interfejs Interactions API

Interfejs API interakcji opiera się na podstawowym zasobie: Interaction. Symbol Interaction oznacza pełną turę w rozmowie lub zadaniu. Działa on jak zapis sesji, zawierający całą historię interakcji w postaci chronologicznej sekwencji kroków wykonania. Obejmują one przemyślenia modelu, wywołania narzędzi po stronie serwera lub klienta i wyniki (np. function_call i function_result) oraz ostateczną model_output. Zapisany zasób (pobrany za pomocą interactions.get) zawiera też user_input kroki, które zapewniają pełny kontekst, ale odpowiedź interactions.create zawiera tylko kroki wygenerowane przez model.

Gdy dzwonisz na numer interactions.create, tworzysz nowy zasób Interaction.

Zarządzanie stanem po stronie serwera

W kolejnym wywołaniu możesz użyć id zakończonej interakcji, korzystając z parametru previous_interaction_id, aby kontynuować rozmowę. Serwer używa tego identyfikatora do pobierania historii rozmowy, dzięki czemu nie musisz ponownie wysyłać całej historii czatu.

Parametr previous_interaction_id zachowuje tylko historię rozmowy (dane wejściowe i wyjściowe) za pomocą previous_interaction_id. Pozostałe parametry mają zakres interakcji i mają zastosowanie tylko do konkretnej interakcji, którą obecnie generujesz:

  • tools
  • system_instruction
  • generation_config (w tym thinking_level, temperature itp.)

Oznacza to, że jeśli chcesz, aby te parametry były stosowane, musisz ponownie określić je w każdej nowej interakcji. Zarządzanie stanem po stronie serwera jest opcjonalne. Możesz też działać w trybie bezstanowym, wysyłając pełną historię rozmowy w każdym żądaniu.

Przechowywanie danych

Domyślnie interfejs API przechowuje wszystkie obiekty Interaction (store=true), aby uprościć korzystanie z funkcji zarządzania stanem po stronie serwera (z previous_interaction_id), wykonania w tle (za pomocą background=true) i dostrzegalności.

  • Wersja płatna: system przechowuje interakcje przez 55 dni.
  • Bezpłatna wersja: system przechowuje interakcje przez 1 dzień.

Jeśli nie chcesz, aby tak się stało, możesz w swojej prośbie ustawić store=false. Ta kontrola jest niezależna od zarządzania stanem. Możesz zrezygnować z przechowywania danych w przypadku dowolnej interakcji. Pamiętaj jednak, że store=false jest niezgodny z wykonywaniem w tle i uniemożliwia używanie previous_interaction_id w kolejnych turach.

W przypadku projektów w wersji płatnej możesz skonfigurować okres przechowywania w AI Studio, aby automatycznie oznaczać logi do usunięcia z pamięci projektu po 7, 14, 28 lub 55 dniach. Krótszy okres przechowywania może wpłynąć na możliwość odzyskania wcześniejszych rozmów.

Zapisane interakcje możesz w każdej chwili usunąć programowo za pomocą metody delete, która wymaga identyfikatora interakcji. W AI Studio możesz też wyświetlać dzienniki zapisanych interakcji i nimi zarządzać, w tym usuwać je z pamięci projektu.

Po wygaśnięciu okresu przechowywania Twoje dane zostaną automatycznie usunięte.

Obiekty interakcji są przetwarzane zgodnie z warunkami.

Wyświetlanie interakcji w AI Studio

Interfejs API przechowuje żądania interfejsu Interactions API wykonane za pomocą store=true w przypadku projektów na poziomie płatnym. Możesz je wyświetlić bezpośrednio na stronie dzienników w Google AI Studio. Więcej informacji znajdziesz w przewodniku po logach.

Sprawdzone metody

  • Współczynnik trafień w pamięci podręcznej: automatyczne buforowanie jest obsługiwane w trybie stanowym i bezstanowym (patrz Szybki start). Używanie previous_interaction_id (stanowego) do kontynuowania rozmów umożliwia systemowi łatwiejsze korzystanie z niejawnego buforowania historii rozmów, co zwiększa wydajność i obniża koszty.
  • Mieszanie interakcji: możesz mieszać interakcje z agentem i modelem w ramach jednej rozmowy. Możesz na przykład użyć specjalistycznego agenta, takiego jak agent Deep Research, do wstępnego zbierania danych, a następnie użyć standardowego modelu Gemini do wykonywania kolejnych zadań, takich jak podsumowywanie lub formatowanie, łącząc te kroki za pomocą funkcji previous_interaction_id.

Obsługiwane modele i agenci

Nazwa modelu Typ Identyfikator modelu
Gemini 3.8 Flash Model gemini-3.8-flash
Gemini 3.7 Flash Model gemini-3.7-flash
Gemini 3.6 Flash Model gemini-3.6-flash
Gemini 3.5 Flash Model gemini-3.5-flash
Gemini 3.1 Pro (wersja testowa) Model gemini-3.1-pro-preview
Gemini 3.5 Flash-Lite Model gemini-3.5-flash-lite
Gemini 3.1 Flash-Lite Model gemini-3.1-flash-lite
Gemini 3 Flash (wersja testowa) Model gemini-3-flash-preview
Gemini 2.5 Pro Model gemini-2.5-pro
Gemini 2.5 Flash Model gemini-2.5-flash
Gemini 2.5 Flash-Lite Model gemini-2.5-flash-lite
Gemini 3 Pro Image Model gemini-3-pro-image
Gemini 3.1 Flash Image Model gemini-3.1-flash-image
Gemini 3.1 Flash TTS (wersja testowa) Model gemini-3.1-flash-tts-preview
Gemma 4 31B IT Model gemma-4-31b-it
Gemma 4 26B MoE IT Model gemma-4-26b-a4b-it
Lyria 3.5 Model lyria-3.5
Podgląd klipu Lyria 3 Model lyria-3-clip-preview
Lyria 3 Pro (wersja testowa) Model lyria-3-pro-preview
Wersja testowa Deep Research Agent deep-research-preview-04-2026
Wersja testowa Deep Research Agent deep-research-max-preview-04-2026
Podgląd Antigravity Agent antigravity-preview-09-2026

Pakiety SDK

Aby uzyskać dostęp do interfejsu API interakcji, możesz użyć najnowszej wersji pakietów SDK Google GenAI.

  • W Pythonie jest to pakiet google-genai od wersji 2.3.0.
  • W przypadku JavaScriptu jest to pakiet @google/genai od wersji 2.3.0.

Więcej informacji o instalowaniu pakietów SDK znajdziesz na stronie Biblioteki.

Ograniczenia

  • Remote MCP: Gemini 3 nie obsługuje zdalnego MCP. Ta funkcja będzie dostępna wkrótce.
  • Zgodność modelu wieloetapowego: w przypadku łączenia różnych modeli w rozmowie (stanowej lub bezstanowej) kolejne modele muszą obsługiwać tryby wyjściowe poprzednich modeli jako dane wejściowe. Jeśli na przykład wygenerujesz obraz za pomocą gemini-3.1-flash-image, nie możesz kontynuować tej rozmowy z modelem, który nie akceptuje danych wejściowych w postaci obrazu (np. z modelem obsługującym tylko tekst lub z modelem do generowania muzyki, takim jak Lyria).

Te funkcje są obsługiwane przez interfejs API generateContent, ale nie są jeszcze dostępne w interfejsie API interakcji:

Prześlij opinię

Twoja opinia jest kluczowa dla rozwoju interfejsu API do interakcji. Podziel się swoimi przemyśleniami, zgłoś błędy lub poproś o funkcje na naszym forum społeczności deweloperów Google AI.

Co dalej?