Interactions API

Interactions API, Gemini के साथ काम करने के लिए नया स्टैंडर्ड प्रिमिटिव है. इसे सभी नए प्रोजेक्ट के लिए इस्तेमाल करने का सुझाव दिया जाता है. यह एजेंटिक वर्कफ़्लो, सर्वर-साइड स्टेट मैनेजमेंट, और जटिल मल्टी-मॉडल, मल्टी-टर्न बातचीत के लिए ऑप्टिमाइज़ किया गया है. ओरिजनल generateContent API अब भी पूरी तरह से काम करता है.

Interactions API का इस्तेमाल क्यों करना चाहिए?

  • सर्वर-साइड हिस्ट्री मैनेजमेंट: previous_interaction_id की मदद से, मल्टी-टर्न फ़्लो को आसान बनाया जा सकता है. सर्वर, डिफ़ॉल्ट रूप से स्टेट को चालू करता है (store=true). हालांकि, store=false सेट करके, स्टेटलेस मोड में काम किया जा सकता है.
  • ऑब्ज़र्वेबल एक्ज़ीक्यूशन स्टेप: टाइप किए गए स्टेप की मदद से, जटिल फ़्लो को डीबग करना आसान हो जाता है. साथ ही, इंटरमीडिएट इवेंट (जैसे, थॉट या सर्च विजेट) के लिए यूज़र इंटरफ़ेस (यूआई) रेंडर करना आसान हो जाता है.
  • एजेंटिक वर्कफ़्लो के लिए बनाया गया है: टाइप किए गए एक्ज़ीक्यूशन स्टेप की मदद से, मल्टी-स्टेप टूल के इस्तेमाल, ऑर्केस्ट्रेशन, और जटिल रीज़निंग फ़्लो के लिए नेटिव सपोर्ट मिलता है.
  • लंबे समय तक चलने वाले और बैकग्राउंड टास्क: background=true का इस्तेमाल करके, Deep Think और Deep Research जैसी समय लेने वाली कार्रवाइयों को बैकग्राउंड प्रोसेस में ऑफ़लोड करने की सुविधा मिलती है.
  • नए मॉडल और क्षमताओं का ऐक्सेस: आने वाले समय में, मुख्य मेनलाइन फ़ैमिली के अलावा नए मॉडल, नए एजेंटिक टूल, और क्षमताओं को सिर्फ़ Interactions API पर लॉन्च किया जाएगा.

अगर कोई नया प्रोजेक्ट शुरू किया जा रहा है, एजेंटिक ऐप्लिकेशन बनाए जा रहे हैं या सर्वर-साइड बातचीत को मैनेज करने की ज़रूरत है, तो Interactions API का इस्तेमाल करें. अगर आपके पास पहले से कोई इंटिग्रेशन है जो आपकी ज़रूरतों के हिसाब से काम करता है या आपको ऐसी सुविधा की ज़रूरत है जो फ़िलहाल Interactions API में उपलब्ध नहीं है, तो generateContent का इस्तेमाल करें. जैसे, बैच एपीआई या साफ़ तौर पर कैश मेमोरी में सेव करने की सुविधा.

शुरू करें

  • कोडिंग एजेंट सेट अप करना: Gemini Docs MCP से कनेक्ट करें और gemini-interactions-api स्किल इंस्टॉल करें. इससे आपके Assistant को डेवलपर के सबसे नए दस्तावेज़ों और सबसे सही तरीकों का डायरेक्ट ऐक्सेस मिल जाएगा. कोडिंग एजेंट सेट अप करना →
  • generateContent से माइग्रेट करना: अगर आपके पास पहले से कोई इंटिग्रेशन है, Interactions API पर ट्रांज़िशन करने के लिए,माइग्रेशन गाइड देखें.
  • क्विकस्टार्ट आज़माना: Interactions API क्विकस्टार्ट में, काम करने वाले सबसे छोटे उदाहरण से शुरुआत करें.

सुविधाओं की गाइड

इन गाइड की मदद से, Interactions API की खास क्षमताओं के बारे में जानें. इन पेजों पर मौजूद टॉगल का इस्तेमाल करके, generateContent और Interactions API के बीच स्विच किया जा सकता है:

Interactions API कैसे काम करता है

Interactions API, मुख्य संसाधन Interaction पर आधारित है. Interaction, बातचीत या टास्क में एक पूरे टर्न को दिखाता है. यह एक सेशन रिकॉर्ड के तौर पर काम करता है. इसमें, एक्ज़ीक्यूशन स्टेप के क्रम के तौर पर, इंटरैक्शन का पूरा इतिहास शामिल होता है. इन स्टेप में, मॉडल के थॉट, सर्वर-साइड या क्लाइंट-साइड टूल कॉल और नतीजे (जैसे, function_call और function_result), और फ़ाइनल model_output शामिल होते हैं. सेव किए गए संसाधन (जिसे interactions.get के ज़रिए वापस पाया जाता है) में, पूरा कॉन्टेक्स्ट पाने के लिए user_input स्टेप भी शामिल होते हैं. हालांकि, interactions.create का जवाब सिर्फ़ मॉडल से जनरेट किए गए स्टेप दिखाता है.

interactions.create को कॉल करने पर, नया Interaction संसाधन बनता है.

सर्वर-साइड स्टेट मैनेजमेंट

बातचीत जारी रखने के लिए, previous_interaction_id पैरामीटर का इस्तेमाल करके, बाद में किए जाने वाले कॉल में, पूरे हो चुके इंटरैक्शन के id का इस्तेमाल किया जा सकता है. सर्वर, बातचीत का इतिहास वापस पाने के लिए इस आईडी का इस्तेमाल करता है. इससे आपको चैट का पूरा इतिहास फिर से भेजने की ज़रूरत नहीं पड़ती.

previous_interaction_id पैरामीटर, previous_interaction_id का इस्तेमाल करके, सिर्फ़ बातचीत का इतिहास (इनपुट और आउटपुट) सेव करता है. अन्य पैरामीटर इंटरैक्शन-स्कोप वाले होते हैं और ये सिर्फ़ उस इंटरैक्शन पर लागू होते हैं जिसे फ़िलहाल जनरेट किया जा रहा है:

  • tools
  • system_instruction
  • generation_config (जिसमें thinking_level, temperature वगैरह शामिल हैं)

इसका मतलब है कि अगर आपको इन पैरामीटर को लागू करना है, तो हर नए इंटरैक्शन में इन्हें फिर से तय करना होगा. सर्वर-साइड स्टेट मैनेजमेंट की सुविधा ज़रूरी नहीं है. हर अनुरोध में बातचीत का पूरा इतिहास भेजकर, स्टेटलेस मोड में भी काम किया जा सकता है.

डेटा स्टोरेज और रखरखाव

डिफ़ॉल्ट रूप से, एपीआई सभी इंटरैक्शन ऑब्जेक्ट (store=true) को सेव करता है. इससे सर्वर-साइड स्टेट मैनेजमेंट की सुविधाओं (जिसमें previous_interaction_id शामिल है), बैकग्राउंड एक्ज़ीक्यूशन (जिसमें background=true शामिल है) का इस्तेमाल आसान हो जाता है. साथ ही, इससे ऑब्ज़र्वेबिलिटी के मकसद पूरे होते हैं.

  • चुकाई गई सदस्यता वाला टियर: सिस्टम, इंटरैक्शन को 55 दिनों तक सेव रखता है.
  • मुफ़्त वाला टियर: सिस्टम, इंटरैक्शन को एक दिन तक सेव रखता है.

अगर आपको यह नहीं चाहिए, तो अपने अनुरोध में store=false सेट करें. यह कंट्रोल, स्टेट मैनेजमेंट से अलग है. किसी भी इंटरैक्शन के लिए, स्टोरेज से ऑप्ट आउट किया जा सकता है. हालांकि, ध्यान दें कि store=false, background=true के साथ काम नहीं करता. साथ ही, इससे बाद के टर्न के लिए previous_interaction_id का इस्तेमाल नहीं किया जा सकता.

एपीआई रेफ़रंस में दिए गए मिटाने के तरीके का इस्तेमाल करके, सेव किए गए इंटरैक्शन को कभी भी मिटाया जा सकता है. इंटरैक्शन को सिर्फ़ तब मिटाया जा सकता है, जब आपको इंटरैक्शन आईडी पता हो.

डेटा के रखरखाव की अवधि खत्म होने के बाद, आपका डेटा अपने-आप मिट जाएगा.

सिस्टम, शर्तों के मुताबिक इंटरैक्शन ऑब्जेक्ट को प्रोसेस करता है.

सबसे सही तरीके

  • कैश हिट रेट: बातचीत जारी रखने के लिए previous_interaction_id का इस्तेमाल करने से, सिस्टम बातचीत के इतिहास के लिए, इंप्लिसिट कैश मेमोरी में सेव करने की सुविधा का आसानी से इस्तेमाल कर पाता है. इससे परफ़ॉर्मेंस बेहतर होती है और लागत कम होती है.
  • इंटरैक्शन को मिक्स करना: बातचीत में, एजेंट और मॉडल के इंटरैक्शन को मिक्स और मैच करने की सुविधा मिलती है. उदाहरण के लिए, शुरुआती डेटा कलेक्शन के लिए, Deep Research एजेंट जैसे खास एजेंट का इस्तेमाल किया जा सकता है. इसके बाद, फ़ॉलो-अप टास्क के लिए, Gemini के स्टैंडर्ड मॉडल का इस्तेमाल किया जा सकता है. जैसे, जानकारी का सारांश देना या उसे फिर से फ़ॉर्मैट करना. इन स्टेप को previous_interaction_id से लिंक किया जा सकता है.

काम करने वाले मॉडल और एजेंट

मॉडल का नाम टाइप मॉडल आईडी
Gemini 3.1 Flash-Lite मॉडल gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite की झलक मॉडल gemini-3.1-flash-lite-preview
Gemini 3.1 Pro की झलक मॉडल gemini-3.1-pro-preview
Gemini 3 Flash की झलक मॉडल 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
Lyria 3 Clip की झलक मॉडल lyria-3-clip-preview
Lyria 3 Pro की झलक मॉडल lyria-3-pro-preview
Deep Research की झलक एजेंट deep-research-pro-preview-12-2025
Deep Research की झलक एजेंट deep-research-preview-04-2026
Deep Research की झलक एजेंट deep-research-max-preview-04-2026

SDK

Interactions API को ऐक्सेस करने के लिए, Google GenAI SDK के सबसे नए वर्शन का इस्तेमाल किया जा सकता है.

  • Python पर, यह google-genai पैकेज, 1.55.0 वर्शन या इसके बाद के वर्शन में उपलब्ध है.
  • JavaScript पर, यह @google/genai पैकेज, 1.33.0 वर्शन या इसके बाद के वर्शन में उपलब्ध है.

लाइब्रेरी वाले पेज पर जाकर, SDK इंस्टॉल करने के तरीके के बारे में ज़्यादा जाना जा सकता है.

सीमाएं

  • बीटा वर्शन: Interactions API, बीटा/प्रीव्यू वर्शन में उपलब्ध है. इसकी सुविधाओं और स्कीमा में बदलाव हो सकता है.
  • रिमोट MCP: Gemini 3, रिमोट MCP के साथ काम नहीं करता. यह सुविधा जल्द ही उपलब्ध होगी.

generateContent API में ये सुविधाएं उपलब्ध हैं, लेकिन Interactions API में फ़िलहाल उपलब्ध नहीं हैं:

नुकसान पहुंचाने वाले बदलाव

Interactions API फ़िलहाल, शुरुआती बीटा स्टेज में है. हम असल दुनिया में इसके इस्तेमाल और डेवलपर के सुझाव/शिकायत/राय के आधार पर, एपीआई की क्षमताओं, संसाधन स्कीमा, और SDK इंटरफ़ेस को लगातार डेवलप और बेहतर बना रहे हैं. इस वजह से, नुकसान पहुंचाने वाले बदलाव हो सकते हैं.

नुकसान पहुंचाने वाले मौजूदा बदलाव:

  • स्टेप स्कीमा: आउटपुट के कलेक्शन की जगह, स्टेप का नया कलेक्शन इस्तेमाल किया जा रहा है. इससे, हर इंटरैक्शन टर्न की स्ट्रक्चर्ड टाइमलाइन मिलती है.

नुकसान पहुंचाने वाले सबसे नए बदलाव के बारे में जानने और माइग्रेट करने का तरीका समझने के लिए, नुकसान पहुंचाने वाले बदलावों से जुड़ी माइग्रेशन गाइड (मई 2026) देखें.

अन्य संभावित अपडेट में, इनपुट और आउटपुट के स्कीमा, SDK के तरीके के सिग्नेचर और ऑब्जेक्ट स्ट्रक्चर, खास सुविधाओं के व्यवहार में बदलाव शामिल हो सकते हैं.

प्रोडक्शन वर्कलोड के लिए, आपको स्टैंडर्ड generateContent एपीआई का इस्तेमाल जारी रखना चाहिए. यह, स्टेबल डिप्लॉयमेंट के लिए सुझाया गया तरीका है. हम इसे लगातार डेवलप और मेंटेन करते रहेंगे.

सुझाव/राय दें या शिकायत करें

Interactions API को डेवलप करने के लिए, आपका सुझाव/राय या शिकायत अहम है. Google AI डेवलपर कम्यूनिटी फ़ोरम पर, अपने विचार शेयर करें, बग की शिकायत करें या सुविधाओं का अनुरोध करें.

आगे क्या करना है