API-ja e Ndërveprimeve

API-ja e Ndërveprimeve është mënyra jonë më e thjeshtë dhe më e mirë për të ndërtuar me modele dhe agjentë Gemini. Që nga qershori 2026, është përgjithësisht e disponueshme dhe e rekomanduar për të gjitha projektet e reja. Ndërsa tani konsiderohet si trashëgimi, API-ja origjinale generateContent mbetet e mbështetur plotësisht.

Pse të përdoret API-ja e Ndërveprimeve?

• Ndërfaqe universale për të gjitha aplikacionet : E projektuar si ndërfaqja standarde për çdo rast përdorimi, duke përfshirë gjenerimin e tekstit me një kthesë të vetme, kuptimin multimodal, rezultatet e strukturuara, orkestrimin e mjeteve dhe rrjedhat e punës agjentike.
• API i vetëm për modelet dhe agjentët : Një pikë fundore dhe model i unifikuar për thirrjen direkte të modeleve standarde Gemini, si dhe agjentëve të specializuar (siç janë Deep Research dhe agjentët e menaxhuar me porosi).
• Aftësi të reja menjëherë : Karakteristika si gjendja opsionale e bisedës në anën e serverit duke përdorur previous_interaction_id , hapa ekzekutimi të vëzhgueshëm për debugging dhe renderim të ndërfaqes së përdoruesit, dhe ekzekutim në sfond për detyra që ekzekutohen për një kohë të gjatë duke përdorur background=true .
• Kosto më e ulët me shkallë më të larta të goditjeve në memorien e përkohshme : Kur përdoren biseda me shumë kthesa, menaxhimi opsional i gjendjes nga ana e serverit mundëson ruajtjen më efikase të kontekstit në memorien e përkohshme nëpër kthesa, duke zvogëluar kostot e tokenëve.
• Ku lançohen veçoritë e reja : Duke vazhduar më tej, të gjitha modelet e reja, aftësitë multimodale, mjetet dhe veçoritë agjentike do të lançohen në Interactions API.

Si parazgjedhje, API-ja e Ndërveprimeve ruan kërkesat në mënyrë që të mund të shfrytëzoni veçoritë e menaxhimit të gjendjes në anën e serverit duke përdorur previous_interaction_id . Mund të zgjidhni sjelljen pa gjendje duke vendosur store=false . Shihni seksionin e ruajtjes së të dhënave për detaje.

Filloni

• Konfiguroni agjentin tuaj të kodimit : Lidhuni me Gemini Docs MCP dhe instaloni aftësinë gemini-interactions-api për t'i dhënë asistentit tuaj akses të drejtpërdrejtë në dokumentet dhe praktikat më të mira më të fundit të zhvilluesit. Konfiguroni agjentin tuaj të kodimit →
• Migroni nga generateContent : Nëse keni një integrim ekzistues, ndiqni Udhëzuesin e Migrimit për të kaluar në API-në e Ndërveprimeve.
• Filloni : Filloni në udhëzuesin e fillimit të Interactions API .

Udhëzues për veçoritë

Eksploroni aftësitë specifike të Interactions API përmes këtyre udhëzuesve. Mund të përdorni butonin e ndërrimit në këto faqe për të kaluar midis generateContent dhe Interactions API:

• Gjenerimi i tekstit
• Gjenerimi i imazhit
• Kuptimi i imazhit
• Kuptimi i audios
• Kuptimi i videos
• Përpunimi i dokumenteve
• Thirrja e funksionit
• Prodhim i strukturuar
• Agjent i Kërkimeve të Thella
• Përfundim fleksibël
• Përfundimi i përparësisë

Si funksionon API-ja e Ndërveprimeve

API-ja e Ndërveprimeve përqendrohet rreth një burimi kryesor: Interaction . Një Interaction përfaqëson një kthesë të plotë në një bisedë ose detyrë. Ai vepron si një regjistrim sesioni, që përmban të gjithë historinë e një ndërveprimi si një sekuencë kronologjike hapash ekzekutimi . Këta hapa përfshijnë mendime modeli, thirrje dhe rezultate mjetesh nga serveri ose klienti (si function_call dhe function_result ), dhe model_output përfundimtar. Burimi i ruajtur (i marrë nëpërmjet interactions.get ) përfshin gjithashtu hapa user_input për kontekst të plotë, megjithëse përgjigja interactions.create kthen vetëm hapa të gjeneruar nga modeli.

Kur bëni një thirrje në interactions.create , ju po krijoni një burim të ri Interaction .

Menaxhimi i gjendjes nga ana e serverit

Mund të përdorni id në e një bashkëveprimi të përfunduar në një thirrje pasuese duke përdorur parametrin previous_interaction_id për të vazhduar bisedën. Serveri përdor këtë ID për të rimarrë historikun e bisedës, duke ju kursyer nga ridërgimi i të gjithë historikut të bisedës.

Parametri previous_interaction_id ruan vetëm historikun e bisedës (të dhënat hyrëse dhe dalëse) duke përdorur previous_interaction_id . Parametrat e tjerë janë të përcaktuar sipas ndërveprimit dhe zbatohen vetëm për ndërveprimin specifik që po gjeneroni aktualisht:

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

Kjo do të thotë që duhet t'i rispecifikoni këto parametra në çdo bashkëveprim të ri nëse dëshironi që ato të zbatohen. Ky menaxhim i gjendjes nga ana e serverit është opsional; gjithashtu mund të veproni në modalitetin pa gjendje duke dërguar historikun e plotë të bisedës në çdo kërkesë.

