Interactions API

Interactions API është mënyra më e mirë për të ndërtuar me modelet dhe agjentët e Gemini. Nga qershori 2026, ai është i disponueshëm në përgjithësi dhe rekomandohet për të gjitha projektet e reja. Megjithëse tani konsiderohet i vjetër, API-ja origjinale generateContent vazhdon të mbështetet plotësisht.

Pse të përdorësh Interactions API?

• Ndërfaqja universale për të gjitha aplikacionet: Projektuar si ndërfaqja standarde për çdo rast përdorimi, duke përfshirë gjenerimin e tekstit me një kthesë, kuptimin multimodal, daljet e strukturuara, organizimin e veglave dhe flukset e punës të agjentëve.
• API i vetëm për modelet dhe agjentët: Një pikë fundore dhe model i unifikuar për thirrjen e modeleve standarde të Gemini, si dhe agjentëve të specializuar drejtpërdrejt (si p.sh. Deep Research dhe agjentët e personalizuar të menaxhuar).
• Aftësi të reja të gatshme për t'u përdorur: Veçori si gjendja opsionale e bisedës në anën e serverit duke përdorur previous_interaction_id, hapat e vëzhgueshëm të ekzekutimit për korrigjimin dhe paraqitjen e ndërfaqes së përdoruesit, si dhe ekzekutimi në sfond për detyrat që zgjasin për një kohë të gjatë duke përdorur background=true.
• Kosto më e ulët me norma më të larta të përputhjes së memories specifike: Kur përdor biseda me disa hapa, menaxhimi opsional i gjendjes në anën e serverit mundëson memorizim specifik më efikas të kontekstit nëpër hapa, duke reduktuar kostot e dërgimit të shenjave.
• Ku do të prezantohen veçoritë e reja: Në vazhdim, të gjitha modelet e reja, aftësitë multimodale, veglat dhe veçoritë e agjentëve do të prezantohen në API-n e "Ndërveprimeve".

Si parazgjedhje, Interactions API i ruan kërkesat që të mund të përdorësh veçoritë e menaxhimit të gjendjes nga ana e serverit duke përdorur previous_interaction_id. Mund të zgjedhësh sjelljen pa gjendje duke caktuar store=false. Shiko seksionin e mbajtjes së të dhënave për detaje.

Fillo

• Konfiguro agjentin tënd të kodimit: Lidhu me Gemini Docs MCP dhe instalo aftësinë e gemini-api-dev për t'i dhënë asistentit tënd qasje të drejtpërdrejtë te dokumentet më të fundit të zhvilluesit dhe praktikat më të mira. Për hapat e detajuar, shiko Udhëzuesin për konfigurimin e agjentit tënd të kodimit
• Migro nga generateContent: Nëse ke një integrim ekzistues, ndiq Udhëzuesin e migrimit për të kaluar tek Interactions API.
• Fillo: Ndiq hapat në udhëzuesin "Fillo" për Interactions API.

Udhëzuesit e veçorive

Eksploro aftësitë specifike të API-së së "Ndërveprimeve" nëpërmjet këtyre udhëzuesve. Mund të përdorësh çelësin në këto faqe për të kaluar mes generateContent dhe Interactions API:

• Gjenerimi i tekstit
• Gjenerimi i imazheve
• Kuptueshmëria e imazheve
• Kuptimi i audios
• Kuptimi i videove
• Përpunimi i dokumentit
• Thirrja e funksionit
• Rezultati i strukturuar
• Agjenti i Deep Research
• Deduksioni Flex
• Përfundimi me përparësi

Si funksionon Interactions API

API-ja e ndërveprimeve përqendrohet në një burim kryesor: Interaction. Një Interaction përfaqëson një radhë të plotë në një bisedë ose detyrë. Ai funksionon si një regjistër seance, që përmban të gjithë historikun e një ndërveprimi si një sekuencë kronologjike hapash ekzekutimi. Këta hapa përfshijnë mendimet e modelit, thirrjet dhe rezultatet e veglave në anën e serverit ose në anën e klientit (si p.sh. function_call dhe function_result), si dhe model_output përfundimtare. Burimi i ruajtur (i marrë nëpërmjet interactions.get) përfshin gjithashtu user_input hapa për kontekstin e plotë, megjithëse përgjigjja e interactions.create kthen vetëm hapat e gjeneruar nga modeli.

Kur bën një telefonatë te interactions.create, po krijon një burim të ri të Interaction:

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)

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);

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(""));

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)
    }
}

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."
  }'

Menaxhimi i gjendjes në anën e serverit

Mund të përdorësh id e një ndërveprimi të përfunduar në një telefonatë vijuese duke përdorur parametrin previous_interaction_id për të vazhduar bisedën. Serveri e përdor këtë ID për të marrë historikun e bisedës, duke të të kursyer nga nevoja për të ridërguar të gjithë historikun e bisedës:

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)

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);

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(""));

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)
    }
}

# 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"
  }'

Parametri previous_interaction_id ruan vetëm historikun e bisedës (hyrjet dhe daljet) duke përdorur previous_interaction_id. Parametrat e tjerë janë me fushëveprim ndërveprimi dhe zbatohen vetëm për ndërveprimin specifik që po gjeneron aktualisht:

• tools
• system_instruction
• generation_config (duke përfshirë thinking_level, temperature etj.)

Kjo do të thotë që duhet t'i specifikosh përsëri këta parametra në çdo ndërveprim të ri nëse dëshiron që ata të zbatohen. Ky menaxhim i gjendjes në anën e serverit është opsional; mund të veprosh gjithashtu në modalitetin pa gjendje duke dërguar historikun e plotë të bisedës në çdo kërkesë.

