Interactions API

‫Interactions API היא הדרך הכי טובה לבנות עם מודלים וסוכנים של Gemini. החל מיוני 2026, היא זמינה לכלל המשתמשים ומומלצת לכל הפרויקטים החדשים. למרות שהוא נחשב עכשיו לגרסה קודמת, ה-API המקורי generateContent עדיין נתמך באופן מלא.

למה כדאי להשתמש ב-Interactions API?

  • ממשק אוניברסלי לכל האפליקציות: הממשק הזה מיועד להיות הממשק הסטנדרטי לכל תרחישי השימוש, כולל יצירת טקסט בשיחה אחת, הבנה מולטימודלית, פלט מובנה, תיאום כלים ותהליכי עבודה מבוססי-סוכנים.
  • ‫API אחד למודלים ולסוכנים: נקודת קצה (endpoint) אחת ותבנית אחת לקריאה ישירה למודלים סטנדרטיים של Gemini ולסוכנים מיוחדים (כמו Deep Research וסוכנים מנוהלים בהתאמה אישית).
  • יכולות חדשות מובנות: תכונות כמו מצב שיחה אופציונלי בצד השרת באמצעות previous_interaction_id, שלבי ביצוע שניתנים לצפייה לצורך ניפוי באגים ורינדור של ממשק המשתמש, וביצוע ברקע של משימות ארוכות באמצעות background=true.
  • עלות נמוכה יותר עם שיעורי מציאה במטמון גבוהים יותר: כשמשתמשים בשיחות עם כמה שלבים, ניהול מצב אופציונלי בצד השרת מאפשר שמירת הקשר במטמון בצורה יעילה יותר בין השלבים, וכך מפחית את עלויות הטוקנים.
  • איפה משיקים תכונות חדשות: מעכשיו, כל המודלים, היכולות המולטימודליות, הכלים והתכונות של הסוכנים יושקו ב-Interactions API.

כברירת מחדל, ה-Interactions API שומר את הבקשות כדי שתוכלו להשתמש בתכונות לניהול המצב בצד השרת באמצעות previous_interaction_id. כדי להפעיל התנהגות בלי שמירת מצב, מגדירים את store=false. פרטים נוספים זמינים בקטע שמירת נתונים.

שנתחיל?

  • הגדרת סוכן התכנות: מתחברים ל-Gemini Docs MCP ומתקינים את המיומנות gemini-api-dev כדי לתת לעוזר האישי גישה ישירה למסמכי התיעוד העדכניים ביותר למפתחים ולשיטות המומלצות. שלבים מפורטים מופיעים במאמר בנושא הגדרת סוכן תכנות.
  • מעבר מ-generateContent: אם יש לכם שילוב קיים, אתם יכולים לפעול לפי המדריך להעברת נתונים (מיגרציה) כדי לעבור ל-Interactions API.
  • איך מתחילים: פועלים לפי השלבים במדריך איך מתחילים לעבוד עם Interactions API.

מדריכים לתכונות

במדריכים האלה מוסבר על היכולות הספציפיות של Interactions API. אתם יכולים להשתמש במתג בדפים האלה כדי לעבור בין generateContent ל-Interactions API:

איך Interactions API פועל

ה-API של אינטראקציות מתמקד במשאב ליבה: Interaction. Interaction מייצג תור שלם בשיחה או במשימה. הוא משמש כתיעוד של סשן, ומכיל את ההיסטוריה המלאה של אינטראקציה כרצף כרונולוגי של שלבי ביצוע. השלבים האלה כוללים את המחשבות של המודל, קריאות לכלים ותוצאות בצד השרת או בצד הלקוח (כמו function_call ו-function_result), ואת model_output הסופי. המשאב שמאוחסן (שמאחזרים באמצעות interactions.get) כולל גם שלבים של user_input בשביל ההקשר המלא, אבל התשובה של interactions.create מחזירה רק שלבים שנוצרו על ידי המודל.

