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 की रॉ टाइमलाइन की जांच और उसे मैन्युअल तरीके से ट्रैवर्स किया जा सकता है.

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

बातचीत जारी रखने के लिए, 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.5 Flash मॉडल gemini-3.5-flash
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

एसडीके

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

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

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

सीमाएं

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

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

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

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

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

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

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

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

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

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

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

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