Gemini API reference

این مرجع API، APIهای استاندارد، استریمینگ و بلادرنگ را که می‌توانید برای تعامل با مدل‌های Gemini استفاده کنید، شرح می‌دهد. می‌توانید از APIهای REST در هر محیطی که از درخواست‌های HTTP پشتیبانی می‌کند، استفاده کنید. برای نحوه شروع اولین فراخوانی API خود، به راهنمای شروع سریع مراجعه کنید. اگر به دنبال منابع کتابخانه‌ها و SDKهای مخصوص زبان ما هستید، به لینک مربوط به آن زبان در نوار ناوبری سمت چپ، زیر بخش منابع SDK ، مراجعه کنید.

نقاط پایانی اولیه

رابط برنامه‌نویسی کاربردی (API) جمینی (Gemini) حول محورهای اصلی زیر سازماندهی شده است:

• تولید محتوای استاندارد ( generateContent ): یک نقطه پایانی استاندارد REST که درخواست شما را پردازش می‌کند و پاسخ کامل مدل را در یک بسته واحد برمی‌گرداند. این بهترین گزینه برای وظایف غیر تعاملی است که در آن‌ها می‌توانید منتظر کل نتیجه باشید.
• تولید محتوای استریمینگ ( streamGenerateContent ): از رویدادهای ارسالی از سرور (SSE) برای ارسال بخش‌هایی از پاسخ به شما هنگام تولید آنها استفاده می‌کند. این امر تجربه‌ای سریع‌تر و تعاملی‌تر را برای برنامه‌هایی مانند چت‌بات‌ها فراهم می‌کند.
• رابط برنامه‌نویسی کاربردی زنده ( BidiGenerateContent ): یک رابط برنامه‌نویسی کاربردی مبتنی بر WebSocket با وضعیت برای استریمینگ دو جهته که برای موارد استفاده مکالمه‌ای بلادرنگ طراحی شده است.
• حالت دسته‌ای ( batchGenerateContent ): یک نقطه پایانی استاندارد REST برای ارسال دسته‌ای درخواست‌های generateContent .
• جاسازی‌ها ( embedContent ): یک نقطه پایانی استاندارد REST که یک بردار جاسازی متن را از ورودی Content تولید می‌کند.
• رابط‌های برنامه‌نویسی کاربردی Gen Media: نقاط پایانی برای تولید رسانه با مدل‌های تخصصی ما مانند Imagen برای تولید تصویر و Veo برای تولید ویدیو . Gemini همچنین این قابلیت‌ها را به صورت داخلی دارد که می‌توانید با استفاده از رابط برنامه‌نویسی کاربردی generateContent به آنها دسترسی داشته باشید.
• APIهای پلتفرم: نقاط پایانی کاربردی که از قابلیت‌های اصلی مانند آپلود فایل‌ها و شمارش توکن‌ها پشتیبانی می‌کنند.

احراز هویت

تمام درخواست‌ها به API جمینی باید شامل یک هدر x-goog-api-key با کلید API شما باشند. با چند کلیک در Google AI Studio یکی ایجاد کنید.

در زیر نمونه‌ای از درخواست با کلید API موجود در هدر آمده است:

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"
          }
        ]
      }
    ]
  }'

برای دستورالعمل نحوه ارسال کلید خود به API با استفاده از SDK های Gemini، به راهنمای استفاده از کلیدهای API Gemini مراجعه کنید.

تولید محتوا

این نقطه پایانی اصلی برای ارسال اعلان‌ها به مدل است. دو نقطه پایانی برای تولید محتوا وجود دارد، تفاوت اصلی در نحوه دریافت پاسخ است:

• generateContent (REST) : یک درخواست دریافت می‌کند و پس از اینکه مدل کل تولید خود را به پایان رساند، یک پاسخ واحد ارائه می‌دهد.
• streamGenerateContent (SSE) : دقیقاً همان درخواست را دریافت می‌کند، اما مدل بخش‌هایی از پاسخ را همزمان با تولید، به صورت استریم برمی‌گرداند. این امر تجربه کاربری بهتری را برای برنامه‌های تعاملی فراهم می‌کند زیرا به شما امکان می‌دهد نتایج جزئی را فوراً نمایش دهید.

درخواست ساختار بدنه

بدنه درخواست یک شیء JSON است که برای هر دو حالت استاندارد و جریان یکسان است و از چند شیء اصلی ساخته شده است:

• شیء Content : نشان‌دهنده‌ی یک نوبت در یک مکالمه است.
• شیء Part : یک قطعه داده درون یک نوبت Content (مانند متن یا تصویر).
• inline_data ( Blob ): ظرفی برای بایت‌های خام رسانه و نوع MIME آنها.

در بالاترین سطح، بدنه درخواست شامل یک شیء 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
          ]
      }
    ]
  }'

ساختار بدن پاسخ دهنده

متن پاسخ برای هر دو حالت streaming و standard مشابه است، به جز موارد زیر:

• حالت استاندارد: بدنه پاسخ شامل نمونه‌ای از GenerateContentResponse است.
• حالت جریانی: بدنه پاسخ شامل جریانی از نمونه‌های GenerateContentResponse است.

در سطح بالا، بدنه پاسخ شامل یک شیء candidates است که فهرستی از اشیاء Candidate است. شیء Candidate شامل یک شیء Content است که پاسخ تولید شده از مدل را در خود جای داده است.

درخواست نمونه

مثال‌های زیر نشان می‌دهند که چگونه این اجزا برای انواع مختلف درخواست‌ها گرد هم می‌آیند.

فقط پیام متنی

یک اعلان متنی ساده شامل یک آرایه contents با یک شیء Content است. آرایه parts آن شیء، به نوبه خود، شامل یک شیء Part ) با یک فیلد text است.

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 تعریف می‌کنید. API از کل این تاریخچه به عنوان زمینه‌ای برای پاسخ بعدی استفاده می‌کند. role هر شیء Content باید بین 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 درون یک شیء Content برای ترکیب انواع مختلف داده‌ها (متن، تصویر، URI ویدیو و غیره) استفاده کنید.
• روش داده خود را انتخاب کنید:
  • برای رسانه‌های کوچک و مستقیماً جاسازی‌شده (مانند اکثر تصاویر)، از Part با inline_data استفاده کنید.
  • برای فایل‌های بزرگ‌تر یا فایل‌هایی که می‌خواهید در درخواست‌های مختلف دوباره استفاده کنید، از API فایل برای آپلود فایل استفاده کنید و آن را با بخش file_data ارجاع دهید.
• مدیریت تاریخچه مکالمات: برای برنامه‌های چت با استفاده از REST API، آرایه contents را با اضافه کردن اشیاء Content برای هر نوبت، به طور متناوب بین نقش‌های "user" و "model" بسازید. اگر از SDK استفاده می‌کنید، برای روش پیشنهادی برای مدیریت تاریخچه مکالمات به مستندات SDK مراجعه کنید.

نمونه‌های پاسخ

مثال‌های زیر نشان می‌دهند که چگونه این اجزا برای انواع مختلف درخواست‌ها گرد هم می‌آیند.

پاسخ فقط متنی

یک پاسخ متنی ساده شامل یک آرایه 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"
}

API زنده (BidiGenerateContent)

Live API یک API مبتنی بر WebSocket با وضعیت (stateful) برای استریمینگ دو جهته ارائه می‌دهد تا موارد استفاده استریمینگ بلادرنگ را فعال کند. برای جزئیات بیشتر می‌توانید راهنمای Live API و مرجع Live API را بررسی کنید.

مدل‌های تخصصی

علاوه بر خانواده مدل‌های Gemini، رابط برنامه‌نویسی نرم‌افزار Gemini، نقاط پایانی برای مدل‌های تخصصی مانند Imagen ، Lyria و مدل‌های تعبیه‌شده ارائه می‌دهد. می‌توانید این راهنماها را در بخش مدل‌ها بررسی کنید.

APIهای پلتفرم

بقیه نقاط پایانی، قابلیت‌های اضافی را برای استفاده با نقاط پایانی اصلی که تاکنون توضیح داده شده‌اند، فعال می‌کنند. برای کسب اطلاعات بیشتر، مباحث حالت دسته‌ای و API فایل را در بخش راهنماها بررسی کنید.

قدم بعدی چیست؟

اگر تازه شروع کرده‌اید، راهنماهای زیر را بررسی کنید که به شما در درک مدل برنامه‌نویسی Gemini API کمک می‌کنند:

• شروع سریع رابط برنامه‌نویسی Gemini
• راهنمای مدل جمینی

همچنین می‌توانید راهنماهای قابلیت‌ها را بررسی کنید که ویژگی‌های مختلف API Gemini را معرفی کرده و نمونه‌های کد ارائه می‌دهند:

• تولید متن
• ذخیره سازی متن
• جاسازی‌ها