دليل المبتدئين لاستخدام Google Gemini 3 API: سحر الذكاء الاصطناعي

إذا كنت تتابع تطورات الذكاء الاصطناعي في عام 2025، فمن المحتمل أنك سمعت الكثير من الضجة حول Google Gemini 3، وهو نموذج الذكاء الاصطناعي متعدد الوسائط من الجيل التالي المصمم للتنافس مع (وفي بعض الأحيان التفوق على) GPT-5. سواء كنت مهندس برمجيات، أو مؤسس شركة ناشئة، أو هاوياً للذكاء الاصطناعي، أو مجرد شخص فضولي بشأن ما يمكن أن يفعله Gemini 3، فإن تعلم كيفية العمل مع Google Gemini 3 API يفتح الباب أمام بناء تطبيقات أكثر ذكاءً وديناميكية.

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

💡

إذا كنت تريد طريقة سهلة ومرئية وبدون أكواد لاختبار نقاط نهاية Gemini 3 REST API، استخدم Apidog. يمكنك تنزيل Apidog مجانًا، وهو يتيح لك تصميم مكالمات API وتصحيحها واختبارها دون الحاجة إلى كتابة سكربت كامل. بما أن هذا الدليل يتضمن أمثلة لـ REST API، ستجد Apidog مفيدًا للغاية عند التجربة.

زر

الآن، دعنا نطلق العنان لقوة نموذج الذكاء الاصطناعي الأكثر تقدمًا من جوجل!

ما هو Google Gemini 3؟

Google Gemini 3 هو أحدث نموذج في عائلة جوجل للذكاء الاصطناعي متعدد الوسائط. على عكس النماذج السابقة، تم تحسين Gemini 3 من أجل:

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

لكن أبرز ما يميزه هو هذا:

يقدم Gemini 3 "وضعي تفكير" رئيسيين:

يتحكم المعامل `thinking_level` في العمق **الأقصى** لعملية الاستدلال الداخلي للنموذج قبل أن ينتج استجابة. يتعامل Gemini 3 مع هذه المستويات على أنها مسموحات نسبية للتفكير بدلاً من ضمانات صارمة للرموز. إذا لم يتم تحديد `thinking_level`، فسيعتمد Gemini 3 Pro الوضع الافتراضي `high`.

**التفكير العالي/الديناميكي (High/Dynamic Thinking):** يزيد من عمق الاستدلال. قد يستغرق النموذج وقتًا أطول بكثير للوصول إلى الرمز الأول، لكن الناتج سيكون أكثر تفكيرًا وعناية.
**التفكير المنخفض (Low Thinking):** يقلل من زمن الاستجابة والتكلفة. الأفضل لاتباع التعليمات البسيطة، أو الدردشة، أو التطبيقات ذات الإنتاجية العالية

الكثير من المبتدئين لا يعلمون هذا بعد، لكن اختيار الوضع الصحيح يحسن جودة المخرجات بشكل كبير *ويساعدك* على التحكم في تكاليفك.

سنتطرق إلى كيفية اختيار وضع باستخدام واجهة برمجة التطبيقات (API) قريبًا.

لماذا تستخدم Gemini 3 API بدلاً من أداة واجهة المستخدم؟

بالتأكيد، يمكنك استخدام Gemini داخل Google AI Studio. ولكن إذا كنت ترغب في:

بناء تطبيقات
أتمتة المهام
دمج النموذج في سير العمل
إنشاء روبوتات دردشة (chatbots)
معالجة البيانات
تدريب الوكلاء
تنفيذ مهام متعددة الوسائط

فستحتاج إلى Gemini 3 API.

يركز هذا الدليل على **REST API** للأسباب التالية:

أسهل للمبتدئين
لا توجد حاجة لمكتبات العملاء
يمكنك اختباره بسرعة في **Apidog** أو Postman
يعمل في أي بيئة خلفية

كيف تعمل Gemini 3 API (نظرة عامة بسيطة)

على الرغم من أن Gemini لديه قدرات متقدمة، إلا أن واجهة برمجة التطبيقات (API) نفسها بسيطة جدًا.

ترسل طلب POST إلى…

<https://generativelanguage.googleapis.com/v1beta/models/{MODEL_ID}:generateContent?key=YOUR_API_KEY>

تُضمّن JSON مثل:

المُدخل النصي (text prompt)
قائمة الرسائل (اختياري)
إعدادات النموذج
إعدادات الأمان

تتلقى…

