دليل إعداد Gemini API: AI Studio والمفتاح وأول استدعاء (2026)

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

تسير هذه المقالة وفق ترتيب الربط الفعلي: التمييز بين AI Studio وVertex AI، ثم إنشاء المفتاح وتثبيت SDK وإرسال طلبات curl وPython، ثم معالجة تسمية الطرازات والتعليمات النظامية والبث والإعدادات الأمنية، وأخيرًا الأسباب الشائعة للأخطاء 400 و403 و429 وقائمة أمان المفاتيح.

ملاحظة: Google وGemini علامتان تجاريتان مملوكتان لشركة Google LLC. قد تتغير أسماء الطرازات والحصص المجانية وقواعد الفوترة، وتعتمد هذه المقالة على الإجراءات الشائعة في أكتوبر 2026؛ والمرجع هو وثائق Google الرسمية وصفحة الأسعار.

أولًا: التمييز بين AI Studio وVertex AI

لـ Gemini API مدخلان شائعان، يختلفان في نظام الحساب وطريقة الإدارة، ويؤدي اختيار المدخل الخطأ إلى إعادة العمل في الصلاحيات أو التسوية.

وجه المقارنة	Google AI Studio	Vertex AI
المدخل	لوحة تحكم في المتصفح، موجهة للمطورين للتجربة السريعة	لوحة تحكم Google Cloud، موجهة للاستخدام المؤسسي
متطلبات الحساب	يكفي حساب Google للبدء	مشروع Cloud وحساب فوترة وصلاحيات IAM
بيانات الاعتماد	مفتاح API يُنشأ في AI Studio	حساب خدمة أو مفتاح مضبوط مع IAM
الفوترة	فئة مجانية وفئة مدفوعة	فوترة حسب مشروع Cloud
المنطقة والبيانات	وفق شروط AI Studio	مناطق اختيارية، ضمن شروط Cloud وإعدادات المشروع
الحالات المناسبة	النماذج الأولية والتعلم والتحقق صغير النطاق	أنظمة الإنتاج والفرق ذات متطلبات التدقيق والصلاحيات العالية

يستخدم المطورون الأفراد والفرق الصغيرة عادةً AI Studio لتشغيل المسار أولًا؛ وعندما تظهر متطلبات العقود ومناطق البيانات والتدقيق الموحد، يُقيَّم Vertex AI. لا تخلط بين مفاتيح الجانبين وحصصه وفواتيره، ولا تستخدم مفتاح AI Studio لاستدعاء واجهات Vertex AI.

ثانيًا: إنشاء أول مفتاح API

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

يوفر AI Studio فئة مجانية للتجربة، وتتغير الطرازات المتاحة ومعدلات الطلبات والحصص بحسب الحساب والفترة؛ وبعد تفعيل الفوترة في مشروع Cloud المرتبط يمكن الانتقال إلى الفئة المدفوعة. لا تعتبر أرقام الحصص الواردة في مقالات قديمة التزامًا حاليًا؛ فالمرجع هو ما تعرضه لوحة التحكم فعليًا والوثائق الرسمية.

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

ثالثًا: تثبيت SDK وإرسال أول طلب

يُنصح باستخدام Python 3.10 أو أحدث، وتثبيت SDK الرسمي داخل بيئة افتراضية.

python3 -m venv .venv
source .venv/bin/activate
pip install -U google-genai
export GEMINI_API_KEY="مفتاحك"

استخدم curl أولًا لاستبعاد عوامل SDK. استبدل معرّف الطراز بعنصر نائب، واحصل على الاسم الفعلي من قائمة الطرازات أو صفحة الأسعار.

curl "https://generativelanguage.googleapis.com/v1beta/models/<معرّف-الطراز>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "اشرح في جملة واحدة ما هي بوابة API"}]}
    ],
    "generationConfig": {"maxOutputTokens": 256, "temperature": 0.7}
  }'

بعد عودة curl بالرمز 200، انتقل إلى Python SDK:

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="<معرّف-الطراز>",
    contents="اشرح في جملة واحدة ما هي بوابة API",
)
print(resp.text)

يجب كتابة معرّف الطراز كاملًا في model، لا اسم السلسلة فقط. تختلف أنواع الإدخال والمعاملات المدعومة بين الطرازات، ويظهر الخطأ في صورة 400 أو 404 عند الكتابة الخاطئة.

رابعًا: تسمية الطرازات والتعليمات النظامية ومعاملات التوليد

يتكون معرّف طراز Gemini عادةً من السلسلة والإصدار. الطريقة الأكثر أمانًا هي استعلام قائمة الطرازات المتاحة للحساب الحالي أولًا:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

لا تخمّن الطرازات غير المدرجة في القائمة. عند الاختيار، وزّع المهام: استخدم فئة الاستجابة المنخفضة للمهام الخفيفة، وارفع الفئة في الاستدلال المعقد والمستندات الطويلة؛ وتُراجع الفئات والأسعار في صفحة الأسعار.

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

تُستخدم التعليمات النظامية لتثبيت الدور وقواعد الإخراج، وتناسب الترجمة والاستخراج وخدمة العملاء:

resp = client.models.generate_content(
    model="<معرّف-الطراز>",
    contents="ترجم هذه الجملة إلى الإنجليزية: تم الربط بنجاح",
    config={"system_instruction": "أنت مترجم وثائق تقنية، وأخرج الترجمة فقط."},
)

تشمل معاملات التوليد الشائعة temperature وmaxOutputTokens وtopP. عند الحاجة إلى نتائج مهيكلة، يمكن طلب JSON من الطراز ثم تحليله والتحقق منه في الكود؛ لا تفترض التزام الطراز بالتنسيق دائمًا، واكتب مسبقًا منطق إعادة المحاولة والحل الاحتياطي.

