مرجع API جمینی

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

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

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

• تعاملات ( CreateInteraction ) (توصیه شده): استاندارد اولیه توصیه شده برای ساخت با 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-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"
          }
        ]
      }
    ]
  }'

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