با استفاده از کلیدهای API Gemini

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

یک کلید API Gemini ایجاد یا مشاهده کنید

انواع کلید API: استاندارد در مقابل مجوز

کلیدهای API دسترسی به API جمینی را فراهم می‌کنند، اما ویژگی‌های امنیتی آنها متفاوت است. API جمینی در حال گذار از کلیدهای API استاندارد به کلیدهای مجوز برای بهبود امنیت است:

  • کلیدهای استاندارد API : درخواست‌ها را برای اهداف صدور صورتحساب و سهمیه‌بندی به یک پروژه Google Cloud مرتبط می‌کنند. کلیدهای استاندارد، تماس‌گیرنده را شناسایی نمی‌کنند، که این امر جزئیات مجوزها و کنترل دسترسی‌هایی را که می‌توانند پشتیبانی کنند، محدود می‌کند.
  • کلیدهای مجوز (auth) : مستقیماً به یک حساب سرویس Google Cloud متصل هستند. وقتی از یک کلید مجوز استفاده می‌کنید، درخواست‌های شما تحت هویت آن حساب سرویس متصل پردازش می‌شوند و کنترل دسترسی جزئی را امکان‌پذیر می‌کنند. کلیدهای مجوز به طور پیش‌فرض به API زبان مولد (Gemini API) محدود شده‌اند و اجرای سریع کلید نشت‌شده را ارائه می‌دهند که به سرعت استفاده از کلیدهای نشت‌شده شناسایی‌شده توسط سیستم‌های ما را متوقف می‌کند.

برای اطمینان از استفاده ایمن، رابط برنامه‌نویسی Gemini از کلیدهای استاندارد به کلیدهای احراز هویت تغییر خواهد کرد:

  • کلیدهای تأیید پیش‌فرض : تمام کلیدهای API جدید ایجاد شده در Google AI Studio به طور خودکار به عنوان کلیدهای تأیید ایجاد می‌شوند.
  • در ۱۹ ژوئن ۲۰۲۶ : رابط برنامه‌نویسی نرم‌افزار Gemini درخواست‌های دریافتی از کلیدهای استاندارد بدون محدودیت را رد خواهد کرد. کلیدهای استاندارد API که محدودیت‌های صریحی بر روی آنها اعمال شده است، به کار خود ادامه خواهند داد. این محدودیت از استفاده غیرمجاز از کلیدهایی که ممکن است به صورت عمومی به اشتراک گذاشته شوند یا به سایر سرویس‌ها مرتبط باشند، جلوگیری می‌کند.
  • در سپتامبر ۲۰۲۶ : رابط برنامه‌نویسی Gemini درخواست‌های دریافتی از کلیدهای استاندارد را رد خواهد کرد. برای جلوگیری از وقفه در سرویس، باید قبل از این تاریخ به کلیدهای احراز هویت مهاجرت کنید . حتماً قبل از سپتامبر ۲۰۲۶ به کلیدهای احراز هویت مهاجرت کنید.

مدیریت کلیدهای API در Google AI Studio

شما می‌توانید پروژه‌ها و کلیدهای خود را مستقیماً در Google AI Studio مدیریت کنید.

پروژه‌های ابری گوگل

هر کلید API جمینی با یک پروژه گوگل کلود مرتبط است. پروژه‌های گوگل کلود، صورتحساب، همکاران و مجوزها را مدیریت می‌کنند. گوگل هوش مصنوعی استودیو یک رابط کاربری سبک برای دسترسی به این پروژه‌ها فراهم می‌کند.

  • پروژه پیش‌فرض : اگر کاربر جدیدی هستید، Google AI Studio پس از پذیرش شرایط خدمات توسط شما، به‌طور خودکار یک پروژه پیش‌فرض Google Cloud و کلید API ایجاد می‌کند. می‌توانید با رفتن به نمای پروژه‌ها در داشبورد خود، نام این پروژه را تغییر دهید.
  • پروژه‌های موجود : اگر از قبل حساب Google Cloud دارید، AI Studio پروژه پیش‌فرض ایجاد نمی‌کند. در عوض، باید پروژه‌های موجود خود را وارد کنید.

وارد کردن پروژه‌ها

