API-ja e Ndërveprimeve

API-ja e Ndërveprimeve është mënyra 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. Për hapa të detajuar, shihni udhëzuesin 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 : Ndiqni hapat në udhëzuesin e fillimit të Interactions API .

Udhëzues të veçorive

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 .