Interactions API

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

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 स्किल इंस्टॉल करें. इससे आपके असिस्टेंट को डेवलपर के लिए उपलब्ध नए दस्तावेज़ों और सबसे सही तरीकों का ऐक्सेस मिलेगा. कोडिंग एजेंट सेट अप करना →
  • 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 रिसॉर्स बनाई है.

SDK टूल की सुविधा वाली प्रॉपर्टी की मदद से आउटपुट ऐक्सेस करना

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

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

SDK टूल की सुविधा वाली प्रॉपर्टी रिटर्न टाइप ब्यौरा
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 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 की क्लिप की झलक मॉडल 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 पर, यह 1.33.0 वर्शन से @google/genai पैकेज है.

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

सीमाएं

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

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

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

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

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

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

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

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

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

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

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

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