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

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

إنشاء مفتاح Gemini API أو عرضه

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

يمكنك إنشاء جميع مفاتيح Gemini 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. يُرجى الرجوع إلى قسم استيراد المشاريع للاطّلاع على التعليمات.

المشروع التلقائي

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

استيراد المشاريع

يرتبط كل مفتاح من مفاتيح Gemini API بمشروع على Google Cloud. لا يعرض Google AI Studio تلقائيًا جميع مشاريعك على Google 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 مفتاح و50 مشروعًا كحد أقصى.
• لا يتم عرض سوى مفاتيح واجهة برمجة التطبيقات التي لا تتضمّن أي قيود أو التي تقتصر على Generative Language API.

للحصول على إذن وصول إضافي لإدارة مشاريعك، بما في ذلك تعديل مفاتيح واجهة برمجة التطبيقات وتقييدها، انتقِل إلى صفحة بيانات الاعتماد في Google Cloud Console. في Cloud Console، يمكنك اختيار مشروعك والنقر على مفتاح حالي لواجهة برمجة التطبيقات، ثم تقييده باستخدام Generative Language 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-3.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-3.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-3.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-3.5-flash",
            "Explain how AI works in a few words",
            null);

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.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 ككلمة مرور. إذا تم اختراق المفتاح، يمكن للآخرين استخدام حصة مشروعك وتحمُّل الرسوم (إذا كانت الفوترة مفعّلة) والوصول إلى بياناتك الخاصة، مثل الملفات.

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

• الحفاظ على سرية المفاتيح: قد تتمكّن مفاتيح Gemini API من الوصول إلى البيانات الحسّاسة التي يعتمد عليها تطبيقك.

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

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

• تقييد الوصول: يمكنك تقييد استخدام مفتاح واجهة برمجة التطبيقات بعناوين IP أو عناوين HTTP أو تطبيقات Android/iOS معيّنة، إن أمكن.

• تقييد الاستخدام: لا تفعِّل سوى واجهات برمجة التطبيقات الضرورية لكل مفتاح.

• إجراء عمليات تدقيق منتظمة: عليك تدقيق مفاتيح واجهة برمجة التطبيقات بانتظام وتغييرها بشكلٍ دوري.

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

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

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

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

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

تأمين مفاتيح واجهة برمجة التطبيقات غير المقيّدة

تكون مفاتيح واجهة برمجة التطبيقات غير المقيّدة عُرضة للجهات المُسيئة والاستخدام غير المصرّح به. اعتبارًا من 19 يونيو 2026، ولتحسين الأمان، ستتوقف Gemini API عن دعم مفاتيح الزيارات غير المقيّدة.

هذا يعني أنّ طلباتك من Gemini API ستفشل إذا لم تتّخذ أي إجراء.

لمواصلة استخدام Gemini API بدون انقطاع، عليك تأمين مفاتيح الزيارات من خلال إضافة قيود في AI Studio.

في aistudio.google.com/api-keys، ستظهر لك لافتة لإعلامك عندما تكون مفاتيح واجهة برمجة التطبيقات غير مقيّدة. يمكنك الاطّلاع على المفاتيح غير المقيّدة واستخدام الخدمة خلال آخر 90 يومًا.

بالنسبة إلى المفاتيح غير المقيّدة، عليك اختيار أحد الخيارَين التاليَين:

• استخدام المفتاح لـ Gemini API فقط
• استخدام المفتاح لغير Gemini API

تقييد المفتاح باستخدام Gemini API فقط

إذا أردت تقييد المفتاح باستخدام Gemini API فقط، عليك تأمين مفتاحك في AI Studio من خلال النقر على الزر تقييد الاستخدام بـ Gemini API.

تقييد المفتاح لغير Gemini API

إذا أردت تقييد المفتاح لغير Gemini API:

1. انتقِل إلى صفحة بيانات الاعتماد في Google Cloud Console.
2. تأكَّد من اختيار المشروع بشكلٍ صحيح.
3. اختَر مفتاح واجهة برمجة تطبيقات.
4. وسِّع القائمة المنسدلة قيود واجهة برمجة التطبيقات ، وطبِّق قيود الخدمة على مفتاح واجهة برمجة التطبيقات.

إذا أردت تعديل المفاتيح التي تتضمّن قيودًا حالية أو قيودًا تمت إضافتها حديثًا، انتقِل إلى الـ Google Cloud Console.

المفاتيح المحظورة

اعتبارًا من 7 مايو 2026، ستحظر Gemini API مفاتيح واجهة برمجة التطبيقات غير المقيّدة التي لم يتم استخدامها لفترة طويلة. سيظهر للمستخدمين الذين لم يستخدموا هذه المفاتيح العلامة محظور لمفاتيحهم على aistudio.google.com/api-keys، وسيحتاجون إلى إنشاء مفتاح جديد أو استخدام مفتاح بديل مقيّد لمواصلة استخدام Gemini API.

تحديد المشاكل وحلّها في إنشاء مفتاح واجهة برمجة التطبيقات

في Google AI Studio، قد يظهر الزر إنشاء مفتاح واجهة برمجة التطبيقات غير متاح، مع الرسالة: "ليس لديك إذن بإنشاء مفتاح في هذا المشروع".

يحدث ذلك عندما لا تتوفّر لديك الأذونات اللازمة في المشروع لإنشاء مفتاح جديد:

• resourcemanager.projects.get: يسمح لـ AI Studio بالتحقّق من وجود المشروع.
• apikeys.keys.create: يسمح بإنشاء مفتاح واجهة برمجة التطبيقات نفسه.
• serviceusage.services.enable: مطلوب لضمان تفعيل Gemini API في المشروع.
• iam.serviceAccounts.create: يتطلب كل مفتاح جديد لواجهة برمجة التطبيقات الآن حساب خدمة مرتبطًا يتم إنشاؤه عند إنشاء مفتاح واجهة برمجة التطبيقات.
• iam.serviceAccountApiKeyBindings.create: مطلوب لربط حساب الخدمة الذي تم إنشاؤه حديثًا بمفتاح واجهة برمجة التطبيقات.

لإصلاح أذوناتك، اطلب من مشرف مشروعك أو مشرف مؤسستك (إذا كان المشروع يتبع لمؤسسة) منحك دورًا يتضمّن الأذونات المذكورة أعلاه (مثل "محرِّر المشروع" أو دور مخصّص).

إذا لم يكن لديك إذن وصول إداري إلى مشروع، يمكنك إنشاء مشروع جديد غير مرتبط بمؤسسة لإنشاء مفاتيحك.