تستدعي Gemini 3.6 Flash باستخدام معرف النموذج gemini-3.6-flash عبر واجهة برمجة تطبيقات Gemini من Google. هذا هو جوهر الأمر. قامت Google بإطلاق تحديث Flash في 21 يوليو 2026، و 3.6 Flash هي الطبقة الأكثر استخدامًا: إخراج أرخص من 3.5 Flash، ونافذة سياق بحجم مليون رمز (1M-token)، ومدخلات نصوص وصور وفيديوهات وصوت وملفات PDF. يرشدك هذا الدليل من الصفر إلى طلب مجرّب. ستحصل على مفتاحك، وتُجري أول استدعاء لك باستخدام curl و Python، وتتعلم المعلمات المهمة، وتُعد اختبار الانحدار لضمان استمرار عمل الاستدعاء بعد إطلاقه.
زر
ما تحتاجه قبل البدء
ثلاثة أشياء، ولا يكلف أي منها مالاً للبدء.
- حساب Google. هذا هو كيف تسجل الدخول للحصول على مفتاح.
- مفتاح Gemini API. إنه مجاني من Google AI Studio، ويغطي القسم التالي ذلك.
- طريقة لإرسال طلب HTTP. يعمل curl من أي طرفية. يعمل Python إذا كنت تفضل كتابة التعليمات البرمجية. يمكنك أيضًا استخدام عميل API مثل Apidog إذا كنت تريد واجهة مستخدم شاملة. سنعرض الثلاثة جميعًا.
لا يتطلب إعداد الفوترة مقدمًا. تعمل الطبقة المجانية عبر AI Studio وتخضع لقيود المعدل، لذا يمكنك الاختبار بدون بطاقة مسجلة. المزيد عن هذه القيود أدناه.
احصل على مفتاح Gemini API
انتقل إلى Google AI Studio وسجل الدخول باستخدام حسابك في Google. انقر على "Get API key" (الحصول على مفتاح API)، ثم "Create API key" (إنشاء مفتاح API). انسخ السلسلة التي تحصل عليها واحفظها في مكان آمن. تعامل معها ككلمة مرور: أي شخص لديه المفتاح يمكنه الإنفاق من حسابك.
لا تلصق المفتاح في التعليمات البرمجية من جانب العميل، ولا تلتزم به في مستودع. عيّنه كمتغير بيئة بدلاً من ذلك:
export GEMINI_API_KEY="your_key_here"
يقرأ Python SDK الرسمي هذا المتغير بنفسه، مما يبقي السر خارج ملفات المصدر الخاصة بك. للحصول على خطوات الإعداد المعيارية، راجع وثائق Gemini API من Google.
أجرِ أول استدعاء API لك
نقطة نهاية REST هي طلب POST إلى طريقة generateContent للنموذج. إليك كيفية القيام بذلك باستخدام curl:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent" \
-H "x-goog-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"parts": [
{"text": "Explain how APIs work"}
]
}
]
}'
يذهب المفتاح في ترويسة x-goog-api-key. الجسم عبارة عن مصفوفة contents؛ كل إدخال يحتوي على مصفوفة parts؛ كل جزء هنا هو سلسلة text. قد يبدو هذا التداخل معقدًا لطلب واحد، ولكنه نفس الشكل الذي يتيح لك لاحقًا مزج النصوص مع الصور والملفات في طلب واحد.
تفضل Python؟ ثبّت SDK باستخدام pip install google-genai، ثم:
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)
يستخدم العميل GEMINI_API_KEY تلقائيًا، لذلك لا يوجد مفتاح موجود في التعليمات البرمجية الخاصة بك. يحتوي resp.text على الإجابة التي تم إنشاؤها. هذا استدعاء يعمل بخمسة أسطر.
تحت الغطاء، تُرجع واجهة برمجة التطبيقات JSON. يوجد النص الذي تم إنشاؤه في candidates[0].content.parts[0].text. تجدر الإشارة إلى ذلك الآن، لأن هذا هو الحقل المحدد الذي ستتحقق منه عندما تحول هذا الاستدعاء إلى اختبار لاحقًا في الدليل.
المعلمات الرئيسية التي تستحق المعرفة
يعمل الطلب الأساسي، لكن هناك عدد قليل من الإعدادات التي تغير ما تحصل عليه.
- تعليمات النظام. قم بتعيين شخصية أو مجموعة من القواعد التي تنطبق على المحادثة بأكملها، وتظل منفصلة عن طلب المستخدم. استخدمها لـ "الرد بصيغة JSON فقط" أو "أنت مراجع أكواد مختصر". فهي توجه النبرة والتنسيق بشكل أكثر موثوقية بكثير من حشر التعليمات في كل رسالة.
- الحد الأقصى لرموز الإخراج. حدد طول الاستجابة. يمكن لـ 3.6 Flash إنتاج ما يصل إلى 64 ألف رمز إخراج، لذا ارفع الحد الأقصى للتوليدات الطويلة وخفضه عندما تريد التحكم في التكلفة وزمن الاستجابة.
- مدخلات متعددة الأنماط. يقرأ النموذج النصوص والصور والفيديو والصوت وملفات PDF في نفس الاستدعاء. يمكنك إضافتها كإدخالات إضافية في مصفوفة
partsجنبًا إلى جنب مع نصك. الإخراج نصي فقط، لذا فكر في الأمر كأنواع متعددة من المدخلات، وكلمات كمخرجات. نافذة السياق تستوعب ما يصل إلى مليون رمز إدخال (1M input tokens)، وهو ما يكفي لملف PDF طويل أو نص فيديو كامل. - التفكير والاستدلال. يقوم 3.6 Flash بالاستدلال قبل الإجابة على الطلبات الصعبة. هذا ما يحسن العمل متعدد الخطوات، وهو السبب في أن سعر الإخراج يشمل رموز التفكير (المزيد عن ذلك في القسم التالي). يمكنك ضبط جهد الاستدلال عندما تريد الموازنة بين العمق والسرعة.
توجد قائمة المعلمات الكاملة في وثائق Gemini API. لا تخمن أسماء الحقول؛ الوثائق هي مصدر الحقيقة، ويتم تحديثها عندما تتغير واجهة برمجة التطبيقات.
التسعير والطبقة المجانية
يكلف Gemini 3.6 Flash 1.50 دولارًا لكل مليون رمز إدخال (1M input tokens) و7.50 دولارات لكل مليون رمز إخراج (1M output tokens). هذا السعر للإخراج هو تخفيض من 9.00 دولارات التي كانت تفرضها 3.5 Flash، ويميل 3.6 Flash أيضًا إلى إنتاج حوالي 17% رموز إخراج أقل لنفس المهمة، لذا تتضاعف التوفيرات. تفصيل واحد يجب استيعابه: سعر الإخراج يشمل رموز التفكير. يتم محاسبة التفكير الداخلي للنموذج بسعر الإخراج، لذا فإن الطلب الذي يستدعي تفكيرًا مكثفًا يمكن أن يكلف أكثر مما يوحي به طول الإجابة المرئي. خصص ميزانية لذلك. نفصل الحسابات الكاملة في دليل تسعير Gemini 3.6 Flash الخاص بنا.
الطبقة المجانية تعمل عبر AI Studio، وهي حقيقية، لكنها مقيدة بمعدل: طلبات محددة في الدقيقة واليوم، وقد تستخدم Google بيانات الطبقة المجانية لتحسين منتجاتها. إنها مصممة للنماذج الأولية، وليست لحركة المرور الإنتاجية. للتعلم والاختبار، إنها كافية. لمعرفة مدى فعاليتها، اقرأ كيفية استخدام Gemini 3.6 Flash مجانًا. عندما تتجاوز حدودها، يمكنك تمكين الفوترة وسيظل نفس المفتاح يعمل، دون الحاجة إلى تغييرات في التعليمات البرمجية.
اختبار وتصحيح أخطاء Gemini API في Apidog
يثبت curl أن الاستدعاء يعمل لمرة واحدة. لن يخبرك متى تغير Google حقل استجابة، أو متى ينتهي مفتاحك، أو متى يؤدي النشر بهدوء إلى تعطيل الطلب. لذلك، تحتاج إلى اختبار محفوظ وقابل للتكرار. هذا هو المكان الذي تكتسب فيه Apidog مكانتها في سير العمل.
Apidog هو عميل API ومنصة اختبار. إليك سير العمل لاستدعاء Gemini، من البداية إلى النهاية:
- إنشاء الطلب. أضف طلب POST جديدًا بعنوان URL
https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent. الصق نص JSON من قبل في نص الطلب. - تخزين المفتاح في متغير بيئة. أضف متغيرًا باسم
GEMINI_API_KEYإلى بيئة Apidog، ثم أشر إليه في ترويسةx-goog-api-keyكـ{{GEMINI_API_KEY}}. يبقى السر خارج الطلب المشترك، ويمكنك تبديل المفاتيح لكل بيئة (تطوير، اختبار، إنتاج) دون لمس الاستدعاء نفسه. - إضافة تأكيدات. بعد تشغيل الطلب، تحقق من استجابة JSON: أن الحالة هي 200، وأن
candidates[0].content.parts[0].textموجود وغير فارغ. الآن، يعني التشغيل الناجح أن واجهة برمجة التطبيقات قد أجابت بالفعل، وليس مجرد أنها أعادت شيئًا. - احفظه وجدولته. احتفظ بالطلب في مجموعة و جدوله كاختبار انحدار. قم بتشغيله بانتظام أو ضمن CI، وستكتشف اللحظة التي يتوقف فيها استدعاء Gemini عن العمل بشكل صحيح، قبل أن يكتشفه المستخدمون.
قم بتنزيل Apidog ويمكنك تشغيل هذا الاختبار في غضون دقائق قليلة. هذا هو الاستخدام الأمثل هنا: Apidog لا يشغل النموذج، بل يتأكد من أن واجهة برمجة التطبيقات التي تعتمد عليها تستمر في الاستجابة بالطريقة التي يتوقعها تطبيقك.
الأخطاء الشائعة والحلول
ثلاثة أخطاء تغطي معظم ما ستصادفه في البداية.
- 401 غير مصرح به (مفتاح غير صالح). المفتاح خاطئ، أو تم إلغاؤه، أو مفقود من الترويسة. تأكد من أن
x-goog-api-keyيحتوي على السلسلة الدقيقة من AI Studio وأن متغير البيئة الخاص بك قد تم حله بالفعل. المسافة الزائدة أو{{GEMINI_API_KEY}}غير الموسع هو السبب المعتاد. - 429 عدد كبير جدًا من الطلبات (حد المعدل). لقد وصلت إلى الحد الأقصى للطبقة المجانية في الدقيقة أو في اليوم. قم بإبطاء معدل الطلبات، أو أضف إعادة محاولة مع تأخير، أو قم بتمكين الفوترة لرفع الحد الأقصى. حلقات الاختبار الضيقة تتسبب في ذلك بسرعة.
- 404 لم يتم العثور عليه (لم يتم العثور على النموذج). هذا دائمًا تقريبًا خطأ إملائي في معرف النموذج. إنه
gemini-3.6-flash، بالضبط. ليسgemini-3.5-flash، ولاgemini-flash-3.6. الطبقة الخفيفة (Lite tier) في هذا الإصدار نفسه هيgemini-3.5-flash-lite، وهو نموذج مختلف من سلسلة 3.5، لذا لا تخلط بينهما.
الأسئلة الشائعة
ما هو معرف النموذج الدقيق لـ Gemini 3.6 Flash؟ إنه gemini-3.6-flash. استخدمه كاسم للنموذج في SDK، وفي مسار عنوان URL لـ REST قبل :generateContent مباشرةً.
هل واجهة برمجة تطبيقات Gemini 3.6 Flash مجانية للاستخدام؟ توجد طبقة مجانية عبر AI Studio، وهي مقيدة بمعدل. إنها جيدة للنماذج الأولية والتعلم. تتطلب حركة المرور الإنتاجية تمكين الفوترة. للتفاصيل، راجع كيفية استخدامها مجانًا.
ما الذي يمكنني إرساله إلى النموذج؟ نصوص، صور، فيديوهات، صوتيات، وملفات PDF، بحد أقصى نافذة سياق بحجم مليون رمز (1M-token). الإخراج نصي فقط.
لماذا جاءت فاتورتي أعلى من الاستجابات المرئية؟ سعر الإخراج البالغ 7.50 دولارًا لكل مليون رمز (1M tokens) يشمل رموز التفكير الخاصة بالنموذج. الطلبات التي تتطلب تفكيرًا مكثفًا تُحاسب بتكلفة أعلى مما يظهره طول الإجابة على الشاشة.
هل هذا هو نفسه Gemini 3.5 Flash API الأقدم؟ شكل الاستدعاء هو نفسه، لذا إذا كنت قد استخدمت Gemini 3.5 API، فما عليك سوى تبديل معرف النموذج وستكون قد انتهيت. يقلل 3.6 Flash سعر الإخراج ويستخدم عددًا أقل من رموز الإخراج لنفس المهمة.
هل يمكنني استخدام نفس المفتاح في curl و Python و Apidog؟ نعم. مفتاح واحد من AI Studio يعمل عبر جميع هذه الأدوات. احتفظ به في متغير بيئة في كل أداة بدلاً من ترميزه بشكل ثابت، ويمكنك تدويره أو إلغائه من مكان واحد.
إلى أين تتجه من هنا
لديك مفتاح، واستدعاء عامل في curl و Python، والمعلمات المهمة، واختبار انحدار محفوظ يراقب نقطة النهاية. ابدأ بالطبقة المجانية، احتفظ بمفتاحك في متغير بيئة، واعتمد على الوثائق الرسمية لأي شيء يتجاوز الأساسيات. عندما يصبح الاستدعاء شيئًا يعتمد عليه تطبيقك، ادمجه في اختبار Apidog حتى لا يصل تغيير واجهة برمجة تطبيقات صامت إلى المستخدمين أولاً.
زر