כששולחים קריאה ל-interactions.create, יוצרים משאב Interaction חדש:

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'

ניהול המצב בצד השרת

אפשר להשתמש ב-id של אינטראקציה שהסתיימה בקריאה הבאה באמצעות הפרמטר previous_interaction_id כדי להמשיך את השיחה. השרת משתמש במזהה הזה כדי לאחזר את היסטוריית השיחות, וכך לא צריך לשלוח מחדש את כל היסטוריית הצ'אט:

Python

from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)

JavaScript

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

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}

REST

# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID"
  }'

הפרמטר previous_interaction_id שומר רק את היסטוריית השיחות (קלט ופלט) באמצעות previous_interaction_id. הפרמטרים האחרים הם ברמת האינטראקציה, והם חלים רק על האינטראקציה הספציפית שאתם יוצרים כרגע:

  • tools
  • system_instruction
  • ‫generation_config (כולל thinking_level, temperature וכו')

כלומר, אם רוצים שהפרמטרים האלה יחולו, צריך לציין אותם מחדש בכל אינטראקציה חדשה. ניהול המצב בצד השרת הוא אופציונלי. אתם יכולים גם לפעול במצב ללא שמירת מצב (stateless) על ידי שליחת היסטוריית השיחות המלאה בכל בקשה.

אחסון נתונים ושמירתם

כברירת מחדל, ה-API שומר את כל אובייקטי האינטראקציה (store=true) כדי לפשט את השימוש בתכונות של ניהול מצב בצד השרת (עם previous_interaction_id), הפעלה ברקע (באמצעות background=true) ולמטרות ניטור.

  • מהדורות בתשלום: המערכת שומרת את האינטראקציות למשך 55 ימים.
  • תוכנית בחינם: המערכת שומרת את האינטראקציות למשך יום אחד.

אם אתם לא רוצים שזה יקרה, אתם יכולים להגדיר את store=false בבקשה. הפקד הזה נפרד מניהול המצב, ואפשר להשבית את האחסון בכל אינטראקציה. עם זאת, חשוב לזכור ש-store=false לא תואם להרצה ברקע ומונע שימוש ב-previous_interaction_id בתורות הבאות.

בפרויקטים בתשלום, אתם יכולים להגדיר ב-AI Studio את חלון הזמן לשמירת הנתונים, כדי לסמן באופן אוטומטי את היומנים למחיקה מהאחסון של הפרויקט אחרי 7, 14, 28 או 55 ימים. תקופת שמירה קצרה יותר עלולה להשפיע על היכולת לאחזר שיחות קודמות.

אתם יכולים למחוק אינטראקציות ששמורות בכל שלב באמצעות השיטה delete באופן פרוגרמטי, שדורשת את מזהה האינטראקציה. אתם יכולים גם לראות ולנהל את יומני האינטראקציות ששמורים, כולל מחיקה מהאחסון של הפרויקט, ב-AI Studio.

אחרי שתקופת השמירה תסתיים, הנתונים יימחקו באופן אוטומטי.

אובייקטים של אינטראקציות מעובדים בהתאם לתנאים.

צפייה באינטראקציות ב-AI Studio

ה-API שומר את הבקשות ל-Interactions API שבוצעו באמצעות store=true לפרויקטים ברמת Paid. אפשר לראות אותם ישירות בדף Logs ב-Google AI Studio. מידע נוסף זמין במדריך בנושא יומנים.

שיטות מומלצות

  • שיעור המציאה במטמון (cache hit rate): שמירה במטמון משתמעת נתמכת גם במצב עם הקשר קודם וגם במצב בלי הקשר קודם (ראו המדריך למתחילים). השימוש ב-previous_interaction_id (עם שמירת מצב) כדי להמשיך שיחות מאפשר למערכת להשתמש בקלות רבה יותר במטמון מרומז להיסטוריית השיחות, וכך לשפר את הביצועים ולהפחית את העלויות.
  • שילוב אינטראקציות: אתם יכולים לשלב בין אינטראקציות עם נציגים ועם מודלים בתוך שיחה. לדוגמה, אתם יכולים להשתמש בסוכן ייעודי, כמו Deep Research, כדי לאסוף נתונים ראשוניים, ואז להשתמש במודל Gemini רגיל למשימות המשך כמו סיכום או שינוי פורמט, ולקשר את השלבים האלה באמצעות previous_interaction_id.

מודלים וסוכנים נתמכים

שם דגם סוג מזהה דגם
Gemini 4 Argon מודל gemini-4-argon
Gemini 3.8 Flash מודל gemini-3.8-flash
Gemini 3.6 Flash מודל gemini-3.6-flash
‫Gemini 3.1 Pro Preview מודל gemini-3.1-pro-preview
Gemini 3.5 Flash-Lite מודל gemini-3.5-flash-lite
Gemini 3.1 Flash-Lite מודל gemini-3.1-flash-lite
‫Gemini 3 Flash Preview מודל gemini-3-flash-preview
Gemini ‎2.5 Pro מודל gemini-2.5-pro
Gemini ‎2.5 Flash מודל gemini-2.5-flash
Gemini 2.5 Flash-lite מודל gemini-2.5-flash-lite
‫Gemini 3 Pro Image מודל gemini-3-pro-image
תמונה של Gemini 3.1 Flash מודל gemini-3.1-flash-image
‫Gemini 3.1 Flash TTS Preview מודל gemini-3.1-flash-tts-preview
Gemma 4 31B IT מודל gemma-4-31b-it
Gemma 4 26B MoE IT מודל gemma-4-26b-a4b-it
Lyria 3.5 מודל lyria-3.5
תצוגה מקדימה של קליפ ב-Lyria 3 מודל lyria-3-clip-preview
‫Lyria 3 Pro בגרסת טרום-השקה (Preview) מודל lyria-3-pro-preview
גרסת טרום-השקה (Preview) של Deep Research סוכן deep-research-preview-04-2026
גרסת טרום-השקה (Preview) של Deep Research סוכן deep-research-max-preview-04-2026
תצוגה מקדימה של Antigravity סוכן antigravity-preview-09-2026

ערכות SDK

אתם יכולים להשתמש בגרסה העדכנית של Google GenAI SDK כדי לגשת אל Interactions API.

  • ב-Python, זו חבילת google-genai החל מגרסה 2.3.0.
  • ב-JavaScript, מדובר בחבילה @google/genai מגרסה 2.3.0 ואילך.
  • ב-Go, זו החבילה google.golang.org/genai.
  • ב-Java, זה חבילת com.google.genai:google-genai.

מידע נוסף על התקנת ערכות ה-SDK זמין בדף Libraries.

מגבלות

  • ‫MCP מרחוק: Gemini 3 לא תומך ב-MCP מרחוק, אבל התכונה הזו תהיה זמינה בקרוב.
  • תאימות למודלים רב-שלביים: כשמשלבים מודלים שונים בשיחה (עם או בלי שמירת מצב), המודלים הבאים חייבים לתמוך במודליות הפלט של המודלים הקודמים כקלט. לדוגמה, אם אתם יוצרים תמונה באמצעות gemini-3.1-flash-image, אתם לא יכולים להמשיך את השיחה הזו עם מודל שלא מקבל קלט של תמונות (כמו מודל טקסט בלבד או מודל ליצירת מוזיקה כמו Lyria).

התכונות הבאות נתמכות על ידי generateContent API, אבל עדיין לא זמינות ב-Interactions API:

משוב

המשוב שלכם חשוב מאוד לפיתוח של Interactions API. בפורום הקהילה של מפתחי Google AI אתם יכולים לשתף את המחשבות שלכם, לדווח על באגים או לבקש תכונות.

המאמרים הבאים