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

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

کلیدهای API

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

هنگامی که یک کلید API دارید، گزینه های زیر را برای اتصال به Gemini API دارید:

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

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

پروژه های Google Cloud

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

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

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

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

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

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

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

محدودیت ها

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

• شما می توانید حداکثر 10 پروژه را در یک زمان از صفحه پروژه های استودیو گوگل AI ایجاد کنید.
• می توانید پروژه ها و کلیدها را نامگذاری و تغییر نام دهید.
• کلیدهای API و صفحات پروژه ها حداکثر 100 کلید و 50 پروژه را نمایش می دهند.
• فقط کلیدهای API که هیچ محدودیتی ندارند یا محدود به API زبان تولیدی هستند نمایش داده می شوند.

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

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

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

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

در اینجا نحوه تنظیم کلید API به صورت محلی به عنوان متغیر محیطی GEMINI_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 ارائه دهید. به عنوان مثال:

• شما در حال انجام یک تماس ساده 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 خود را ایمن نگه دارید

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

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

• هرگز کلیدهای API را به کنترل منبع متعهد نکنید. کلید API خود را در سیستم های کنترل نسخه مانند Git بررسی نکنید.

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

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

• استفاده از تماس‌های سمت سرور با کلیدهای API ایمن‌ترین راه برای استفاده از کلید API تماس با Gemini API از یک برنامه سمت سرور است که در آن می‌توان کلید را محرمانه نگه داشت.

• استفاده از نشانه های زودگذر برای دسترسی سمت سرویس گیرنده (فقط Live API): برای دسترسی مستقیم سمت کلاینت به Live API، می توانید از نشانه های زودگذر استفاده کنید. آنها با خطرات امنیتی کمتری همراه هستند و می توانند برای استفاده در تولید مناسب باشند. راهنمای نشانه های زودگذر را برای اطلاعات بیشتر مرور کنید.

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

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