DEV Community

Cover image for طريقة استخدام Gemini 3.6 Flash API
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

طريقة استخدام Gemini 3.6 Flash API

تستدعي Gemini 3.6 Flash باستخدام معرّف النموذج gemini-3.6-flash عبر واجهة Gemini API من Google. أطلقت Google تحديث Flash في 21 يوليو 2026، وتُعد 3.6 Flash الطبقة الأكثر استخدامًا: إخراج أقل تكلفة من 3.5 Flash، ونافذة سياق بحجم مليون رمز، ودعم للنصوص والصور والفيديو والصوت وملفات PDF. في هذا الدليل ستنشئ مفتاح API، وترسل أول طلب باستخدام curl وPython، ثم تضيف اختبار انحدار للتحقق من استمرار عمل التكامل.

جرّب Apidog اليوم

واجهة Gemini 3.6 Flash

ما تحتاجه قبل البدء

ستحتاج إلى ثلاثة أشياء:

  • حساب Google لتسجيل الدخول وإنشاء المفتاح.
  • مفتاح Gemini API من Google AI Studio.
  • عميل HTTP لإرسال الطلبات، مثل curl أو Python أو عميل API مثل Apidog.

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

احصل على مفتاح Gemini API

  1. افتح Google AI Studio وسجل الدخول بحساب Google.
  2. اختر Get API key.
  3. اختر Create API key.
  4. انسخ المفتاح واحفظه في مدير أسرار أو متغير بيئة.

إنشاء مفتاح Gemini API

لا تضع المفتاح في كود الواجهة الأمامية، ولا ترفعه إلى مستودع Git. عيّنه كمتغير بيئة:

export GEMINI_API_KEY="your_key_here"
Enter fullscreen mode Exit fullscreen mode

راجع وثائق Gemini API الرسمية لخطوات الإعداد والتغييرات الحالية في الواجهة.

أجرِ أول استدعاء API باستخدام curl

أرسل طلب POST إلى طريقة generateContent الخاصة بالنموذج:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how APIs work"
          }
        ]
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

نقاط يجب التحقق منها:

  • أرسل المفتاح ضمن الترويسة x-goog-api-key.
  • استخدم معرّف النموذج بدقة: gemini-3.6-flash.
  • يتكون جسم الطلب من contents، وكل عنصر يحتوي parts.
  • يمكنك لاحقًا وضع نصوص وصور وملفات ضمن مصفوفة parts نفسها.

تتضمن الاستجابة JSON النص المُنشأ عادةً في المسار:

candidates[0].content.parts[0].text
Enter fullscreen mode Exit fullscreen mode

احفظ هذا المسار؛ ستحتاجه عند كتابة اختبارات التحقق من الاستجابة.

أجرِ الاستدعاء نفسه باستخدام Python

ثبّت SDK أولًا:

pip install google-genai
Enter fullscreen mode Exit fullscreen mode

ثم أنشئ ملفًا مثل gemini_request.py:

from google import genai

client = genai.Client()  # يقرأ GEMINI_API_KEY من البيئة

resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Explain how APIs work",
)

print(resp.text)
Enter fullscreen mode Exit fullscreen mode

يشير genai.Client() إلى المتغير GEMINI_API_KEY تلقائيًا، لذلك لا تحتاج إلى كتابة المفتاح داخل الكود.

المعلمات الرئيسية التي تستحق المعرفة

بعد نجاح الطلب الأساسي، ابدأ بضبط الإعدادات بحسب حالة الاستخدام.

تعليمات النظام

استخدم تعليمات النظام لفرض سلوك ثابت على النموذج، مثل:

  • الرد بصيغة JSON فقط.
  • العمل كمراجع كود مختصر.
  • اتباع أسلوب أو قواعد تنسيق محددة.

ضع هذه التعليمات منفصلة عن رسالة المستخدم بدل تكرارها في كل طلب.

الحد الأقصى لرموز الإخراج

حدد حدًا لطول الاستجابة عند الحاجة:

  • ارفعه للتلخيصات أو المخرجات الطويلة.
  • اخفضه للتحكم في التكلفة وزمن الاستجابة.

يمكن لـ Gemini 3.6 Flash إنتاج ما يصل إلى 64 ألف رمز إخراج.

المدخلات متعددة الأنماط

يدعم النموذج النصوص والصور والفيديو والصوت وملفات PDF ضمن الاستدعاء نفسه. أضفها كعناصر إضافية في parts إلى جانب النص.

الإخراج نصي فقط، بينما تصل نافذة السياق إلى مليون رمز إدخال، وهو مناسب للملفات الطويلة أو النصوص الكاملة للفيديوهات.

التفكير والاستدلال

يُجري Gemini 3.6 Flash استدلالًا قبل الإجابة عن الطلبات المعقدة متعددة الخطوات. يمكنك ضبط جهد الاستدلال عند الحاجة إلى موازنة العمق مقابل السرعة والتكلفة.

لا تخمّن أسماء الحقول أو الإعدادات؛ استخدم وثائق Gemini API باعتبارها المصدر المرجعي.

التسعير والطبقة المجانية

يكلف Gemini 3.6 Flash:

  • 1.50 دولار لكل مليون رمز إدخال
  • 7.50 دولارات لكل مليون رمز إخراج

سعر الإخراج أقل من 3.5 Flash، التي كانت تكلف 9.00 دولارات لكل مليون رمز إخراج. كما يميل Gemini 3.6 Flash إلى إنتاج رموز إخراج أقل بنحو 17% للمهمة نفسها.

انتبه إلى أن سعر الإخراج يشمل رموز التفكير؛ لذلك قد تكون تكلفة الطلبات التي تتطلب استدلالًا مكثفًا أعلى من طول الإجابة الظاهر. راجع دليل تسعير Gemini 3.6 Flash للحسابات التفصيلية.

الطبقة المجانية عبر AI Studio مناسبة للتعلم والنماذج الأولية، لكنها تخضع لحدود طلبات في الدقيقة واليوم، وقد تستخدم Google بيانات الطبقة المجانية لتحسين منتجاتها. لمزيد من التفاصيل، اقرأ كيفية استخدام Gemini 3.6 Flash مجانًا.

عند تجاوز الحدود، يمكنك تمكين الفوترة والاستمرار باستخدام المفتاح نفسه دون تغيير الكود.

اختبار وتصحيح أخطاء Gemini API في Apidog

نجاح طلب curl مرة واحدة لا يضمن بقاء التكامل سليمًا. تحتاج إلى اختبار محفوظ وقابل للتكرار لاكتشاف:

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

يمكنك استخدام Apidog لإنشاء اختبار API قابل للتشغيل محليًا أو ضمن CI.

1. أنشئ الطلب

أضف طلب POST جديدًا:

https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent
Enter fullscreen mode Exit fullscreen mode

ثم أضف جسم الطلب:

{
  "contents": [
    {
      "parts": [
        {
          "text": "Explain how APIs work"
        }
      ]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

2. خزّن المفتاح في متغير بيئة

أنشئ متغيرًا في بيئة Apidog باسم:

GEMINI_API_KEY
Enter fullscreen mode Exit fullscreen mode

واستخدمه في ترويسة الطلب:

x-goog-api-key: {{GEMINI_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

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

3. أضف تأكيدات للاستجابة

تحقق بعد تنفيذ الطلب من:

  1. أن رمز الحالة هو 200.
  2. أن المسار التالي موجود وغير فارغ: 
candidates[0].content.parts[0].text
Enter fullscreen mode Exit fullscreen mode

هذا يحول الطلب من فحص اتصال بسيط إلى اختبار يتحقق من وجود إجابة مولدة فعلًا.

4. احفظ الاختبار وجدوله

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

نزّل Apidog وأنشئ اختبارك خلال دقائق. لا يشغّل Apidog النموذج؛ بل يساعدك على التحقق من أن واجهة API التي يعتمد عليها تطبيقك تستجيب بالشكل المتوقع.

الأخطاء الشائعة والحلول

401 غير مصرح به: مفتاح غير صالح

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

  • المفتاح غير صحيح أو تم إلغاؤه.
  • الترويسة x-goog-api-key مفقودة.
  • متغير البيئة لم يُحل.
  • توجد مسافة زائدة في المفتاح.

تحقق من أن قيمة المفتاح تطابق القيمة من AI Studio، وأن {{GEMINI_API_KEY}} توسع إلى القيمة الفعلية في بيئة الاختبار.

429 عدد كبير جدًا من الطلبات

هذا يعني أنك وصلت إلى حد المعدل في الطبقة المجانية.

الحلول:

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

404 لم يتم العثور على النموذج

يكون السبب غالبًا خطأ في معرّف النموذج. استخدم:

gemini-3.6-flash
Enter fullscreen mode Exit fullscreen mode

ولا تستخدم:

gemini-3.5-flash
gemini-flash-3.6
Enter fullscreen mode Exit fullscreen mode

لاحظ أن gemini-3.5-flash-lite نموذج مختلف من سلسلة 3.5، وليس اسمًا بديلًا لـ Gemini 3.6 Flash.

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

ما هو معرّف النموذج الدقيق؟

استخدم:

gemini-3.6-flash
Enter fullscreen mode Exit fullscreen mode

ضعه في SDK كاسم النموذج، أو ضمن مسار REST قبل :generateContent.

هل Gemini 3.6 Flash مجاني؟

توجد طبقة مجانية عبر AI Studio، لكنها محددة بالمعدل ومناسبة للتعلم والنماذج الأولية. تحتاج حركة المرور الإنتاجية إلى تمكين الفوترة. راجع كيفية استخدامها مجانًا.

ما أنواع المدخلات المدعومة؟

يمكنك إرسال:

  • نصوص
  • صور
  • فيديوهات
  • صوتيات
  • ملفات PDF

تصل نافذة السياق إلى مليون رمز إدخال، بينما الإخراج نصي فقط.

لماذا تبدو الفاتورة أعلى من طول الإجابة؟

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

هل تختلف الواجهة عن Gemini 3.5 Flash API؟

شكل الاستدعاء نفسه تقريبًا. إذا كنت قد استخدمت Gemini 3.5 API، فاستبدل معرّف النموذج بـ gemini-3.6-flash.

هل يمكن استخدام المفتاح نفسه مع curl وPython وApidog؟

نعم. يعمل المفتاح نفسه من AI Studio مع الأدوات الثلاث. احتفظ به في متغيرات البيئة بدل تضمينه في الكود، حتى تتمكن من تدويره أو إلغائه من مكان واحد.

إلى أين تتجه من هنا

ابدأ بالطبقة المجانية، واحفظ المفتاح في متغير بيئة، ثم نفّذ طلبًا بسيطًا باستخدام curl أو Python. بعد ذلك:

  1. أضف تعليمات النظام والحدود المناسبة للإخراج.
  2. اختبر الاستجابات متعددة الأنماط عند الحاجة.
  3. أنشئ اختبار انحدار للاستدعاء.
  4. ارجع إلى الوثائق الرسمية عند التعامل مع إعدادات متقدمة أو تغييرات في API.
  5. أضف الاختبار إلى Apidog أو إلى خط CI قبل الاعتماد على التكامل في الإنتاج.

شاهد الفيديو: كيفية إنشاء وثائق API عامة باستخدام APIDog

Top comments (0)