Interactions API

Interfejs Interactions API to najlepszy sposób na tworzenie aplikacji z wykorzystaniem modeli i agentów Gemini. Od czerwca 2026 r. jest on ogólnie dostępny i zalecany w przypadku wszystkich nowych projektów. Chociaż jest on teraz uważany za starszy, oryginalny generateContent interfejs 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, uporządkowanych danych wyjściowych, orkiestracji narzędzi i przepływów pracy agenta.
  • Pojedynczy 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 rozmowy po stronie serwera za pomocą previous_interaction_id, widoczne kroki wykonania 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 w kolejnych turach, co zmniejsza koszty tokenów.
  • Miejsce, w którym wprowadzane są nowe funkcje: w przyszłości wszystkie nowe modele, funkcje multimodalne , narzędzia i funkcje agenta będą 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ć zachowanie bezstanowe, ustawiając store=false. Więcej informacji znajdziesz w sekcji Przechowywanie danych szczegółów.

Rozpocznij

  • Skonfiguruj agenta kodowania: połącz się z Gemini Docs MCP i zainstaluj umiejętność gemini-api-dev, aby zapewnić asystentowi bezpośredni dostęp do najnowszej dokumentacji dla deweloperów i sprawdzonych metod. Szczegółowe instrukcje znajdziesz w przewodniku Konfigurowanie agenta kodowania.
  • Migracja z generateContent: jeśli masz już integrację, postępuj zgodnie z instrukcjami w przewodniku Migracja, aby przejść na interfejs Interactions API.
  • Rozpocznij: wykonaj czynności opisane w przewodniku Rozpoczęcie korzystania z interfejsu Interactions API guide.

Przewodniki po funkcjach

W tych przewodnikach znajdziesz informacje o konkretnych funkcjach interfejsu Interactions API. Możesz użyć przełącznika na tych stronach, aby przełączać się między interfejsami generateContent i Interactions API:

Jak działa interfejs Interactions API

Interfejs Interactions API opiera się na podstawowym zasobie: Interaction. Interaction reprezentuje pełną turę w rozmowie lub zadaniu. Działa jako rekord sesji, który zawiera całą historię interakcji jako chronologiczną sekwencję kroków wykonania. Te kroki obejmują myśli modelu, wywołania narzędzi po stronie serwera lub klienta i wyniki (np. function_call i function_result) oraz końcowe model_output. Przechowywany zasób (pobierany za pomocą interactions.get) zawiera też kroki user_input dla pełnego kontekstu, chociaż odpowiedź interactions.create zwraca tylko kroki wygenerowane przez model.

Gdy wywołujesz interactions.create, tworzysz nowy zasób Interaction.

Zarządzanie stanem po stronie serwera

Możesz użyć id zakończonej interakcji w kolejnym wywołaniu za pomocą previous_interaction_id parametru, 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 są zakresowe i dotyczą tylko 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 je ponownie określić 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 (za pomocą previous_interaction_id), wykonywania w tle (za pomocą background=true) i dostrzegalności.

  • Płatny poziom: system przechowuje interakcje przez 55 dni.
  • Bezpłatny poziom: system przechowuje interakcje przez 1 dzień.

Jeśli nie chcesz tego robić, możesz ustawić store=false w żądaniu. Ta opcja jest niezależna od zarządzania stanem. Możesz zrezygnować z przechowywania dowolnej interakcji. Pamiętaj jednak, że store=false jest niezgodne z wykonywaniem w tle i uniemożliwia używanie previous_interaction_id w kolejnych turach.

W przypadku projektów na płatnym poziomie 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 pobieranie wcześniejszych rozmów.

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

Po upływie okresu przechowywania Twoje dane zostaną automatycznie usunięte.

Obiekty Interactions są przetwarzane zgodnie z warunkami.

Wyświetlanie interakcji w AI Studio

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

Sprawdzone metody

  • Współczynnik trafień w pamięci podręcznej: buforowanie niejawne jest obsługiwane w trybie stanowym i bezstanowym (patrz Szybki start). Używanie previous_interaction_id (stanowe) do kontynuowania rozmów umożliwia systemowi łatwiejsze korzystanie z buforowania niejawnego w historii rozmowy, co zwiększa wydajność i obniża koszty.
  • Łączenie interli: możesz dowolnie łączyć interakcje agenta i modelu w ramach rozmowy. Na przykład możesz użyć wyspecjalizowanego 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ą 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
Lyria 3 Clip (wersja testowa) Model lyria-3-clip-preview
Lyria 3 Pro (wersja testowa) Model lyria-3-pro-preview
Deep Research (wersja testowa) Agent deep-research-preview-04-2026
Deep Research (wersja testowa) Agent deep-research-max-preview-04-2026
Antigravity (wersja testowa) Agent antigravity-preview-05-2026

Pakiety SDK

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

  • W Pythonie jest to pakiet google-genai w wersji 2.3.0 lub nowszej.
  • W JavaScript jest to pakiet @google/genai w wersji 2.3.0 lub nowszej.

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

Ograniczenia

  • Zdalny 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ć dane 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 obrazu (np. z modelem tylko tekstowym lub modelem generowania muzyki, takim jak Lyria).

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

Prześlij opinię

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

Co dalej?