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

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

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

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

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

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

برای اطمینان از استفاده ایمن، Gemini API از کلیدهای استاندارد به کلیدهای اصالت‌سنجی منتقل خواهد شد:

• کلیدهای اصالت‌سنجی پیش‌فرض: از ۲۸ مه ۲۰۲۶، همه کلیدهای API جدید ایجادشده در Google AI Studio به‌طور خودکار به‌عنوان کلیدهای اصالت‌سنجی ایجاد می‌شوند.
• کلیدهای بدون محدودیت رد شد: «میانای برنامه‌سازی کاربردی Gemini» درخواست‌های کلیدهای استاندارد بدون محدودیت را رد می‌کند. کلیدهای استاندارد API که محدودیت‌های صریح دارند همچنان کار می‌کنند. این محدودیت از استفاده غیرمجاز از کلیدهایی که ممکن است به‌صورت عمومی هم‌رسانی شوند یا به سرویس‌های دیگر پیوند داده شوند جلوگیری می‌کند.

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

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

پروژه‌های Google Cloud

هر کلید Gemini API با یک پروژه Google Cloud مرتبط است. پروژه‌های Google Cloud صورت‌حساب، همیاران، و اجازه‌ها را مدیریت می‌کنند. ‫Google AI Studio میانای سبکی برای دسترسی به این پروژه‌ها ارائه می‌دهد.

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

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

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

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

عیب‌یابی کردن اجازه‌های ایجاد کلید

اگر دکمه ایجاد کلید میانای برنامه‌سازی کاربردی دردسترس نیست و پیام زیر را نمایش می‌دهد: «اجازه ایجاد کلید در این پروژه را ندارید»، اجازه‌های 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 جدیدی ایجاد کنید که با سازمانی مرتبط نباشد تا کلیدهایتان را تولید کنید.

ایجاد کلید در کنسول Google Cloud

‫Google AI Studio فقط کلیدهایی را نمایش می‌دهد که بدون محدودیت باشند یا به Gemini API محدود شده باشند. اگر نمی‌توانید از «استودیو هوش مصنوعی» استفاده کنید یا می‌خواهید همه کلیدهای API خود را در یک مکان مدیریت کنید، مستندات Cloud را درباره ایجاد کلید API دنبال کنید. برای ایجاد کلید Gemini API، باید آن را به حساب سرویس پیوند دهید.

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

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

گزینه ۱: استفاده از متغیرهای محیطی (توصیه‌شده)

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

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

~/.bashrc

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

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.bashrc

~/.zshrc

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

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.zshrc

گزینه ۲: ارائه کلید API به‌صورت صریح در کد

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

from google import genai

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

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)

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

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

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.output_text);
}

main();

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = Client.builder().apiKey("YOUR_API_KEY").build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain how AI works in a few sentences."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

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

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Explain how AI works in a few sentences."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain how AI works in a few words"
  }'

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

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

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

• محرمانه نگه داشتن کلیدها: هرگز کلیدهای API را در سیستم‌های کنترل منبع مانند Git بررسی نکنید.
• هرگز کلیدها را در سمت کارخواه در دسته هدف تولید آشکار نکنید: کلیدهای API را مستقیماً در برنامه‌های وب یا تلفن همراه کدبندی سخت نکنید. کاربران می‌توانند کلیدهای گردآوری‌شده در کد سمت مشتری را استخراج کنند. برای ایمن کردن برنامه‌های سمت کارخواه، سرور پروکسی زیرینه را برای انجام فراخوان‌های واقعی API اجرا کنید.

روال‌های مطلوب مدیریت رمز

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

بازبینه پاسخ به نشتی

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

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

محدود کردن و ایمن کردن کلیدها

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

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

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

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

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

برای ادامه استفاده از «میانای برنامه‌سازی کاربردی Gemini»، باید همه کلیدهای بدون محدودیت را ایمن کنید.

روش A: کلید را فقط به Gemini API (استودیو هوش مصنوعی) محدود کنید

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

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

روش ب: محدود کردن کلید برای سرویس‌های دیگر (کنسول Google Cloud)

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

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

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

از ۷ مه ۲۰۲۶، «میانای برنامه‌سازی کاربردی Gemini» کلیدهای میانای برنامه‌سازی کاربردی بدون محدودیت را که برای مدت طولانی غیرفعال بوده‌اند مسدود می‌کند. این کلیدها برچسب مسدودشده را در «استودیوِ هوش مصنوعی» نشان می‌دهند. برای ادامه باید کلید جدیدی تولید کنید یا از کلید محدودشده موجود استفاده کنید.

انتقال به کلید اصالت‌سنجی

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

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

محدودیت‌ها

‫Google AI Studio محدودیت‌های زیر را برای مدیریت پروژه و کلید اعمال می‌کند:

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

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