این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

برای استفاده از API جمینی، به یک کلید API نیاز دارید. این صفحه نحوه ایجاد و مدیریت کلیدهای شما در Google AI Studio و همچنین نحوه تنظیم محیط برای استفاده از آنها در کد شما را شرح می‌دهد.

کلیدهای API

کلید API یک رشته رمزگذاری شده است که می‌توانید هنگام فراخوانی APIهای Google Cloud از آن استفاده کنید. می‌توانید تمام کلیدهای API Gemini خود را از صفحه کلیدهای API Google AI Studio ایجاد و مدیریت کنید.

پس از دریافت کلید API، گزینه‌های زیر برای اتصال به API جمینی در اختیار شماست:

تنظیم کلید API به عنوان یک متغیر محیطی
ارائه صریح کلید API شما

برای آزمایش اولیه، می‌توانید یک کلید API را به صورت کد ثابت (hard code) بنویسید، اما این کار باید موقتی باشد زیرا امن نیست. می‌توانید مثال‌هایی برای کد ثابت کلید API را در بخش «ارائه صریح کلید API» بیابید.

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

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

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

پروژه پیش‌فرض

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

پروژه‌های واردات

هر کلید API Gemini با یک پروژه Google Cloud مرتبط است. به طور پیش‌فرض، Google AI Studio تمام پروژه‌های Cloud شما را نشان نمی‌دهد. شما باید پروژه‌های مورد نظر خود را با جستجوی نام یا شناسه پروژه در کادر محاوره‌ای Import Projects وارد کنید. برای مشاهده لیست کاملی از پروژه‌هایی که به آنها دسترسی دارید، از Cloud Console دیدن کنید.

اگر هنوز هیچ پروژه‌ای را وارد نکرده‌اید، برای وارد کردن یک پروژه Google Cloud و ایجاد یک کلید، این مراحل را دنبال کنید:

به استودیوی هوش مصنوعی گوگل بروید.
داشبورد را از پنل سمت چپ باز کنید.
پروژه‌ها را انتخاب کنید.
دکمه‌ی «وارد کردن پروژه‌ها» را در صفحه‌ی پروژه‌ها انتخاب کنید.
پروژه Google Cloud مورد نظر برای وارد کردن را جستجو و انتخاب کنید و دکمه Import را بزنید.

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

محدودیت‌ها

محدودیت‌های مدیریت کلیدهای API و پروژه‌های Google Cloud در Google AI Studio به شرح زیر است.

شما می‌توانید حداکثر ۱۰ پروژه را همزمان از صفحه پروژه‌های استودیوی هوش مصنوعی گوگل ایجاد کنید.
شما می‌توانید پروژه‌ها و کلیدها را نامگذاری و تغییر نام دهید.
صفحات کلیدهای API و پروژه‌ها حداکثر ۱۰۰ کلید و ۵۰ پروژه را نمایش می‌دهند.
فقط کلیدهای API که هیچ محدودیتی ندارند یا محدود به API زبان مولد هستند نمایش داده می‌شوند.

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

تنظیم کلید API به عنوان یک متغیر محیطی

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

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

در اینجا نحوه تنظیم کلید API خود به صورت محلی به عنوان متغیر محیطی GEMINI_API_KEY با سیستم عامل‌های مختلف آورده شده است.

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

Bash یک پیکربندی رایج ترمینال لینوکس و macOS است. می‌توانید با اجرای دستور زیر بررسی کنید که آیا فایل پیکربندی برای آن دارید یا خیر:

~/.bashrc

اگر پاسخ «چنین فایل یا دایرکتوری وجود ندارد» است، باید این فایل را ایجاد کرده و با اجرای دستورات زیر آن را باز کنید، یا از zsh استفاده کنید:

touch ~/.bashrc
open ~/.bashrc

در مرحله بعد، باید با اضافه کردن دستور export زیر، کلید API خود را تنظیم کنید:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

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

source ~/.bashrc

macOS - Zsh

Zsh یک پیکربندی رایج ترمینال لینوکس و macOS است. می‌توانید با اجرای دستور زیر بررسی کنید که آیا فایل پیکربندی برای آن دارید یا خیر:

~/.zshrc

اگر پاسخ «چنین فایل یا دایرکتوری وجود ندارد» است، باید این فایل را ایجاد کرده و با اجرای دستورات زیر یا استفاده از bash آن را باز کنید:

touch ~/.zshrc
open ~/.zshrc

در مرحله بعد، باید با اضافه کردن دستور export زیر، کلید API خود را تنظیم کنید:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

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

source ~/.zshrc

ویندوز

در نوار جستجو عبارت «متغیرهای محیطی» را جستجو کنید.
تغییر تنظیمات سیستم را انتخاب کنید. ممکن است لازم باشد تأیید کنید که می‌خواهید این کار را انجام دهید.
در پنجره تنظیمات سیستم، روی دکمه‌ای با عنوان «متغیرهای محیطی» کلیک کنید.
در زیر گزینه‌های User variables (برای کاربر فعلی) یا System variables (برای همه کاربرانی که از دستگاه استفاده می‌کنند اعمال می‌شود)، روی New... کلیک کنید.
نام متغیر را GEMINI_API_KEY تعیین کنید. کلید API Gemini خود را به عنوان مقدار متغیر تعیین کنید.
برای اعمال تغییرات، روی تأیید کلیک کنید.
برای دریافت متغیر جدید، یک ترمینال جدید (cmd یا Powershell) باز کنید.

ارائه صریح کلید API

در برخی موارد، ممکن است بخواهید صریحاً یک کلید API ارائه دهید. برای مثال:

شما در حال انجام یک فراخوانی API ساده هستید و ترجیح می‌دهید کلید API را به صورت دستی وارد کنید.
شما می‌خواهید کنترل صریح داشته باشید بدون اینکه مجبور باشید به کشف خودکار متغیرهای محیطی توسط کتابخانه‌های Gemini API تکیه کنید.
شما از محیطی استفاده می‌کنید که متغیرهای محیطی در آن پشتیبانی نمی‌شوند (مثلاً وب) یا در حال فراخوانی REST هستید.

در زیر مثال‌هایی برای نحوه ارائه صریح کلید API آورده شده است:

پایتون

from google import genai

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

response = client.models.generate_content(
    model="gemini-2.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-2.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-2.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-2.5-flash",
            "Explain how AI works in a few words",
            null);

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

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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 خود را ایمن نگه دارید

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

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

هرگز کلیدهای API را به کنترل منبع (source control) ارسال نکنید. کلید API خود را در سیستم‌های کنترل نسخه مانند Git بررسی نکنید.
هرگز کلیدهای API را در سمت کلاینت نمایش ندهید. از کلید API خود مستقیماً در برنامه‌های وب یا موبایل در محیط تولید استفاده نکنید. کلیدها در کد سمت کلاینت (از جمله کتابخانه‌های جاوا اسکریپت/تایپ اسکریپت و فراخوانی‌های REST ما) قابل استخراج هستند.

بهترین شیوه‌ها

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

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

کلیدهای API

پس از دریافت کلید API، گزینه‌های زیر برای اتصال به API جمینی در اختیار شماست:

تنظیم کلید API به عنوان یک متغیر محیطی
ارائه صریح کلید API شما

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

پروژه پیش‌فرض

پروژه‌های واردات

به استودیوی هوش مصنوعی گوگل بروید.
داشبورد را از پنل سمت چپ باز کنید.
پروژه‌ها را انتخاب کنید.
دکمه‌ی «وارد کردن پروژه‌ها» را در صفحه‌ی پروژه‌ها انتخاب کنید.
پروژه Google Cloud مورد نظر برای وارد کردن را جستجو و انتخاب کنید و دکمه Import را بزنید.