به طور پیش‌فرض، Google AI Studio تمام پروژه‌های Google Cloud شما را نمایش نمی‌دهد. شما باید پروژه‌هایی را که می‌خواهید استفاده کنید، وارد کنید:

  1. به استودیوی هوش مصنوعی گوگل بروید.
  2. از پنل سمت چپ، داشبورد را باز کنید و پروژه‌ها را انتخاب کنید.
  3. روی دکمه‌ی وارد کردن پروژه‌ها کلیک کنید.
  4. پروژه Google Cloud مورد نظر برای وارد کردن را جستجو و انتخاب کنید، سپس روی «وارد کردن» کلیک کنید.
  5. پس از وارد کردن، به صفحه کلیدهای API در داشبورد بروید تا یک کلید در آن پروژه ایجاد کنید.

عیب‌یابی مجوزهای ایجاد کلید

اگر دکمه‌ی «ایجاد کلید API» در دسترس نیست و پیام «شما مجوز ایجاد کلید در این پروژه را ندارید» را نمایش می‌دهد، مجوزهای IAM لازم را ندارید.

از مدیر پروژه یا سازمان Google Cloud خود بخواهید نقشی با مجوزهای زیر (مانند ویرایشگر پروژه) به شما اعطا کند:

  • resourcemanager.projects.get : به AI Studio اجازه می‌دهد تا پروژه را تأیید کند.
  • apikeys.keys.create : امکان تولید کلید را فراهم می‌کند.
  • serviceusage.services.enable : تضمین می‌کند که رابط برنامه‌نویسی کاربردی زبان مولد (Generative Language API) فعال است.
  • iam.serviceAccounts.create : برای ایجاد حساب سرویس لینک‌شده مورد نیاز است.
  • iam.serviceAccountApiKeyBindings.create : حساب کاربری سرویس را به کلید API متصل می‌کند.

اگر نمی‌توانید دسترسی مدیریتی داشته باشید، می‌توانید یک پروژه جدید Google Cloud ایجاد کنید که به سازمانی وابسته نباشد تا کلیدهای شما را تولید کند.

راه‌اندازی محیط شما

وقتی کلید را داشتید، محیط خود را طوری پیکربندی کنید که از آن به طور ایمن در برنامه‌هایتان استفاده کنید.

استفاده از متغیرهای محیطی (توصیه شده)

متغیر محیطی GEMINI_API_KEY یا GOOGLE_API_KEY را تنظیم کنید. کتابخانه‌های کلاینت API Gemini به طور خودکار این متغیرها را شناسایی و استفاده می‌کنند. اگر هر دو تنظیم شده باشند، GOOGLE_API_KEY اولویت دارد.

برای تنظیم متغیر، سیستم عامل خود را انتخاب کنید:

لینوکس/مک او اس - بش

بررسی کنید که آیا فایل پیکربندی bash دارید یا خیر:

~/.bashrc

اگر اینطور نیست، یکی ایجاد کنید و آن را باز کنید:

touch ~/.bashrc && open ~/.bashrc

دستور export را در انتهای فایل اضافه کنید:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

فایل را ذخیره کنید، سپس تغییرات را اعمال کنید:

source ~/.bashrc

macOS - Zsh

بررسی کنید که آیا فایل پیکربندی zsh دارید یا خیر:

~/.zshrc

اگر اینطور نیست، یکی ایجاد کنید و آن را باز کنید:

touch ~/.zshrc && open ~/.zshrc

دستور export را اضافه کنید:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

فایل را ذخیره کنید، سپس تغییرات را اعمال کنید:

source ~/.zshrc

ویندوز

  1. در نوار جستجوی ویندوز عبارت «Environment Variables» را جستجو کنید.
  2. در پنجره System Properties روی Environment Variables کلیک کنید.
  3. در زیر گزینه‌های User variables یا System variables ، روی New... کلیک کنید.
  4. نام متغیر را GEMINI_API_KEY و مقدار آن را برابر با کلید API خود قرار دهید.
  5. برای ذخیره، روی تأیید کلیک کنید. یک جلسه ترمینال جدید باز کنید تا متغیر بارگذاری شود.

کلید API را به طور صریح در کد ارائه دهید

شما می‌توانید کلید API را به طور صریح هنگام مقداردهی اولیه کلاینت ارسال کنید. فقط در صورتی این کار را انجام دهید که نمی‌توانید از متغیرهای محیطی استفاده کنید.

