استخدام مفاتيح واجهة برمجة التطبيقات في Gemini

لاستخدام Gemini API، يجب أن يكون لديك مفتاح واجهة برمجة تطبيقات. يمكنك إنشاء مفتاح مجانًا ببضع نقرات في Google AI Studio.

بعد الحصول على مفتاح واجهة برمجة التطبيقات، تتوفّر لك الخيارات التالية للربط بواجهة Gemini API:

• ضبط مفتاح واجهة برمجة التطبيقات كمتغيّر بيئة
• تقديم مفتاح واجهة برمجة التطبيقات بشكلٍ صريح

لإجراء الاختبار الأوّلي، يمكنك تضمين مفتاح واجهة برمجة التطبيقات في الرمز البرمجي، ولكن يجب أن يكون ذلك مؤقتًا فقط لأنّه غير آمن. يمكنك العثور على أمثلة حول الترميز الثابت لمفتاح واجهة برمجة التطبيقات في قسم توفير مفتاح واجهة برمجة التطبيقات بشكل صريح.

ضبط مفتاح واجهة برمجة التطبيقات كمتغيّر بيئة

في حال ضبطت متغيّر البيئة GEMINI_API_KEY أو GOOGLE_API_KEY، سيختار العميل مفتاح واجهة برمجة التطبيقات تلقائيًا عند استخدام إحدى مكتبات Gemini API. ننصحك بضبط أحد المتغيرَين فقط، ولكن في حال ضبط كليهما، ستكون الأولوية للمتغير GOOGLE_API_KEY.

إذا كنت تستخدم REST API أو JavaScript على المتصفّح، عليك تقديم مفتاح واجهة برمجة التطبيقات بشكل صريح.

في ما يلي كيفية ضبط مفتاح واجهة برمجة التطبيقات محليًا كمتغيّر بيئة 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

توفير مفتاح واجهة برمجة التطبيقات بشكلٍ صريح

في بعض الحالات، قد تحتاج إلى تقديم مفتاح واجهة برمجة التطبيقات بشكل صريح. على سبيل المثال:

• إذا كنت بصدد إجراء طلب بسيط من واجهة برمجة التطبيقات وتفضّل الترميز الثابت لمفتاح واجهة برمجة التطبيقات
• تريد التحكّم بشكل صريح بدون الاعتماد على الاكتشاف التلقائي لمتغيرات البيئة من خلال مكتبات Gemini API
• أنت تستخدم بيئة لا تتوافق مع متغيرات البيئة (مثل الويب) أو تجري طلبات REST.

في ما يلي أمثلة على كيفية تقديم مفتاح واجهة برمجة التطبيقات بشكلٍ صريح:

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"
          }
        ]
      }
    ]
  }'

الحفاظ على أمان مفتاح واجهة برمجة التطبيقات

تعامَل مع مفتاح Gemini API كما لو كان كلمة مرور. في حال تعرّض حسابك للاختراق، يمكن للآخرين استخدام حصة مشروعك، وتحمّل الرسوم (في حال تفعيل الفوترة)، والوصول إلى بياناتك الخاصة، مثل الملفات.

قواعد الأمان المهمة

• لا ترسِل مفاتيح واجهة برمجة التطبيقات إلى نظام التحكّم بالمصادر. لا تُدرِج مفتاح واجهة برمجة التطبيقات في أنظمة التحكم في الإصدارات، مثل Git.

• لا تعرض مفاتيح واجهة برمجة التطبيقات على جهة العميل أبدًا. لا تستخدِم مفتاح واجهة برمجة التطبيقات مباشرةً في تطبيقات الويب أو الأجهزة الجوّالة في مرحلة الإنتاج. يمكن استخراج المفاتيح من الرمز البرمجي من جهة العميل (بما في ذلك مكتبات JavaScript/TypeScript وطلبات REST).

أفضل الممارسات

• استخدام طلبات من جهة الخادم مع مفاتيح واجهة برمجة التطبيقات الطريقة الأكثر أمانًا لاستخدام مفتاح واجهة برمجة التطبيقات هي طلب Gemini API من تطبيق من جهة الخادم حيث يمكن الحفاظ على سرية المفتاح.

• استخدام رموز مميزة مؤقتة للوصول من جهة العميل (Live API فقط): للوصول مباشرةً إلى Live API من جهة العميل، يمكنك استخدام رموز مميزة مؤقتة. وتتضمّن مخاطر أمان أقل ويمكن أن تكون مناسبة للاستخدام في مرحلة الإنتاج. راجِع دليل الرموز المميزة المؤقتة لمزيد من المعلومات.

• ننصحك بإضافة قيود إلى مفتاحك: يمكنك الحدّ من أذونات المفتاح من خلال إضافة قيود على مفتاح واجهة برمجة التطبيقات. ويحدّ هذا الإجراء من الأضرار المحتملة في حال تسرُّب المفتاح.

للاطّلاع على بعض أفضل الممارسات العامة، يمكنك أيضًا مراجعة مقالة الدعم هذه.