Interactions API

Interfejs API Interactions to nasz nowy interfejs i najprostszy sposób na tworzenie aplikacji z modelami i agentami Gemini. Od czerwca 2026 r. jest on ogólnie dostępny i zalecany w przypadku wszystkich nowych projektów.

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?

  • Nowe funkcje od razu po wyjęciu z pudełka: 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 wskaźnikom trafień w pamięci podręcznej: zarządzanie stanem po stronie serwera umożliwia wydajniejsze buforowanie kontekstu w kolejnych turach, co obniża koszty tokenów w przypadku rozmów wieloetapowych.
  • Stworzona z myślą o najnowocześniejszych modelach i agentach: zaprojektowana specjalnie z myślą o modelach myślenia, wieloetapowym korzystaniu z narzędzi i złożonych procesach rozumowania, co upraszcza proces tworzenia, debugowania i koordynowania aplikacji agentowych.
  • Jeden interfejs API dla modeli i agentów: jeden ujednolicony interfejs do bezpośredniego wywoływania modeli i agentów Gemini, takich jak Deep Research i niestandardowi zarządzani agenci – nie musisz poznawać osobnych punktów końcowych ani wzorców.
  • Miejsce wprowadzania nowości: nowe modele i funkcje wykraczające poza podstawową rodzinę modeli, a także nowe funkcje i narzędzia 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ć 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 rozmów, 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 w każdym żądaniu pełną historię rozmowy.

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), wykonywania w tle (za pomocą background=true) i obserwacji.

  • Wersja płatna: system przechowuje interakcje przez 55 dni.
  • Poziom bezpłatny: 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 background=true i uniemożliwia używanie previous_interaction_id w kolejnych turach.

Zapisane interakcje możesz w każdej chwili usunąć za pomocą metody usuwania opisanej w dokumentacji interfejsu API. Interakcje możesz usuwać tylko wtedy, gdy znasz ich identyfikator.

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

System przetwarza obiekty Interaction zgodnie z warunkami.

Sprawdzone metody

  • Współczynnik trafień w pamięci podręcznej: używanie symbolu previous_interaction_id do kontynuowania rozmów ułatwia systemowi korzystanie z niejawnego buforowania historii rozmów, co zwiększa wydajność i obniża koszty.
  • Miksowanie interakcji: możesz miksować i dopasowywać 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ą znaku previous_interaction_id.

Obsługiwane modele i agenci

Nazwa modelu Typ Identyfikator modelu
Gemini 3.1 Flash-Lite Model gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite (wersja testowa) Model gemini-3.1-flash-lite-preview
Gemini 3.1 Pro (wersja testowa) Model gemini-3.1-pro-preview
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
Podgląd klipu Lyria 3 Model lyria-3-clip-preview
Lyria 3 Pro (wersja testowa) Model lyria-3-pro-preview
Podgląd Deep Research Agent deep-research-pro-preview-12-2025
Podgląd Deep Research Agent deep-research-preview-04-2026
Podgląd Deep Research Agent deep-research-max-preview-04-2026
Podgląd Antigravity Agent antigravity-preview-05-2026

Pakiety SDK

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

  • W przypadku Pythona jest to pakiet google-genai od wersji 1.55.0.
  • W przypadku JavaScriptu jest to pakiet @google/genai od wersji 1.33.0.

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.

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?