Ruajtja dhe mbajtja e të dhënave

Si parazgjedhje, API-ja ruan të gjitha objektet e ndërveprimit (store=true) për të thjeshtuar përdorimin e veçorive të menaxhimit të gjendjes nga ana e serverit (me previous_interaction_id), ekzekutimin në sfond (duke përdorur background=true) dhe për qëllime vëzhgimi.

• Niveli me pagesë: Sistemi i ruan ndërveprimet për 55 ditë.
• Niveli falas: Sistemi i mban ndërveprimet për 1 ditë.

Nëse nuk e dëshiron këtë, mund të caktosh store=false në kërkesën tënde. Ky kontroll është i ndarë nga menaxhimi i gjendjes; mund të tërhiqesh nga ruajtja për çdo ndërveprim. Megjithatë, ki parasysh se store=false nuk është i përputhshëm me ekzekutimin në sfond dhe parandalon përdorimin e previous_interaction_id për radhët vijuese.

Për projektet e nivelit me pagesë, mund të konfigurosh periudhën e ruajtjes në AI Studio për të shënuar automatikisht evidencat për fshirje nga hapësira ruajtëse e projektit pas 7, 14, 28 ose 55 ditësh. Një periudhë më e shkurtër mbajtjeje mund të ndikojë te marrja e bisedave të kaluara.

Mund t'i fshish ndërveprimet e ruajtura në çdo kohë duke përdorur metodën delete në mënyrë programatike, e cila kërkon ID-në e ndërveprimit. Gjithashtu, mund të shikosh dhe të menaxhosh evidencat e ruajtura të ndërveprimeve, duke përfshirë fshirjen nga hapësira ruajtëse e projektit, në AI Studio.

Pasi të skadojë periudha e ruajtjes, të dhënat e tua do të fshihen automatikisht.

Objektet e ndërveprimit përpunohen në përputhje me kushtet.

Shiko ndërveprimet në AI Studio

API-ja ruan kërkesat e Interactions API të ekzekutuara me store=true për projektet në nivelin me pagesë. Mund t'i shikosh ato drejtpërdrejt nga faqja "Evidencat" në Google AI Studio. Shiko Udhëzuesin e evidencave për më shumë.

Praktikat më të mira

• Shkalla e goditjes së memorieve specifike: Ruajtja implicite në memorien specifike mbështetet si në modalitetin me gjendje, ashtu edhe në atë pa gjendje (shiko Nisjen e shpejtë). Përdorimi i previous_interaction_id (me gjendje) për të vazhduar bisedat lejon që sistemi të përdorë më lehtë ruajtjen e ndërmjetme të të dhënave për historikun e bisedave, gjë që përmirëson performancën dhe ul kostot.
• Ndërveprimet e përzierjes: Ke fleksibilitetin për të përzier dhe kombinuar ndërveprimet e agjentit dhe modelit brenda një bisede. Për shembull, mund të përdorësh një agjent të specializuar, si p.sh. agjentin e Deep Research, për mbledhjen fillestare të të dhënave dhe më pas të përdorësh një model standard të Gemini për detyrat vijuese, si p.sh. përmbledhja ose riformatimi, duke i lidhur këta hapa me previous_interaction_id.

Modelet dhe agjentët e mbështetur

SDK-të

Mund të përdorësh versionin më të fundit të SDK-ve të Google GenAI për t'u qasur tek Interactions API.

• Në Python, kjo është paketa google-genai nga versioni 2.3.0 dhe në vazhdim.
• Në JavaScript, kjo është paketa @google/genai nga versioni 2.3.0 e në vazhdim.
• Në Go, kjo është pakoja google.golang.org/genai.
• Në Java, kjo është paketa com.google.genai:google-genai.

Mund të mësosh më shumë se si të instalosh SDK-të në faqen Bibliotekat.

Kufizimet

• MCP në distancë: Gemini 3 nuk e mbështet MCP në distancë. Kjo pritet së shpejti.
• Përputhshmëria e modelit me disa hapa: Kur përzien modele të ndryshme në një bisedë (me ose pa gjendje), modelet vijuese duhet të mbështesin modalitetet e nxjerra të modeleve të mëparshme si hyrje. Për shembull, nëse gjeneron një imazh duke përdorur gemini-3.1-flash-image, nuk mund ta vazhdosh atë bisedë me një model që nuk pranon hyrje imazhesh (si p.sh. një model vetëm me tekst ose një model gjenerimi muzike si Lyria).

Veçoritë e mëposhtme mbështeten nga API-ja e generateContent, por nuk ofrohen ende në Interactions API:

• Batch API
• Thirrja automatike e funksionit (Python)
• Ruajtja e qartë në memorien specifike: Ki parasysh se ruajtja e nënkuptuar në memorien specifike në anën e serverit ofrohet në Interactions API nëpërmjet previous_interaction_id.
• Cilësimet e sigurisë: Cilësimet e personalizuara të sigurisë nuk mbështeten në Interactions API.

Komentet

Komentet e tua janë thelbësore për zhvillimin e Interactions API. Ndaj mendimet e tua, raporto defekte ose kërko veçori në Forumin e komunitetit të zhvilluesve të IA-së së Google.

Çfarë ka më pas

• Provo bllokun e shënimeve të nisjes së shpejtë të Interactions API.
• Mëso më shumë rreth agjentit të Gemini Deep Research.