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

برای استفاده از Gemini API، به یک کلید API نیاز دارید. می توانید با چند کلیک در Google AI Studio یک کلید به صورت رایگان ایجاد کنید.

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

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

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

تنظیم کلید 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?key=$YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -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، مجوزهای یک کلید را محدود کنید. این امر آسیب احتمالی را در صورت نشت کلید به حداقل می رساند.

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