پایتون 

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how AI works in a few words"
)
print(response.text)

جاوا اسکریپت 

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

main();

برو 

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey:  "YOUR_API_KEY",
        Backend: genai.BackendGeminiAPI,
    })
    if err != nil {
        log.Fatal(err)
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3.5-flash",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

جاوا 

package com.example;

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().apiKey("YOUR_API_KEY").build();

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-3.5-flash",
            "Explain how AI works in a few words",
            null);

    System.out.println(response.text());
  }
}

استراحت 

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

مدیریت امنیت و رازداری

با کلید API Gemini خود مانند یک رمز عبور رفتار کنید. در صورت لو رفتن، دیگران می‌توانند سهمیه پروژه شما را مصرف کنند، هزینه‌های غیرمنتظره‌ای را متحمل شوند و به منابع خصوصی دسترسی پیدا کنند.

قوانین امنیتی حیاتی

  • کلیدها را محرمانه نگه دارید : هرگز کلیدهای API را در سیستم‌های کنترل منبع مانند Git بررسی نکنید.
  • هرگز کلیدها را در محیط تولید سمت کلاینت افشا نکنید : کلیدهای API را مستقیماً در برنامه‌های وب یا موبایل به صورت کد ثابت (hardcode) قرار ندهید. کلیدهای کامپایل شده در کد سمت کلاینت می‌توانند توسط کاربران استخراج شوند. برای ایمن‌سازی برنامه‌های سمت کلاینت، یک سرور پروکسی backend را برای برقراری تماس‌های واقعی API اجرا کنید.

بهترین شیوه‌های مدیریت مخفی

  • متغیرهای محیطی : کلیدها را از متغیرهای محیطی به جای فایل‌های پیکربندی بخوانید.
  • مدیر مخفی : برای محیط عملیاتی، کلیدهای خود را در یک فضای ذخیره‌سازی مخفی امن مانند Google Cloud Secret Manager ذخیره کنید.
  • هشدارهای صورتحساب : هشدارهای صورتحساب را در کنسول Google Cloud تنظیم کنید تا در صورت افزایش مصرف یا هزینه‌ها به شما اطلاع داده شود.

چک لیست واکنش به نشتی

اگر مشکوک هستید که کلید API شما فاش شده است:

  1. ایجاد یک کلید جدید : یک کلید جایگزین در Google AI Studio یا Cloud Console ایجاد کنید.
  2. برنامه خود را به‌روزرسانی کنید : کد خود را با استفاده از کلید جدید مستقر کنید.
  3. غیرفعال کردن یا حذف کلید لو رفته : پس از تأیید کلید جدید، کلید لو رفته را در کنسول ابری غیرفعال کنید. برای جلوگیری از خرابی برنامه، تا زمانی که کلید جدید کاملاً فعال نشده است، کلید قدیمی را حذف نکنید.
  4. بررسی میزان استفاده : گزارش‌های صورتحساب و میزان استفاده از API را در کنسول Google Cloud بررسی کنید تا فعالیت‌های غیرمجاز را شناسایی کنید.

محدود کردن و ایمن‌سازی کلیدهای شما

اضافه کردن محدودیت به کلیدهای API شما، آسیب‌های احتمالی در صورت لو رفتن کلید را به حداقل می‌رساند.

اعمال محدودیت‌های مبدا درخواست

محدودیت‌های مبدا، آدرس‌های IP، وب‌سایت‌ها یا برنامه‌هایی که می‌توانند از کلید شما استفاده کنند را محدود می‌کنند.

  1. به صفحه اعتبارنامه‌های کنسول گوگل کلود بروید.
  2. پروژه خود را انتخاب کنید و روی نام کلید API که می‌خواهید محدود کنید کلیک کنید.
  3. در زیر محدودیت‌های برنامه ، آدرس‌های IP (یا نوع محدودیت مناسب برای محیط خود) را انتخاب کنید.
  4. آدرس‌ها یا محدوده‌های IP مجاز را مشخص کنید، سپس روی ذخیره کلیک کنید.

ایمن‌سازی کلیدهای استاندارد API بدون محدودیت