نص مخرجات النموذج
هيكل الاستدلال (للتفكير العالي/الديناميكي)
الاستشهاد بالمراجع
البيانات الوصفية (metadata)
الكائنات متعددة الوسائط (إذا كانت قابلة للتطبيق)

بمجرد فهمك لهذا الهيكل، يصبح كل شيء آخر أسهل.

البدء: خطواتك الأولى مع Gemini API

الخطوة 1: احصل على مفتاح API الخاص بك

فكر في مفتاح API الخاص بك ككلمة مرور خاصة تخبر جوجل: "نعم، يُسمح لي باستخدام Gemini". إليك كيفية الحصول عليه:

اذهب إلى Google AI Studio
سجّل الدخول باستخدام حسابك على Google
اضغط على "Create API Key" (إنشاء مفتاح API) في الشريط الجانبي الأيسر
امنح مفتاحك اسمًا وأنشئه
**انسخ واحفظ هذا المفتاح في مكان آمن!** لن تتمكن من رؤيته مرة أخرى.

**مهم:** لا تشارك مفتاح API الخاص بك أبدًا أو تلتزم به في مستودعات الأكواد العامة. تعامل معه ككلمة مرورك.

الخطوة 2: اختر طريقتك

يمكنك التفاعل مع Gemini بطريقتين رئيسيتين:

**REST API:** النهج العالمي. يعمل مع أي لغة برمجة يمكنها إجراء طلبات HTTP. سنركز على هذه الطريقة.
**حزم تطوير البرمجيات الرسمية (Official SDKs):** توفر جوجل مكتبات ملائمة لـ Python وNode.js ولغات أخرى تتولى تفاصيل HTTP نيابة عنك.

نظرًا لأننا نركز على الأساسيات، سنستخدم نهج REST API، فهو يعمل في كل مكان ويساعدك على فهم ما يحدث في الخلفية.

فهم أوضاع التفكير في Gemini

إحدى أقوى ميزات Gemini هي قدرته على العمل في "أوضاع تفكير" مختلفة. هذا ليس مجرد تسويق، بل يغير بشكل أساسي كيفية معالجة النموذج لطلباتك.

التفكير المنخفض (Low Thinking) (شيطان السرعة)

**متى تستخدمه:** للمهام البسيطة، الاستجابات السريعة، وعندما تسعى لتحسين السرعة والتكلفة.

**السرعة:** استجابات سريعة جدًا
**التكلفة:** أكثر تكلفة معقولة
**حالات الاستخدام:** أسئلة وأجوبة بسيطة، تصنيف النصوص، تلخيص أساسي، ترجمات مباشرة

على سبيل المثال:

gemini-3-flash
gemini-3-mini

فكر في وضع التفكير المنخفض وكأنه إجراء محادثة سريعة مع صديق مطلع يقدم لك إجابات فورية.

التفكير العالي/الديناميكي (High/Dynamic Thinking) (المحلل المتعمق)

**متى تستخدمه:** للاستدلال المعقد، المشاكل متعددة الخطوات، والمهام التي تتطلب تحليلًا عميقًا.

**السرعة:** أبطأ (فهو "يفكر" أكثر قبل الاستجابة)
**التكلفة:** أكثر تكلفة
**حالات الاستخدام:** مسائل الرياضيات المعقدة، الاستدلال المنطقي، تصحيح الأخطاء البرمجية، الكتابة الإبداعية، التخطيط الاستراتيجي

التفكير العالي/الديناميكي يشبه استشارة خبير يأخذ وقته في النظر في جميع الجوانب قبل أن يقدم لك إجابة مدروسة جيدًا.

على سبيل المثال:

gemini-3-pro
gemini-3-pro-thinking

تقدم هذه النماذج استدلالًا أعمق، ونوافذ انتباه أطول، وقدرات تخطيط أفضل.

الجميل هو أنه يمكنك اختيار **كلا النموذجين: التفكير العالي/الديناميكي والتفكير المنخفض** حسب احتياجاتك الخاصة. لمعظم التطبيقات البسيطة، التفكير المنخفض مثالي. عندما تحتاج إلى استدلال أعمق، انتقل إلى التفكير العالي.

كقاعدة عامة:

نوع المهمة	وضع النموذج
البحث	التفكير العالي/الديناميكي
الرياضيات/المنطق	التفكير العالي/الديناميكي
توليد الكود	التفكير العالي/الديناميكي
دردشة العملاء	التفكير المنخفض
توليد النصوص الأساسي	التفكير المنخفض
مساعدو واجهة المستخدم	التفكير المنخفض
تطبيقات الوقت الفعلي	التفكير المنخفض