محدودیت‌ها

محدودیت‌های مدیریت کلیدهای API و پروژه‌های Google Cloud در Google AI Studio به شرح زیر است.

شما می‌توانید حداکثر ۱۰ پروژه را همزمان از صفحه پروژه‌های استودیوی هوش مصنوعی گوگل ایجاد کنید.
شما می‌توانید پروژه‌ها و کلیدها را نامگذاری و تغییر نام دهید.
صفحات کلیدهای API و پروژه‌ها حداکثر ۱۰۰ کلید و ۵۰ پروژه را نمایش می‌دهند.
فقط کلیدهای API که هیچ محدودیتی ندارند یا محدود به API زبان مولد هستند نمایش داده می‌شوند.

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

تنظیم کلید API به عنوان یک متغیر محیطی

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

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

~/.bashrc

touch ~/.bashrc
open ~/.bashrc

در مرحله بعد، باید با اضافه کردن دستور export زیر، کلید API خود را تنظیم کنید:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

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

source ~/.bashrc

macOS - Zsh

~/.zshrc

touch ~/.zshrc
open ~/.zshrc

در مرحله بعد، باید با اضافه کردن دستور export زیر، کلید API خود را تنظیم کنید:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

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

source ~/.zshrc

ویندوز

در نوار جستجو عبارت «متغیرهای محیطی» را جستجو کنید.
تغییر تنظیمات سیستم را انتخاب کنید. ممکن است لازم باشد تأیید کنید که می‌خواهید این کار را انجام دهید.
در پنجره تنظیمات سیستم، روی دکمه‌ای با عنوان «متغیرهای محیطی» کلیک کنید.
در زیر گزینه‌های User variables (برای کاربر فعلی) یا System variables (برای همه کاربرانی که از دستگاه استفاده می‌کنند اعمال می‌شود)، روی New... کلیک کنید.
نام متغیر را GEMINI_API_KEY تعیین کنید. کلید API Gemini خود را به عنوان مقدار متغیر تعیین کنید.
برای اعمال تغییرات، روی تأیید کلیک کنید.
برای دریافت متغیر جدید، یک ترمینال جدید (cmd یا Powershell) باز کنید.

ارائه صریح کلید API

در برخی موارد، ممکن است بخواهید صریحاً یک کلید API ارائه دهید. برای مثال:

شما در حال انجام یک فراخوانی API ساده هستید و ترجیح می‌دهید کلید API را به صورت دستی وارد کنید.
شما می‌خواهید کنترل صریح داشته باشید بدون اینکه مجبور باشید به کشف خودکار متغیرهای محیطی توسط کتابخانه‌های Gemini API تکیه کنید.
شما از محیطی استفاده می‌کنید که متغیرهای محیطی در آن پشتیبانی نمی‌شوند (مثلاً وب) یا در حال فراخوانی REST هستید.

در زیر مثال‌هایی برای نحوه ارائه صریح کلید API آورده شده است:

پایتون

from google import genai

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

response = client.models.generate_content(
    model="gemini-2.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-2.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-2.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-2.5-flash",
            "Explain how AI works in a few words",
            null);

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

استراحت

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.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 خود را ایمن نگه دارید

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

هرگز کلیدهای API را به کنترل منبع (source control) ارسال نکنید. کلید API خود را در سیستم‌های کنترل نسخه مانند Git بررسی نکنید.
هرگز کلیدهای API را در سمت کلاینت نمایش ندهید. از کلید API خود مستقیماً در برنامه‌های وب یا موبایل در محیط تولید استفاده نکنید. کلیدها در کد سمت کلاینت (از جمله کتابخانه‌های جاوا اسکریپت/تایپ اسکریپت و فراخوانی‌های REST ما) قابل استخراج هستند.

بهترین شیوه‌ها

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

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