Gemini API reference

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

प्राइमरी एंडपॉइंट

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

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

पुष्टि करना

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

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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): यह रॉ मीडिया बाइट और उनके एमआईएमई टाइप का कंटेनर होता है.

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

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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 ऑब्जेक्ट होता है. यह candidates ऑब्जेक्ट की सूची होती है.Candidate Candidate ऑब्जेक्ट में एक Content ऑब्जेक्ट होता है. इसमें मॉडल से मिला जनरेट किया गया जवाब होता है.

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

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

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

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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-2.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-2.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 मल्टीमॉडल की सुविधा चालू करता है: अलग-अलग तरह के डेटा (टेक्स्ट, इमेज, वीडियो यूआरआई वगैरह) को एक साथ इस्तेमाल करने के लिए, एक Part ऑब्जेक्ट में कई Part ऑब्जेक्ट इस्तेमाल करें.Content
• डेटा ट्रांसफ़र करने का तरीका चुनें:
  • सीधे तौर पर एम्बेड किए गए छोटे मीडिया (जैसे कि ज़्यादातर इमेज) के लिए, Part with inline_data का इस्तेमाल करें.
  • बड़ी फ़ाइलों या उन फ़ाइलों के लिए जिन्हें आपको कई अनुरोधों में फिर से इस्तेमाल करना है, 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-2.5-flash-lite",
  "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-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

लाइव एपीआई (BidiGenerateContent) WebSockets API

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

खास मॉडल

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

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

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

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

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

• Gemini API का इस्तेमाल शुरू करना
• Gemini के मॉडल से जुड़ी गाइड

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

• टेक्स्ट जनरेट करना
• कॉन्टेक्स्ट को कैश मेमोरी में सेव करना
• एम्बेडिंग