سنوضح لك كيفية اختيار كل نموذج في REST API.

بناء أول استدعاء لـ Gemini 3 REST API

دعنا نبدأ بأبسط مثال ممكن.

نقطة النهاية (Endpoint)

POST <https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro:generateContent?key=YOUR_API_KEY>

مثال على نص الطلب (JSON)

{
  "contents": [
    { "role": "user",
      "parts": [{ "text": "Explain how airplanes fly." }]
    }
  ]
}

مثال لأمر Curl

curl -X POST \\
  -H "Content-Type: application/json" \\
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "Explain how airplanes fly." }]
      }
    ]
  }' \\
"<https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro:generateContent?key=YOUR_API_KEY>"

استخدام وضع التفكير العالي/الديناميكي

لتفعيل وضع الاستدلال، يجب عليك استخدام نموذج يدعمه مثل `gemini-3-pro-thinking`.

مثال على REST API

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

عند استخدام وضع التفكير العالي/الديناميكي، غالبًا ما تتلقى:

هياكل سلسلة التفكير (مخفية ما لم يتم طلبها)
إجابات أكثر تماسكًا
أوقات استجابة أبطأ
تكاليف استنتاج أكثر تكلفة

أوصي باستخدام هذا الوضع فقط عندما يكون الأمر مهمًا حقًا، مثل الاستدلال المطول أو تخطيط الكود.

استخدام وضع التفكير المنخفض

نماذج التفكير المنخفض محسّنة للسرعة وهي مثالية لـ:

الإكمال التلقائي
الرسائل القصيرة
استجابات واجهة المستخدم
المساعدين الصغار
الميزات الجانبية لروبوتات الدردشة

مثال على REST API باستخدام "Flash"

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "How does AI work?"}]
    }],
    "generationConfig": {
        thinkingConfig: {
          thinkingLevel: "low"
      }
    }
  }'

نماذج التفكير المنخفض تكلف أقل بكثير وتعود باستجابات شبه فورية.

التعامل مع المدخلات متعددة الوسائط (الصور، ملفات PDF، الصوت، الفيديو)

يقدم Gemini 3 تحكمًا دقيقًا في معالجة الرؤية متعددة الوسائط عبر المعامل `media_resolution`. تعمل الدقة الأعلى على تحسين قدرة النموذج على قراءة النصوص الدقيقة أو تحديد التفاصيل الصغيرة، ولكنها تزيد من استخدام الرموز وزمن الاستجابة. يحدد المعامل `media_resolution` **الحد الأقصى لعدد الرموز المخصصة لكل صورة أو إطار فيديو مدخل.**

يمكنك الآن تعيين الدقة إلى `media_resolution_low`، `media_resolution_medium`، أو `media_resolution_high` لكل جزء وسائط فردي أو عالميًا (عبر `generation_config`). إذا لم يتم تحديدها، يستخدم النموذج الإعدادات الافتراضية المثلى بناءً على نوع الوسائط.

يدعم Gemini 3 تضمينات متعددة الوسائط عبر:

الصور
الصوت
إطارات الفيديو
المستندات

مثال على رفع صورة (base64):

curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        { "text": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

الاختبار وتصحيح الأخطاء باستخدام Apidog

بينما تُعد أوامر `curl` رائعة للاختبارات السريعة، إلا أنها تصبح مرهقة عند تطوير تطبيق حقيقي. وهنا تبرز قوة **Apidog**.

باستخدام Apidog، يمكنك:

**حفظ إعدادات API الخاصة بك:** قم بإعداد نقطة نهاية Gemini ومفتاح API مرة واحدة، ثم أعد استخدامهما في جميع اختباراتك.
**إنشاء قوالب طلبات:** احفظ أنواعًا مختلفة من المطالبات (بدايات المحادثات، طلبات التحليل، الكتابة الإبداعية) كقوالب.
**اختبار أوضاع التفكير جنبًا إلى جنب:** قم بالتبديل بسهولة بين أوضاع التفكير المنخفض والعالي لمقارنة الاستجابات والأداء.
**إدارة سجل المحادثات:** استخدم متغيرات بيئة Apidog للحفاظ على سياق المحادثة عبر طلبات متعددة.
**أتمتة الاختبار:** أنشئ مجموعات اختبار تتحقق من أن دمج Gemini يعمل بشكل صحيح.

زر

إليك كيف يمكنك إعداد طلب Gemini في Apidog:

أنشئ طلب POST جديد إلى: `https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key={{api_key}}`
قم بإعداد متغير بيئة `api_key` باستخدام مفتاح API الفعلي الخاص بك
في نص الطلب، استخدم JSON:

{
  "contents": [{
    "parts": [{
      "text": "{{prompt}}"
    }]
  }],
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 800
  }
}

4. قم بتعيين متغير بيئة آخر `prompt` بما تريد سؤاله لـ Gemini

هذا النهج يجعل التجربة أسرع وأكثر تنظيمًا.

أفضل الممارسات لـ Gemini API

1. التعامل مع الأخطاء بذكاء

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

2. إدارة تكاليفك

يتم احتساب استخدام Gemini API وتكلفته مالياً (بعد تجاوز حدود الطبقة المجانية). ضع هذه النصائح في الاعتبار:

ابدأ بالطبقة المجانية للتجربة
استخدم وضع التفكير المنخفض (Low Thinking) كلما أمكن للمهام البسيطة
عيّن حدودًا معقولة لـ `maxOutputTokens`
راقب استخدامك في Google AI Studio

يمكن أن تكون الرموز أحرفًا مفردة مثل `z` أو كلمات كاملة مثل `cat`. تُقسّم الكلمات الطويلة إلى عدة رموز. تُسمى مجموعة جميع الرموز التي يستخدمها النموذج بالمفردات، وتُسمى عملية تقسيم النص إلى رموز *تقسيم الرموز (tokenization)*.

عند تفعيل الفوترة، يتم تحديد تكلفة الاستدعاء إلى Gemini API جزئيًا بعدد الرموز المدخلة والمخرجة، لذا فإن معرفة كيفية عد الرموز يمكن أن يكون مفيدًا.

3. صياغة مطالبات أفضل

جودة مخرجاتك تعتمد بشكل كبير على مدخلاتك. إليك بعض نصائح هندسة المطالبات:

**بدلاً من:** "اكتب عن الكلاب"

**جرب:** "اكتب تدوينة تعليمية من 200 كلمة حول فوائد تبني كلاب الإنقاذ، مكتوبة بأسلوب ودود ومشجع لأصحاب الحيوانات الأليفة المحتملين."

**بدلاً من:** "أصلح هذا الكود"

**جرب:** "يرجى تصحيح خطأ دالة Python هذه التي من المفترض أن تحسب المضروب ولكنها تُرجع نتائج غير صحيحة للمدخل 5. اشرح الخطأ وقدم الكود المصحح."

4. اختر النموذج الصحيح

تقدم جوجل عدة نماذج Gemini، لكل منها نقاط قوة مختلفة. تحقق من أن معلمات نموذجك ضمن القيم التالية:

ابدأ بـ `gemini-1.5-flash` وقم بالترقية فقط إذا كنت بحاجة إلى قدرة استدلال أكبر. بالإضافة إلى التحقق من قيم المعلمات، تأكد من أنك تستخدم إصدار API الصحيح (مثل `v1/` أو `v1beta/`) والنموذج الذي يدعم الميزات التي تحتاجها. على سبيل المثال، إذا كانت ميزة ما في إصدار تجريبي (Beta)، فستكون متاحة فقط في إصدار `v1beta/` من API.

الخاتمة: رحلتك في عالم الذكاء الاصطناعي تبدأ

لديك الآن كل ما تحتاجه للبدء في البناء باستخدام Google Gemini API. لقد تعلمت كيفية الحصول على مفتاح API، وإجراء طلبات أساسية، وفهم أوضاع التفكير المختلفة، وحتى رأيت بعض الأمثلة المتقدمة.

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

الخطوة التالية الأكثر أهمية هي البدء بالتجربة. خذ الأمثلة في هذا الدليل، قم بتعديلها، جربها، وشاهد ما سيحدث. أفضل طريقة للتعلم هي بالممارسة.

للمبتدئين، أوصي بشدة باستخدام **Apidog** كأداة لاختبار REST API. فهو يساعدك على:

تصحيح الطلبات (debug requests)
تخزين متغيرات البيئة
تشغيل المجموعات (run collections)
مقارنة مخرجات النموذج بسرعة
مشاركة حالات اختبار API الخاصة بك مع زملائك في الفريق

ولأنه مجاني، فلا يوجد أي جانب سلبي.

زر