خامسًا: البث والإعدادات الأمنية

يناسب البث واجهات المحادثة والإجابات الطويلة. في واجهة REST أضف :streamGenerateContent بعد اسم الدالة مع alt=sse، وفي Python SDK استخدم generate_content_stream:

for chunk in client.models.generate_content_stream(
    model="<معرّف-الطراز>",
    contents="اشرح مفهوم تحديد المعدل في ثلاث نقاط",
):
    print(chunk.text, end="")

يمكن ضبط الإعدادات الأمنية حسب الفئة لرفع أو خفض حدود الاعتراض، وتشمل الفئات الشائعة التحرش والكراهية والمحتوى الجنسي والمحتوى الخطير. تناسب الحدود الافتراضية معظم الأعمال؛ أما خفض الاعتراض فيوسع نطاق المحتوى ويحتاج إلى تقييم وفق سياسة المنتج والتشريعات المحلية. لا تعطّل الإعدادات الأمنية بالكامل لمجرد «اجتياز الاختبار»، خصوصًا في المنتجات الموجهة للجمهور.

سادسًا: كيفية تشخيص 400 و403 و429

رمز الحالة	الأسباب الشائعة	اتجاه المعالجة
400	خطأ في بنية JSON، أو معامل غير مدعوم، أو عدم تطابق معرّف الطراز مع الواجهة	راجع جسم الطلب حقلًا حقلًا، وابدأ بأصغر طلب
403	مفتاح غير صالح أو مقيد، أو API غير مفعّل، أو قيود مشروع أو منطقة	جرّب مفتاحًا آخر، وافحص صلاحيات المشروع وحالة الحساب
404	خطأ في كتابة معرّف الطراز، أو إصدار أو مسار غير صحيح	راجع قائمة الطرازات، وتأكد من `v1beta` واسم الدالة
429	استنفاد الحصة المجانية، أو كثرة الطلبات في الدقيقة، أو ارتفاع التزامن	تراجع أسي مع إعادة المحاولة، وخفض التزامن، وتقييم الفئة المدفوعة
500/503	عطل مؤقت في الخادم	إعادة محاولة محدودة، ثم خفض المستوى أو تبديل القناة عند الاستمرار

لا تعد إرسال الطلب فورًا عند 429. الطريقة الصحيحة هي التراجع مع تشويش عشوائي، وضبط حد أقصى للمحاولات، وتسجيل الطلبات الفاشلة. تكون حدود المعدل في الفئة المجانية أضيق عادةً، وينبغي ترتيب اختبارات الضغط والمهام الدفعية بشكل منفصل.

سابعًا: قائمة أمان المفاتيح

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

ثامنًا: ربط Gemini عبر مدخل متوافق مع OpenAI

إذا كان لدى الفريق OpenAI SDK ومجموعة كود استدعاء قائمة، فيمكن استخدام المدخل المتوافق مع OpenAI في بوابة ZSQH AI، وعنوان Base URL هو https://ai.zhongshangqihang.com/v1، مع تغيير ثلاثة مواضع فقط: base_url وapi_key وmodel:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="<اسم طراز Gemini من صفحة الأسعار>",
    messages=[{"role": "user", "content": "أجب بكلمة OK فقط"}],
)
print(resp.choices[0].message.content)

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

الأسئلة الشائعة

هل يوفر Gemini API حصة مجانية؟

يوفر AI Studio فئة مجانية، لكن الطرازات المتاحة والمعدلات والحصص قابلة للتغيير، وقد تختلف شروط البيانات عن الفئة المدفوعة. يمكن استخدام الفئة المجانية للتحقق من النموذج الأولي، ويُنصح بإعادة تقييم الحصص والتكلفة على الفئة المدفوعة قبل التشغيل الرسمي.

ماذا أفعل إذا تسرب مفتاح API؟

ألغِ المفتاح أو استبدله في لوحة التحكم أولًا، ثم راجع سجلات الاستخدام لتحديد نطاق الاستدعاءات غير الطبيعية، وأخيرًا افحص قناة التسريب. حذف المفتاح من الكود لا يكفي؛ إذ تُعامل بيانات الاعتماد المسربة على أنها غير صالحة.

هل يمكن استدعاء Gemini API مباشرة من الشبكات المحلية؟

تختلف جودة المسار بحسب المنطقة والمشغل، وقد تحدث مهل انتهاء أو فشل في الاتصال. من الممارسات الشائعة تشغيل الطلبات على خادم يمكن الوصول إليه باستقرار، أو استخدام بوابة تدعم واجهة متوافقة مع OpenAI؛ وتُراجع القيود الفعلية وفق المسار الحقيقي والوثائق الرسمية.

لماذا يعمل curl بينما يخطئ Python SDK؟

تحقق أولًا من إصدار SDK والاعتماديات، ثم من كتابة model وإعدادات الوكيل واتساق متغيرات البيئة. عند ظهور 404 من SDK، ركّز على معرّف الطراز ومسار الواجهة، ولا تغيّر عدة متغيرات في وقت واحد.

هل يمكن استدعاء Gemini API باستخدام OpenAI SDK مباشرة؟

توفر Google مدخلًا متوافقًا مع OpenAI، وتوفر البوابات المحلية طبقة توافق مماثلة، لكن نطاق دعم المعاملات يختلف. يجب التحقق من الوسائط المتعددة واستدعاء الأدوات والإخراج المهيكل بطلبات حقيقية، لا افتراض التكافؤ الكامل.

الخطوة التالية

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

قراءات ذات صلة: