Interactions API

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

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

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

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

शुरू करें

  • कोडिंग एजेंट सेट अप करें: 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 संसाधन बनता है.

एसडीके की सुविधाजनक प्रॉपर्टी की मदद से आउटपुट ऐक्सेस करना

Interactions API, एक्ज़ीक्यूशन स्टेप (जैसे, थॉट, खोज क्वेरी, और फ़ंक्शन कॉल) की स्ट्रक्चर्ड टाइमलाइन दिखाता है. हालांकि, मॉडल के फ़ाइनल जवाब पाने के लिए, आपको मैन्युअल तरीके से स्टेप को ट्रैवर्स करने की ज़रूरत नहीं होती.

Google GenAI SDK टूल, अलग-अलग मोड के लिए आउटपुट ऐक्सेस करने के लिए, लौटाए गए Interaction ऑब्जेक्ट पर सीधे सुविधाजनक प्रॉपर्टी उपलब्ध कराते हैं:

एसडीके की सुविधाजनक प्रॉपर्टी रिटर्न टाइप ब्यौरा
interaction.output_text स्ट्रिंग मॉडल के जवाब में मौजूद, टेक्स्ट के आखिरी ब्लॉक दिखाता है. अगर जवाब को एक के बाद एक कई TextContent ब्लॉक में बांटा गया है, तो यह उन्हें अपने-आप जोड़ देता है. इसमें, टेक्स्ट के पहले वाले ब्लॉक शामिल नहीं होते. इन्हें, गैर-टेक्स्ट कॉन्टेंट (जैसे, थॉट, इमेज, ऑडियो या टूल कॉल) से अलग किया गया होता है. जटिल या इंटरलीव्ड मल्टीमॉडल जवाबों के लिए, आपको इसके बजाय मैन्युअल तरीके से steps पर इटरेट करना होगा.
interaction.output_image ImageContent या None मौजूदा अनुरोध में, मॉडल से जनरेट किया गया इमेज का आखिरी ब्लॉक दिखाता है.
interaction.output_audio AudioContent या None मौजूदा अनुरोध में, मॉडल से जनरेट किया गया ऑडियो का आखिरी ब्लॉक दिखाता है.

ऐडवांस इस्तेमाल के उदाहरणों के लिए—जैसे, इंटरमीडिएट थिंकिंग प्रोसेस रेंडर करना, स्टेप-बाय-स्टेप टूल कॉल की जांच करना या डीबग करना—अब भी interaction.steps की रॉ टाइमलाइन की मैन्युअल तरीके से जांच की जा सकती है और उसे ट्रैवर्स किया जा सकता है.

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

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

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

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

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

बैकग्राउंड में कोड एक्ज़ीक्यूट होने की सुविधा

लंबे समय तक चलने वाले टास्क के लिए, अनुरोध में background=true सेट करके, इंटरैक्शन को बैकग्राउंड में चलाया जा सकता है. यह सुविधा इन दोनों के लिए उपलब्ध है:

  • मॉडल: यह उन टास्क के लिए काम की है जिन्हें प्रोसेस करने में ज़्यादा समय लगता है. जैसे, थिंकिंग का इस्तेमाल करने वाले टास्क.
  • एजेंट: यह लंबे समय तक चलने वाले एजेंट वर्कफ़्लो के लिए ज़रूरी है. जैसे, Deep Research.

बैकग्राउंड में चलने पर:

  • आपको store=true (डिफ़ॉल्ट) सेट करना होगा, क्योंकि सिस्टम को इंटरैक्शन संसाधन को सेव करना होता है, ताकि इसे बाद में वापस पाया जा सके.
  • interactions.create को किया गया शुरुआती कॉल, in_progress की स्थिति के साथ तुरंत वापस आ जाता है.
  • इंटरैक्शन आईडी के साथ interactions.get को कॉल करके, इंटरैक्शन की स्थिति और नतीजे वापस पाए जा सकते हैं. इसके अलावा, इंटरैक्शन पूरा होने पर सूचनाएं पाने के लिए, वेबहुक कॉन्फ़िगर किए जा सकते हैं.
  • प्रोग्रेस अपडेट पाने के लिए, इंटरैक्शन को स्ट्रीम भी किया जा सकता है.

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

डिफ़ॉल्ट रूप से, एपीआई सभी इंटरैक्शन ऑब्जेक्ट (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.5 Flash मॉडल gemini-3.5-flash
Gemini 3.1 Flash-Lite मॉडल gemini-3.1-flash-lite
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

एसडीके

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

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

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

सीमाएं

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

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

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

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

फ़िलहाल, नुकसान पहुंचाने वाले ये बदलाव किए गए हैं:

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

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

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

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

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

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

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