Gemini API reference

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

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

Gemini API حول نقاط پایانی اصلی زیر سازماندهی شده است:

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

احراز هویت

همه درخواست‌ها به API Gemini باید شامل یک هدر 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 با استفاده از Gemini SDK، به راهنمای استفاده از کلیدهای Gemini API مراجعه کنید.

تولید محتوا

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

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

ساختار بدن پاسخگو

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

در سطح بالا، بدنه پاسخ حاوی یک شیء 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 استفاده کنید.
    • برای فایل‌های بزرگ‌تر یا فایل‌هایی که می‌خواهید مجدداً در درخواست‌ها استفاده کنید، از File 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"
}

Live API (BidiGenerateContent) WebSockets API

Live API یک API مبتنی بر WebSocket حالت‌پذیر را برای پخش جریانی دوطرفه ارائه می‌کند تا موارد استفاده از جریان در زمان واقعی را فعال کند. برای جزئیات بیشتر می‌توانید راهنمای Live API و مرجع Live API را مرور کنید.

مدل های تخصصی

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

API های پلتفرم

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

بعدش چی

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

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