استخدام مفاتيح Gemini API

لاستخدام 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.

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

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

interaction = client.interactions.create(
    model="gemini-3-flash-preview", 
    input="Explain how AI works in a few words"
)
print(interaction.steps[-1].content[0].text)

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

main();

# Specifies the API revision to avoid breaking changes when they become default
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -X POST \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "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، يمكنك استخدام الرموز المميّزة المؤقتة. تتضمّن هذه الرموز مخاطر أمنية أقل ويمكن أن تكون مناسبة للاستخدام في بيئات الإنتاج. يُرجى مراجعة دليل الرموز المميّزة المؤقتة لمزيد من المعلومات.

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

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

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

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

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

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

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

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