Ruajtja dhe ruajtja e të dhënave

Si parazgjedhje, API ruan të gjitha objektet e Ndërveprimit ( store=true ) për të thjeshtuar përdorimin e veçorive të menaxhimit të gjendjes në anën e serverit (me previous_interaction_id ), ekzekutimin në sfond (duke përdorur background=true ) dhe për qëllime vëzhgueshmërie.

• Niveli i Paguar : Sistemi ruan ndërveprimet për 55 ditë .
• Niveli Falas : Sistemi ruan ndërveprimet për 1 ditë .

Nëse nuk e dëshironi këtë, mund të vendosni store=false në kërkesën tuaj. Ky kontroll është i ndarë nga menaxhimi i gjendjes; mund të zgjidhni të mos përdorni hapësirën e ruajtjes për çdo ndërveprim. Megjithatë, vini re se store=false nuk është i përputhshëm me ekzekutimin në sfond dhe parandalon përdorimin e previous_interaction_id për kthesat pasuese.

Për projektet e Nivelit të Paguar, mund ta konfiguroni dritaren e ruajtjes në AI Studio për të shënuar automatikisht regjistrat për fshirje nga hapësira ruajtëse e projektit pas 7, 14, 28 ose 55 ditësh. Një ruajtje më e shkurtër mund të ndikojë në rikthimin e bisedave të kaluara.

Mund t’i fshini ndërveprimet e ruajtura në çdo kohë duke përdorur metodën delete në mënyrë programore, e cila kërkon ID-në e ndërveprimit. Gjithashtu mund të shikoni dhe menaxhoni regjistrat e ndërveprimeve të ruajtura, duke përfshirë fshirjen nga hapësira ruajtëse e projektit, në AI Studio .

Pas skadimit të periudhës së ruajtjes, të dhënat tuaja do të fshihen automatikisht.

Objektet e ndërveprimit përpunohen sipas termave .

Shikoni Ndërveprimet në AI Studio

API-ja ruan kërkesat e API-së së Ndërveprimeve të ekzekutuara me store=true për projektet në Nivelin e Paguar. Mund t'i shikoni ato direkt nga faqja e Logjeve në Google AI Studio . Shihni udhëzuesin e Logjeve për më shumë.

Praktikat më të mira

• Shkalla e klikimeve në memorjen e përkohshme: Ruajtja e përkohshme në memorje të përkohshme mbështetet si në modalitetet me gjendje ashtu edhe pa gjendje (shih Fillimi i Shpejtë ). Përdorimi previous_interaction_id (me gjendje) për të vazhduar bisedat i lejon sistemit të përdorë më lehtë ruajtjen e përkohshme në memorje të përkohshme për historikun e bisedave, gjë që përmirëson performancën dhe ul kostot.
• Përzierja e ndërveprimeve : Ju keni fleksibilitetin për të përzier dhe përputhur ndërveprimet e Agjentit dhe Modelit brenda një bisede. Për shembull, mund të përdorni një agjent të specializuar, si agjenti i Kërkimit të Thellë, për mbledhjen fillestare të të dhënave, dhe më pas të përdorni një model standard Gemini për detyra pasuese, të tilla si përmbledhja ose riformatimi, duke i lidhur këto hapa me previous_interaction_id .

Modele dhe agjentë të mbështetur

SDK-të

Mund të përdorni versionin më të fundit të SDK-ve të Google GenAI për të aksesuar API-në e Ndërveprimeve.

• Në Python, kjo është paketa google-genai nga versioni 2.3.0 e tutje.
• Në JavaScript, kjo është paketa @google/genai nga versioni 2.3.0 e tutje.

Mund të mësoni më shumë rreth mënyrës së instalimit të SDK-ve në faqen e Bibliotekave .

Kufizime

• MCP në distancë : Gemini 3 nuk e mbështet MCP në distancë, kjo do të vijë së shpejti.
• Pajtueshmëria e modelit me shumë kthesa : Kur përzieni modele të ndryshme në një bisedë (qoftë me ose pa gjendje), modelet pasuese duhet të mbështesin modalitetet e daljes së modeleve të mëparshme si hyrje. Për shembull, nëse gjeneroni një imazh duke përdorur gemini-3.1-flash-image , nuk mund ta vazhdoni atë bisedë me një model që nuk pranon hyrje imazhi (siç është një model vetëm me tekst ose një model gjenerimi muzike si Lyria).

Karakteristikat e mëposhtme mbështeten nga generateContent API, por nuk janë ende të disponueshme në Interactions API:

• Meta të dhëna videoje : Fusha video_metadata , përdoret për të vendosur intervalet e prerjes dhe shpejtësitë e personalizuara të kuadrove për të kuptuar videon.
• API-ja e grupeve
• Thirrja automatike e funksionit (Python)
• Ruajtja në memorje të qartë : Vini re se ruajtja në memorje e nënkuptuar nga ana e serverit është e disponueshme në Interactions API nëpërmjet previous_interaction_id .
• Cilësimet e sigurisë : Cilësimet e personalizuara të sigurisë nuk mbështeten në API-në e Ndërveprimeve.

Reagime

Reagimet tuaja janë thelbësore për zhvillimin e API-t të Ndërveprimeve. Ndani mendimet tuaja, raportoni gabime ose kërkoni veçori në Forumin tonë të Komunitetit të Zhvilluesve të IA-së në Google .

Çfarë vjen më pas

• Provo fletoren e nisjes së shpejtë të Interactions API .
• Mësoni më shumë rreth Agjentit të Kërkimeve të Thellë Gemini .