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

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

مفاتيح واجهة برمجة التطبيقات

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

بعد الحصول على مفتاح واجهة برمجة التطبيقات، تتوفّر لك الخيارات التالية للربط بواجهة Gemini 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. يجب استيراد المشاريع التي تريدها من خلال البحث عن الاسم أو رقم تعريف المشروع في مربّع الحوار استيراد المشاريع. للاطّلاع على قائمة كاملة بالمشاريع التي يمكنك الوصول إليها، انتقِل إلى Cloud Console.

إذا لم تكن قد استوردت أي مشاريع بعد، اتّبِع الخطوات التالية لاستيراد مشروع Google Cloud وإنشاء مفتاح:

1. انتقِل إلى Google AI Studio.
2. افتح لوحة البيانات من اللوحة الجانبية على يمين الصفحة.
3. اختَر المشاريع.
4. انقر على الزر استيراد المشاريع في صفحة المشاريع.
5. ابحث عن مشروع Google Cloud الذي تريد استيراده واختَره، ثم انقر على الزر استيراد.

بعد استيراد مشروع، انتقِل إلى صفحة مفاتيح واجهة برمجة التطبيقات من قائمة لوحة البيانات وأنشئ مفتاح واجهة برمجة تطبيقات في المشروع الذي استوردته للتو.

القيود

في ما يلي بعض القيود المفروضة على إدارة مفاتيح واجهة برمجة التطبيقات ومشاريع Google Cloud في Google AI Studio.

• يمكنك إنشاء 10 مشاريع كحد أقصى في كل مرة من صفحة المشاريع في Google AI Studio.
• يمكنك تسمية المشاريع والمفاتيح وإعادة تسميتها.
• تعرض صفحتَي مفاتيح واجهة برمجة التطبيقات والمشاريع 100 مفتاح و100 مشروع كحد أقصى.
• لا يتم عرض سوى مفاتيح واجهة برمجة التطبيقات التي لا تتضمّن أي قيود أو التي تقتصر على Generative Language API.

للحصول على إذن وصول إضافي لإدارة مشاريعك، انتقِل إلى Google Cloud Console.

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

في حال ضبطت متغيّر البيئة 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" \
  -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"
          }
        ]
      }
    ]
  }'

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

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

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

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

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

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

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

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

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

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