برای ادامه استفاده از رابط برنامه‌نویسی کاربردی Gemini پس از ۱۹ ژوئن ۲۰۲۶، باید کلیدهای نامحدود خود را ایمن کنید.

کلید را فقط از طریق AI Studio به API Gemini محدود کنید

اگر فقط از کلید برای API Gemini استفاده می‌کنید، آن را مستقیماً در AI Studio ایمن کنید:

  1. در صفحه کلیدهای API در Google AI Studio ، کلیدهایی را که با برچسب Unrestricted مشخص شده‌اند، پیدا کنید.
  2. ماوس را روی برچسب نگه دارید و در کادر محاوره‌ای روی «افزودن محدودیت‌ها» کلیک کنید.
  3. گزینه «فقط محدود به API Gemini» را انتخاب کنید.
  4. برای تأیید، روی کلید محدود کردن کلیک کنید.

کلید را برای سایر سرویس‌ها از طریق کنسول ابری گوگل محدود کنید

اگر این کلید با سایر APIهای گوگل به اشتراک گذاشته شده است (توصیه نمی‌شود)، آن را در کنسول ابری محدود کنید. توجه: درخواست‌های API Gemini با استفاده از این کلید پس از اعمال این محدودیت‌ها، با شکست مواجه خواهند شد.

  1. از صفحه اعتبارنامه‌های کنسول ابری گوگل دیدن کنید.
  2. پروژه و کلید API را انتخاب کنید.
  3. در زیر محدودیت‌های API ، کلید محدود کردن را انتخاب کنید.
  4. از منوی کشویی، APIهایی را که می‌خواهید این کلید به آنها دسترسی داشته باشد، انتخاب کنید. API زبان مولد (Generative Language API) را انتخاب نکنید.
  5. روی ذخیره کلیک کنید. برای ادامه استفاده از API جمینی، یک کلید جداگانه و محدود در AI Studio ایجاد کنید.

کلیدهای غیرفعال مسدود شده

از ۷ مه ۲۰۲۶، رابط برنامه‌نویسی Gemini کلیدهای API نامحدودی را که برای مدت طولانی غیرفعال بوده‌اند، مسدود می‌کند. این کلیدها در AI Studio با برچسب Blocked نمایش داده می‌شوند. برای ادامه باید یک کلید جدید ایجاد کنید یا از یک کلید محدود موجود استفاده کنید.

مهاجرت به یک کلید احراز هویت

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

  1. به صفحه کلیدهای API استودیو AI بروید.
  2. ستون «نوع کلید» را بررسی کنید تا کلیدهای فهرست‌شده به عنوان «استاندارد» را شناسایی کنید.
  3. برای ایجاد یک کلید جدید، روی Create API key کلیک کنید. تمام کلیدهای جدید ایجاد شده در AI Studio به طور خودکار به عنوان کلیدهای احراز هویت ایجاد می‌شوند.
  4. کلید API احراز هویت جدید را کپی کنید.
  5. کد برنامه، متغیرهای محیطی و هرگونه پیکربندی استقرار خود را برای استفاده از کلید API احراز هویت جدید به‌روزرسانی کنید.
  6. برنامه خود را آزمایش کنید تا مطمئن شوید که با کلید جدید به درستی کار می‌کند.
  7. پس از تأیید، کلید ترافیک قدیمی خود را حذف یا لغو کنید تا از سوءاستفاده جلوگیری شود.

محدودیت‌ها

استودیوی هوش مصنوعی گوگل محدودیت‌های زیر را در مدیریت پروژه و کلید اعمال می‌کند:

  • شما می‌توانید حداکثر ۱۰ پروژه را همزمان از صفحه پروژه‌های استودیوی هوش مصنوعی گوگل ایجاد کنید.
  • صفحات کلیدهای API و پروژه‌ها حداکثر ۱۰۰ کلید و ۵۰ پروژه را نمایش می‌دهند.
  • فقط کلیدهای API که بدون محدودیت هستند یا به طور خاص به API زبان مولد (Gemini API) محدود شده‌اند، نمایش داده می‌شوند.

برای مدیریت پیشرفته پروژه یا تغییر کلیدها با سایر محدودیت‌ها، از صفحه اعتبارنامه‌های کنسول ابری گوگل استفاده کنید.