Gemini API reference

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

मुख्य एंडपॉइंट

Gemini API, इन मुख्य एंडपॉइंट के हिसाब से व्यवस्थित है:

  • इंटरैक्शन (CreateInteraction) (सुझाया गया): Gemini के साथ काम करने के लिए, यह स्टैंडर्ड प्रिमिटिव है. इसे एजेंटिक वर्कफ़्लो, सर्वर-साइड स्टेट मैनेजमेंट, और मल्टी-मोडल, मल्टी-टर्न वाली जटिल बातचीत के लिए ऑप्टिमाइज़ किया गया है. हमारा सुझाव है कि इसका इस्तेमाल किया जाए.
  • स्टैंडर्ड कॉन्टेंट जनरेशन (generateContent): यह एक स्टैंडर्ड REST एंडपॉइंट है. यह आपके अनुरोध को प्रोसेस करता है और मॉडल का पूरा जवाब एक ही पैकेज में दिखाता है. यह उन नॉन-इंटरैक्टिव टास्क के लिए सबसे सही है जिनमें पूरे नतीजे का इंतज़ार किया जा सकता है.
  • स्ट्रीमिंग कॉन्टेंट जनरेशन (streamGenerateContent): यह Server-Sent Events (एसएसई) का इस्तेमाल करके, जवाब के हिस्सों को जनरेट होने के साथ-साथ आपको भेजता है. इससे चैटबॉट जैसे ऐप्लिकेशन के लिए, ज़्यादा तेज़ और इंटरैक्टिव अनुभव मिलता है.
  • Live API (BidiGenerateContent): यह स्टेटफ़ुल WebSocket पर आधारित एपीआई है. इसका इस्तेमाल, दोनों दिशाओं में स्ट्रीमिंग के लिए किया जाता है. इसे रीयल-टाइम बातचीत के इस्तेमाल के लिए डिज़ाइन किया गया है.
  • बैच मोड (batchGenerateContent): यह generateContent के अनुरोधों के बैच सबमिट करने के लिए, एक स्टैंडर्ड REST एंडपॉइंट है.
  • एंबेडिंग (embedContent): यह एक स्टैंडर्ड REST एंडपॉइंट है. यह इनपुट Content से, टेक्स्ट एंबेडिंग वेक्टर जनरेट करता है.
  • Gen Media APIs: ये एंडपॉइंट, इमेज जनरेट करने के लिए Imagen और वीडियो जनरेट करने के लिए Veo जैसे हमारे खास मॉडल की मदद से मीडिया जनरेट करते हैं. Gemini में ये सुविधाएं भी शामिल हैं. इन्हें ऐक्सेस करने के लिए, generateContent API का इस्तेमाल किया जा सकता है.
  • प्लैटफ़ॉर्म एपीआई: ये यूटिलिटी एंडपॉइंट हैं. ये फ़ाइलें अपलोड करने और टोकन की गिनती करने जैसी मुख्य सुविधाओं के साथ काम करते हैं.

पुष्टि करना

Gemini API के सभी अनुरोधों में, x-goog-api-key हेडर के साथ आपका एपीआई पासकोड शामिल होना चाहिए. Google AI Studio में कुछ ही क्लिक में इसे बनाया जा सकता है.

यहां हेडर में एपीआई पासकोड शामिल करके, अनुरोध का एक उदाहरण दिया गया है:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Gemini SDK टूल का इस्तेमाल करके, एपीआई को पासकोड भेजने के तरीके के बारे में जानने के लिए, Gemini API पासकोड का इस्तेमाल करने की गाइड देखें.

कॉन्टेंट जनरेट करना

यह मॉडल को प्रॉम्प्ट भेजने का मुख्य एंडपॉइंट है. कॉन्टेंट जनरेट करने के लिए दो एंडपॉइंट हैं. इनमें मुख्य अंतर यह है कि आपको जवाब कैसे मिलता है:

  • generateContent (REST): यह एक अनुरोध लेता है और मॉडल के पूरा कॉन्टेंट जनरेट करने के बाद, एक जवाब देता है.
  • streamGenerateContent (एसएसई): यह ठीक वही अनुरोध लेता है, लेकिन मॉडल जवाब के हिस्सों को जनरेट होने के साथ-साथ स्ट्रीम करता है. इससे इंटरैक्टिव ऐप्लिकेशन के लिए, उपयोगकर्ताओं को बेहतर अनुभव मिलता है, क्योंकि इससे नतीजे के कुछ हिस्से तुरंत दिखाए जा सकते हैं.

अनुरोध के मुख्य भाग का स्ट्रक्चर

अनुरोध का मुख्य भाग, एक JSON ऑब्जेक्ट होता है. यह स्टैंडर्ड और स्ट्रीमिंग, दोनों मोड के लिए एक जैसा होता है. इसे कुछ मुख्य ऑब्जेक्ट से बनाया जाता है:

  • Content ऑब्जेक्ट: यह बातचीत के एक टर्न को दिखाता है.
  • Part ऑब्जेक्ट: यह Content टर्न में मौजूद डेटा का एक हिस्सा होता है. जैसे, टेक्स्ट या इमेज.
  • inline_data (Blob): यह रॉ मीडिया बाइट और उनके MIME टाइप के लिए एक कंटेनर है.

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

यहां generateContent के अनुरोध के मुख्य भाग का एक सामान्य उदाहरण दिया गया है:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

जवाब के मुख्य भाग का स्ट्रक्चर

जवाब का मुख्य भाग स्ट्रीमिंग और स्टैंडर्ड, दोनों मोड के लिए एक जैसा होता है. हालांकि, इनमें ये अंतर होते हैं:

  • स्टैंडर्ड मोड: जवाब के मुख्य भाग में, GenerateContentResponse का एक इंस्टेंस शामिल होता है.
  • स्ट्रीमिंग मोड: जवाब के मुख्य भाग में, GenerateContentResponse इंस्टेंस की एक स्ट्रीम शामिल होती है.

सबसे ऊपर के लेवल पर, जवाब के मुख्य भाग में एक candidates ऑब्जेक्ट होता है. यह Candidate ऑब्जेक्ट की एक सूची होती है. Candidate ऑब्जेक्ट में एक Content ऑब्जेक्ट होता है. इसमें मॉडल से मिला जनरेट किया गया जवाब शामिल होता है.

अनुरोध के उदाहरण

यहां दिए गए उदाहरणों में दिखाया गया है कि अलग-अलग तरह के अनुरोधों के लिए, ये कॉम्पोनेंट एक साथ कैसे काम करते हैं.

सिर्फ़ टेक्स्ट वाला प्रॉम्प्ट

सिर्फ़ टेक्स्ट वाले एक सामान्य प्रॉम्प्ट में, contents कलेक्शन होता है. इसमें एक Content ऑब्जेक्ट शामिल होता है. उस ऑब्जेक्ट के parts कलेक्शन में, एक Part ऑब्जेक्ट होता है. इसमें text फ़ील्ड शामिल होता है.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

मल्टीमोडल प्रॉम्प्ट (टेक्स्ट और इमेज)

किसी प्रॉम्प्ट में टेक्स्ट और इमेज, दोनों शामिल करने के लिए, parts कलेक्शन में दो Part ऑब्जेक्ट होने चाहिए: एक टेक्स्ट के लिए और दूसरा इमेज के inline_data के लिए.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

मल्टी-टर्न वाली बातचीत (चैट)

मल्टी-टर्न वाली बातचीत बनाने के लिए, contents कलेक्शन में एक से ज़्यादा Content ऑब्जेक्ट तय करें. एपीआई, अगले जवाब के लिए इस पूरे इतिहास को कॉन्टेक्स्ट के तौर पर इस्तेमाल करेगा. हर Content ऑब्जेक्ट के लिए, role की वैल्यू user और model के बीच बदलती रहनी चाहिए.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

ज़रूरी बातें

  • Content एक एनवलप है: यह मैसेज टर्न के लिए टॉप-लेवल कंटेनर है. यह टर्न, उपयोगकर्ता या मॉडल से हो सकता है.
  • Part मल्टीमोडैलिटी की सुविधा देता है: अलग-अलग तरह के डेटा (टेक्स्ट, इमेज, वीडियो यूआरआई वगैरह) को एक साथ इस्तेमाल करने के लिए, एक Content ऑब्जेक्ट में एक से ज़्यादा Part ऑब्जेक्ट का इस्तेमाल करें.
  • डेटा का तरीका चुनें:
    • छोटे, सीधे तौर पर एंबेड किए गए मीडिया (जैसे, ज़्यादातर इमेज) के लिए, inline_data के साथ Part का इस्तेमाल करें.
    • बड़ी फ़ाइलों या उन फ़ाइलों के लिए जिन्हें आपको अलग-अलग अनुरोधों में फिर से इस्तेमाल करना है, File API का इस्तेमाल करके फ़ाइल अपलोड करें. इसके बाद, file_data पार्ट की मदद से उसका रेफ़रंस दें.
  • बातचीत के इतिहास को मैनेज करना: REST API का इस्तेमाल करने वाले चैट ऐप्लिकेशन के लिए, हर टर्न के लिए Content ऑब्जेक्ट जोड़कर, contents कलेक्शन बनाएं. इसमें "user" और "model" की भूमिकाएं बदलती रहनी चाहिए. अगर एसडीके का इस्तेमाल किया जा रहा है, तो बातचीत के इतिहास को मैनेज करने के सुझाए गए तरीके के लिए, एसडीके का दस्तावेज़ देखें.

जवाब के उदाहरण

यहां दिए गए उदाहरणों में दिखाया गया है कि अलग-अलग तरह के अनुरोधों के लिए, ये कॉम्पोनेंट एक साथ कैसे काम करते हैं.

सिर्फ़ टेक्स्ट वाला जवाब

डिफ़ॉल्ट टेक्स्ट जवाब में, candidates कलेक्शन होता है. इसमें एक या एक से ज़्यादा content ऑब्जेक्ट शामिल होते हैं. इनमें मॉडल का जवाब होता है.

यहां स्टैंडर्ड जवाब का एक उदाहरण दिया गया है:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

यहां स्ट्रीमिंग जवाबों की सीरीज़ दी गई है. हर जवाब में एक responseId होता है. इससे पूरे जवाब को एक साथ जोड़ा जाता है:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-3.5-flash",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-3.5-flash",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets API

Live API, स्टेटफ़ुल WebSocket पर आधारित एपीआई उपलब्ध कराता है. इसका इस्तेमाल, दोनों दिशाओं में स्ट्रीमिंग के लिए किया जाता है. इससे रीयल-टाइम स्ट्रीमिंग के इस्तेमाल के उदाहरणों को लागू किया जा सकता है. ज़्यादा जानकारी के लिए, Live API की गाइड और Live API का रेफ़रंस देखें.

खास मॉडल

Gemini API, Gemini के मॉडल के अलावा, Imagen, Lyria और एंबेडिंग मॉडल जैसे खास मॉडल के लिए एंडपॉइंट उपलब्ध कराता है. इन गाइड को मॉडल सेक्शन में देखा जा सकता है.

प्लैटफ़ॉर्म एपीआई

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

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

अगर आपने अभी-अभी शुरुआत की है, तो यहां दी गई गाइड देखें. इनसे आपको Gemini API के प्रोग्रामिंग मॉडल को समझने में मदद मिलेगी:

इसके अलावा, सुविधाओं की गाइड भी देखी जा सकती हैं. इनमें Gemini API की अलग-अलग सुविधाओं के बारे में बताया गया है और कोड के उदाहरण दिए गए हैं: