Przechodzenie na interfejs Interactions API

Ten przewodnik pomoże Ci przejść z interfejsu generateContent API na interfejs Interactions API.

Interactions API to najprostszy i najlepszy sposób na tworzenie aplikacji z wykorzystaniem modeli i agentów Gemini. Chociaż interfejs generateContent jest w dalszym ciągu w pełni obsługiwany, w przypadku wszystkich nowych projektów zalecamy korzystanie z interfejsu Interactions API.

Dlaczego warto przeprowadzić migrację?

Interfejs Interactions API to najprostszy i najlepszy sposób na tworzenie aplikacji z wykorzystaniem modeli i agentów Gemini:

  • Zarządzanie historią po stronie serwera: uproszczone przepływy wieloetapowe za pomocą previous_interaction_id. Serwer domyślnie włącza stan (store=true), ale możesz włączyć zachowanie bezstanowe, ustawiając store=false.
  • Widoczne kroki wykonania: wpisane kroki ułatwiają debugowanie złożonych przepływów i renderowanie interfejsu użytkownika dla zdarzeń pośrednich (takich jak myśli czy widżety wyszukiwania).
  • Korzystanie z narzędzi i przepływy pracy agenta: natywna obsługa wieloetapowego korzystania z narzędzi, aranżacji i złożonych przepływów rozumowania za pomocą wpisywanych kroków wykonywania.
  • Długotrwałe zadania i zadania w tle: obsługuje przenoszenie czasochłonnych operacji, takich jak Deep Think i Deep Research, do procesów w tle za pomocą background=true.

Podstawowe wejście/wyjście

W tej sekcji pokazujemy, jak przeprowadzić migrację prostego żądania generowania tekstu.

Przed (generateContent)

Interfejs generateContent API jest bezstanowy i zwraca odpowiedź bezpośrednio. Struktura odpowiedzi obejmuje dane wyjściowe w postaci listy elementów candidates, z których każdy zawiera element content z listą elementów parts do przeanalizowania.

Python

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash-lite", contents="Tell me a joke."
)
print(response.text)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash-lite",
  contents: "Tell me a joke.",
});
console.log(response.text);

REST

# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "contents": [{
        "parts": [{
            "text": "Tell me a joke."
        }]
    }]
}'

# Response
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Why did the chicken cross the road? To get to the other side!"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 12,
    "totalTokenCount": 16
  }
}

Interfejs API interakcji zwraca zapisany zasób interakcji z stepsosią czasu. Możesz ręcznie sprawdzić tablicę steps, aby znaleźć zdarzenia pośrednie, ale pakiety SDK generatywnej AI od Google udostępniają wygodne właściwości bezpośrednio w zwróconym obiekcie Interaction, aby uzyskać dostęp do końcowego wyniku.

Najczęstszym typem właściwości jest .output_text (String), który automatycznie wyodrębnia i łączy kolejne bloki TextContent na końcu odpowiedzi modelu. W przypadku prostych odpowiedzi to rozwiązanie sprawdza się doskonale, ale nie obejmuje wcześniejszych bloków tekstu oddzielonych treściami innymi niż tekst (np. przemyśleniami, obrazami, dźwiękiem lub wywołaniami narzędzi). W przypadku złożonych lub przeplatanych odpowiedzi multimodalnych musisz ręcznie iterować po steps.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.6-flash", input="Tell me a joke."
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

let interaction = await client.interactions.create({
    model: 'gemini-3.6-flash',
    input: 'Tell me a joke.'
});

console.log(interaction.output_text);

REST

# Request
curl -X POST "https://generativelanguage.googleapis.com/v1beta2/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "model": "gemini-3.6-flash",
    "input": "Tell me a joke."
}'

# Response
{
  "id": "int_123",
  "status": "completed",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Tell me a joke."
        }
      ]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

Rozmowy wieloetapowe

Interfejs API interakcji domyślnie przechowuje interakcje, co umożliwia zarządzanie stanem po stronie serwera w przypadku rozmów wieloetapowych.

Przed (generateContent)

W generateContent musisz ręcznie zarządzać historią rozmów za pomocą tablicy contents lub pomocnika czatu po stronie klienta.

Python

Korzystanie z pomocy na czacie (zalecane)

from google import genai

client = genai.Client()

chat = client.chats.create(model="gemini-2.5-flash-lite")
response1 = chat.send_message("Hi, my name is Phil.")
print(response1.text)

response2 = chat.send_message("What is my name?")
print(response2.text)

Ręczne zarządzanie historią

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash-lite",
    contents=[
        types.Content(
            role="user", parts=[types.Part.from_text(text="Hi, my name is Phil.")]
        ),
        types.Content(
            role="model",
            parts=[types.Part.from_text(text="Hi Phil, how can I help you?")],
        ),
        types.Content(
            role="user", parts=[types.Part.from_text(text="What is my name?")]
        ),
    ],
)
print(response.text)

JavaScript

Korzystanie z pomocy na czacie (zalecane)

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const chat = client.chats.create({ model: 'gemini-2.5-flash-lite' });
let response = await chat.sendMessage({ message: 'Hi, my name is Phil.' });
console.log(response.text);

response = await chat.sendMessage({ message: 'What is my name?' });
console.log(response.text);

Ręczne zarządzanie historią

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const response = await client.models.generateContent({
    model: 'gemini-2.5-flash-lite',
    contents: [
        { role: 'user', parts: [{ text: 'Hi, my name is Phil.'