عند فتح الوثائق الرسمية لـ Gemini، وخصوصًا الصفحات الخاصة بتوليد الصور مثل Nano Banana، قد تلاحظ وجود مفتاح تبديل جديد في أعلى الصفحة: أحد الخيارين هو Interactions API والآخر generateContent API. الأمر ليس مجرد تحديث شكلي للوثائق، بل إن Google أعلنت رسميًا في يونيو 2026 عن وصول Interactions API إلى مرحلة GA (الإتاحة العامة)، مع توصية بأن تعتمد عليه كل المشاريع الجديدة أولًا. في هذا المقال، وبالاستناد إلى الوثائق الرسمية ونتائج الاختبار الفعلية عبر بوابة APIYI، سنوضح الفروق الجوهرية بينهما، والفجوات في القدرات، وما الذي يُنصح به عمليًا عند الاستدعاء.
القيمة الأساسية: بعد قراءة هذا المقال، ستفهم بوضوح الفروقات بين Interactions API و generateContent من حيث فلسفة التصميم، وإدارة الحالة، وتغطية القدرات، وستعرف أي نموذج تختار عند استدعاء Gemini عبر APIYI كخدمة وكيل API.
الفروق الجوهرية بين Interactions API و generateContent
لنبدأ بالخلاصة: هذان الـ API ليسا مجرد ترقية من نسخة قديمة إلى جديدة، بل يمثلان فلسفتين مختلفتين في التصميم. generateContent يعتمد على نمط بلا حالة: «طلب واحد، استجابة واحدة»، وعلى العميل أن يحتفظ هو بكل سجل المحادثة. أما Interactions API فينقل إدارة الحالة إلى الخادم، ويعيد تصميم آلية التفاعل كاملةً حول مفهوم جديد هو "Interaction".
تعرّف الوثائق الرسمية الـ Interaction بأنه «جلسة محادثة أو دورة مهمة كاملة»، وتتكوّن داخليًا من سلسلة خطوات مرتبة زمنيًا، تشمل عملية تفكير النموذج، واستدعاء الأدوات ونتائجها، ثم المخرجات النهائية للنموذج. وهذا يعني أن Interactions API صُمم أصلًا للمحادثات متعددة الجولات وللمهام الشبيهة بالوكلاء، وليس لأسئلة وإجابات منفردة فقط.
وهذا يفسر أيضًا لماذا استخدمت Google تعبير «الإتاحة العامة» بدلًا من وصفه بأنه مجرد «ميزة جديدة». فقد دخل Interactions API مرحلة المعاينة العامة في ديسمبر 2025، ثم أُعلن رسميًا عن GA في يونيو 2026. وتذكر المدونة الرسمية بوضوح: «نوصي بأن تستخدم جميع المشاريع والتطبيقات الجديدة Interactions API»، كما أن جميع الوثائق الرسمية أصبحت تعرض هذه الفلسفة الجديدة افتراضيًا، وتسعى Google كذلك إلى دفع حِزم SDK الشريكة والنظام البيئي الخارجي لاعتمادها كواجهة افتراضية. بعبارة أخرى: هذا ليس تحديثًا اختياريًا فحسب، بل إعادة تعريف لطريقة استدعاء Gemini، مع توفير دليل ترحيل يتيح للمطورين الانتقال تدريجيًا حسب وتيرتهم، من دون فرض تغيير شامل دفعة واحدة.
| بُعد المقارنة | generateContent (Legacy) | Interactions API |
|---|---|---|
| الحالة الحالية | قديم لكنه ما يزال مدعومًا بالكامل | GA رسميًا اعتبارًا من يونيو 2026 |
| التوصية الرسمية | يمكن للمشاريع الحالية الاستمرار فيه | يُنصح بأن تعتمد عليه المشاريع الجديدة أولًا |
| الطريقة الأساسية | generateContent | interactions.create / get / delete |
| فلسفة التصميم | طلب منفرد بلا حالة | دورة مهمة حالة-مدارة حول Interaction |
| القدرات الجديدة مستقبلًا | سيواصل تلقي النماذج الرئيسية الجديدة | القدرات المتقدمة لوكلاء الذكاء الاصطناعي تصل إليه أولًا |
🎯 نصيحة تقنية: إذا كنت تستدعي نماذج Gemini عبر APIYI على apiyi.com، فمن الأفضل أن تقضي بضع دقائق في مراجعة الوثائق الرسمية للتأكد من أي فلسفة يستخدمها مشروعك حاليًا، ثم تقرر ما إذا كنت بحاجة إلى متابعة الترحيل، حتى لا يسبب لك ظهور Interactions API افتراضيًا في الوثائق انطباعًا خاطئًا بأن كودك الحالي أصبح قديمًا.
الفرق الجوهري بين طريقتَي الطلب وإدارة الحالة
فهم الفارق بين الطريقتين يبدأ من سؤال واحد: من الذي يدير سجل المحادثة؟
في generateContent يجب على العميل أن يضمّن كل تاريخ الرسائل في كل طلب بشكل كامل. حتى لو كنت في الجولة العاشرة من الحوار، عليك إرسال محتوى الجولات التسع السابقة كما هو. هذه الطريقة مباشرة وبسيطة، لكن مع زيادة عدد الجولات يكبر حجم الطلب، وتبدأ البيانات التاريخية نفسها بالمرور مرة أخرى، ما يعني تكلفة أعلى.
أما Interactions API فتقدم حلًا مختلفًا: تأخذ interaction id الذي عاد من الاستدعاء السابق، وتمريره في الطلب التالي عبر previous_interaction_id، فيسترجع الخادم تاريخ المحادثة كاملًا تلقائيًا، من دون حاجة إلى إعادة دمجه يدويًا من جهة العميل. وتوفّر الوثائق أيضًا معامل background=true للمهام الطويلة، إلى جانب ميزة خطوات التنفيذ القابلة للملاحظة، وهي مفيدة جدًا عند التصحيح أو عند عرض ما يجري داخل النموذج في واجهة المستخدم، خصوصًا في منتجات الوكيل الذكي.
لكن إدارة الحالة على الخادم ليست بلا ثمن. افتراضيًا، تكون قيمة store هي true، أي إن النظام يحتفظ بسجلات الـ interaction: الحسابات المدفوعة تحتفظ بها لمدة 55 يومًا، والحسابات المجانية لمدة يوم واحد فقط. وإذا أردت تعطيل التخزين لأسباب تتعلق بالخصوصية أو الامتثال فبإمكانك ضبط store=false، لكنك ستفقد عندها القدرة على متابعة المحادثة باستخدام previous_interaction_id وكذلك القدرة على التنفيذ في الخلفية. وهذه نقطة يجب الموازنة بينها مسبقًا.
من زاوية التكلفة، توضح الوثائق الرسمية القيمة التي تقدمها هذه الفكرة: عندما يدير الخادم الحالة، لا يعود محتوى المحادثة نفسها يُحسب كل مرة ضمن مدخلات token، وهذا يرفع معدل الاستفادة من الكاش بشكل ملحوظ. وتصفه الوثائق بعبارة: "تكلفة أقل، ومعدل إصابة أعلى للكاش".
بالنسبة لسيناريوهات مثل روبوتات الدعم الفني أو أسئلة الأجوبة على المستندات الطويلة، يظهر هذا الفرق بوضوح مع ارتفاع عدد الاستدعاءات. أما المهام أحادية الجولة، أو الأعمال الدفعية، فهي بطبيعتها عديمة الحالة، لذلك لا تستفيد كثيرًا من هذه الميزة.
هناك أيضًا تفصيل سهل أن يُفوت:
المعاملات مثل tools وsystem_instruction وgeneration_config — بما فيها thinking_level وtemperature وغيرها — تُعد إعدادات لكل طلب. حتى لو استخدمت previous_interaction_id لمتابعة الحوار السابق، فلن تُورَّث هذه الإعدادات تلقائيًا، ويجب تمريرها بشكل صريح في كل مرة.
| القدرة | generateContent |
Interactions API |
|---|---|---|
| إدارة تاريخ المحادثة | العميل يضمّن كل السجل يدويًا | الخادم يسترجعها تلقائيًا عبر previous_interaction_id |
| التنفيذ الخلفي للمهام الطويلة | غير مدعوم | مدعوم عبر background=true |
| إظهار خطوات التنفيذ الوسيطة | يجب تحليلها يدويًا | توفّره ميزة steps القابلة للملاحظة |
| سياسة الاحتفاظ بالسجلات | لا يوجد هذا المفهوم | افتراضيًا محفوظة، 55 يومًا للمدفوع و1 يوم للمجاني |
| وراثة أدوات ومعاملات التوليد | يجب تمريرها صراحة كل مرة | يجب تمريرها صراحة كل مرة، ولا تُورَّث تلقائيًا |
💡 توصية الاختيار: إذا كان مشروعك يعتمد كثيرًا على المحادثات متعددة الجولات أو على بناء تدفقات عمل من نوع agent، فإن آلية إدارة الحالة في
Interactions APIستوفر عليك كثيرًا من كود الربط اليدوي. أما إذا كان استخدامك الأساسي هو التوليد الفردي، فقد لا تظهر هذه الأفضلية بوضوح. ننصح بتجربة محدودة عبر منصة APIYI apiyi.com قبل اتخاذ قرار الانتقال.
الفجوات في القدرات بينهما: ما الذي يدعمه كل طرف وما الذي لا يدعمه
رغم أن Interactions API تمثل النمط الجديد، فإن الوثائق الرسمية تذكر بوضوح بعض القدرات التي ما زالت غير مدعومة فيها. وهذا مهم جدًا عند اختيار المسار، لأن "الأحدث" لا يعني بالضرورة "الأكمل".
تنص الوثائق على أن Interactions API لا تدعم حاليًا حقل video metadata في فهم الفيديو، ولا Batch API، ولا الاستدعاء التلقائي للدوال في Python (automatic function calling)، ولا التخزين الصريح (explicit caching). ومع ذلك، فهي تدعم التخزين الضمني عبر previous_interaction_id.
في المقابل، يدعم generateContent بشكل كامل المخرجات المتدفقة، واستدعاء الدوال، وBatch API، والتخزين الصريح، وكذلك الإدخال متعدد الوسائط كاملًا، بما في ذلك النصوص والصور والصوت والفيديو والمستندات.
| القدرة | generateContent |
Interactions API |
|---|---|---|
Batch API |
✅ مدعوم | ❌ غير مدعوم حاليًا |
التخزين الصريح (explicit caching) |
✅ مدعوم | ⚠️ التخزين الضمني فقط |
حقل video metadata |
✅ مدعوم | ❌ غير مدعوم حاليًا |
| الاستدعاء التلقائي للدوال في Python | ✅ مدعوم | ❌ غير مدعوم حاليًا |
| الإخراج المتدفق / استدعاء الدوال | ✅ مدعوم | ✅ مدعوم |
| التكلفة ومعدل إصابة الكاش المعلن عنهما | تسعير اعتيادي | تصفه الوثائق بأنه أقل تكلفة وأعلى معدل إصابة |
إذا أخذنا مثال Nano Banana لتوليد الصور، فالفارق العملي الأوضح يظهر في طريقة الحصول على النتيجة.
في Interactions API توجد خصائص مريحة مثل interaction.output_image وinteraction.output_text، ويمكنك الوصول مباشرة إلى الصورة أو النص الناتج الأخير. أما generateContent فيعتمد على البنية الأدنى candidates[0].content.parts، وعليك المرور على المصفوفة بنفسك وتحديد نوع كل جزء.
بالنسبة للمشاريع التي بُنيت أصلًا على منطق تحليل generateContent، فإن هذا الاختلاف البنيوي قد يعني تعديلًا برمجيًا كبيرًا، وليس مجرد تبديل نقطة النهاية فقط.
هذه الفجوات ليست تفاصيل هامشية.
فـ Batch API مثلًا تمثل أداة أساسية في المشاريع الحساسة للتكلفة عندما تريد معالجة مهام غير متصلة بالإنترنت على دفعات. وإذا انتقلت إلى نمط جديد ثم اكتشفت أنه لا يدعمها، فقد تضطر إلى إعادة تصميم سلسلة المعالجة كاملة.
أما التخزين الصريح، فهو يرتبط مباشرة بتكلفة السيناريوهات ذات السياق الطويل. وإذا كان لديك system prompt ثابت طويل أو مادة مرجعية تعيد استخدامها مرارًا، فإن غياب التخزين الصريح يعني أنك لن تستطيع التحكم بدقة في ما يُخزَّن ومدة تخزينه. ولهذا السبب تحتفظ الوثائق الرسمية بالمسارين معًا، بدلًا من إيقاف generateContent نهائيًا. فهو ما يزال غير قابل للاستبدال على الأقل إلى أن تُستكمل هذه القدرات.
🔧 نصيحة عملية: إذا كان عملك يعتمد بقوة على
Batch APIأو على التخزين الصريح لخفض التكلفة، فالانتقال المبكر إلىInteractions APIقد يكلّفك فقدان هذه الإمكانات. الأفضل متابعة دليل الترحيل الرسمي وانتظار وضوح الخريطة قبل تغيير كود الإنتاج.
اختبار APIYI للبوابة: أي نمط يجب استخدامه الآن
الخلاصة أولًا: بحسب الاختبار العملي حتى 4 يوليو 2026، عند استدعاء Gemini عبر بوابة APIYI، ينبغي الاستمرار في استخدام التنسيق الأصلي generateContent.
قام فريق APIYI التقني بإجراء اختبار مباشر على المسار الرئيسي لـ Interactions API، مع تغطية طريقتي المصادقة الشائعتين، وكانت النتيجة كما يلي:
| نقطة النهاية للاختبار | طريقة المصادقة | النتيجة |
|---|---|---|
| POST /v1beta2/interactions | Bearer token | ❌ 404 (عنوان URL غير صالح) |
| POST /v1beta/interactions | Bearer token | ❌ 404 (عنوان URL غير صالح) |
| POST /v1beta2/interactions | x-goog-api-key header | ❌ 404 (عنوان URL غير صالح) |
| POST /v1beta/models/{model}:generateContent | Bearer token | ✅ استجابة طبيعية |
ينصّ التوثيق الرسمي لـ APIYI حرفيًا على: "بوابة APIYI لا تدعم حاليًا ترحيل Interactions API — المساران /v1beta2/interactions و/v1beta/interactions يعيدان 404"، مع توصية واضحة تقول: "عند استدعاء Gemini عبر APIYI، استمر في استخدام تنسيق generateContent الأصلي". وهذا أيضًا سبب توحيد جميع وثائق Gemini داخل موقع APIYI حاليًا على تنسيق generateContent، بحيث يتمكن القارئ من نسخ الكود وتشغيله مباشرة دون مواجهة مشكلة 404 في المسار.
ومن المهم التأكيد أن هذا الوضع ديناميكي، وليس قيدًا دائمًا. ومع تحول Interactions API تدريجيًا إلى النمط الافتراضي الرسمي، فمن المرجّح أن تضيف البوابة دعمه لاحقًا؛ وعندها ستحدّث APIYI الوثائق المرتبطة به. يمكن حاليًا متابعة الصفحة docs.apiyi.com/api-capabilities/gemini/interactions-api لمعرفة أحدث حالة دعم، بدلًا من اختبار النقاط النهائية يدويًا كل مرة.
وتذكّرنا هذه النتائج أيضًا بحقيقة كثيرًا ما تُهمل: "الإتاحة الرسمية" على مستوى الوثائق ليست هي نفسها "الجاهزية الفعلية" لدى بوابة وكيل API معينة أو SDK خارجي. إذا اعتمد المطوّر فقط على المثال الافتراضي في الوثائق الرسمية، ثم نسخ مثال Interactions API مباشرة إلى إعدادات الترحيل الحالية، فغالبًا سيصطدم أولًا بخطأ 404، ثم يقضي وقتًا في البحث: هل الخطأ في الكود أم أن البوابة نفسها لم تتبنَّ النمط الجديد بعد؟ في مثل هذه الحالات، التحقق أولًا من مسار الاستدعاء لديك — هل هو اتصال مباشر بالمزوّد الرسمي أم عبر وكيل طرف ثالث — غالبًا أسرع في تحديد المشكلة من إعادة فحص منطق التطبيق نفسه.
🚀 بدء سريع: إذا كنت تريد الآن التحقق من أن مسار استدعاء Gemini لديك يعمل بشكل صحيح، فالأفضل استخدام تنسيق generateContent عبر APIYI apiyi.com مباشرة. توفر المنصة
base_urlموحّدًا، وتدعم استدعاء نماذج Gemini النصية والمرئية وغيرها، دون الحاجة إلى التعامل الإضافي مع تفاصيل المصادقة.
كيف تختار: توصيات حسب السيناريو
بناءً على مقارنة القدرات السابقة ونتيجة الاختبار العملي، هذه توصية مبسطة حسب السيناريو.
| حالة الاستخدام | الحل الموصى به | السبب |
|---|---|---|
| استدعاء Gemini عبر بوابة APIYI | generateContent | البوابة تدعم هذا التنسيق حاليًا فقط، بينما مسارات Interactions API تُرجع 404 |
| الاعتماد على Batch API للمعالجة الجماعية | generateContent | Interactions API لا تدعم Batch API حاليًا |
| الحاجة إلى تخزين مؤقت صريح لتقليل التكلفة | generateContent | Interactions API تحتوي حاليًا على تخزين مؤقت ضمني فقط |
| بناء agent محادثة متعدد الجولات مع اتصال مباشر بالمزوّد الرسمي | يمكن تقييم Interactions API | إدارة الحالة على الخادم توفر عناء دمج السجل السابق يدويًا |
| الحاجة إلى تتبّع خطوات التنفيذ الداخلية للنموذج أثناء التصحيح | Interactions API | توفر دعمًا أصليًا لخطوات التنفيذ القابلة للملاحظة |
| مشروعك الحالي يعمل بالفعل على generateContent | لا حاجة للترحيل الآن | النمط القديم ما يزال مدعومًا بالكامل، وسيستمر بالحصول على نماذج جديدة على المدى القصير |
ببساطة: قرار الترحيل لا يعتمد على "كونه جديدًا" أو لا، بل على ما إذا كانت متطلباتك الحالية مغطاة بالكامل بـ Interactions API، وكذلك على ما إذا كانت سلسلة استدعاء Gemini لديك — اتصال مباشر بالمزوّد أو عبر بوابة وكيل API — تدعم هذه الصيغة الجديدة بالفعل. بالنسبة لمعظم المطورين الذين يستدعون عبر APIYI، يبقى التمسك حاليًا بـ generateContent هو الخيار الأكثر أمانًا.
الأسئلة الشائعة
س1: هل سيتم إيقاف generateContent؟ وهل ما زال يستحق بناء مشروع جديد عليه الآن؟
لن يتم إيقافه في المدى القريب. وقد أوضحت الجهة الرسمية بوضوح أن generateContent، رغم أنه مُوسوم بأنه legacy، «لا يزال مدعومًا بالكامل»، وسيستمر كذلك في الحصول على نماذج Gemini الرئيسية الجديدة في المستقبل المنظور. إذا كنت تستدعي Gemini عبر APIYI apiyi.com، فلا توجد مشكلة إطلاقًا في بناء مشروع جديد اعتمادًا على generateContent في هذه المرحلة، ولا داعي للقلق فقط لأن الوثائق تعرض افتراضيًا Interactions API.
س2: متى ستدعم بوابة APIYI Interactions API؟
لا يوجد جدول زمني مؤكد حتى الآن، لأن ذلك يعتمد على مدى انتشار هذا النمط في المنظومة الرسمية وعلى وتيرة التكيّف في جانب البوابة. نوصي بمتابعة تحديثات الوثائق الرسمية لمنصة APIYI apiyi.com؛ فبمجرد دعم تحويل Interactions API عبر خدمة وكيل API، ستُحدَّث الوثائق المرتبطة بذلك فورًا، ولن تحتاج إلى اختبار حالة نقاط النهاية بنفسك مرارًا وتكرارًا.
س3: هل يمكن استخدام النوعين من واجهات API معًا داخل المشروع نفسه؟
من الناحية التقنية، طالما أن مسار الاستدعاء يدعم ذلك، يمكن للطريقتين أن تتعايشا. على سبيل المثال، يمكن استخدام generateContent لمعالجة مهام Batch API الدُفعية، وفي الوقت نفسه تجربة Interactions API في سيناريوهات المحادثة متعددة الجولات عند الاتصال المباشر بالواجهة الرسمية. لكن عند الاستدعاء عبر بوابة APIYI، وبما أن مسار Interactions API يعود حاليًا بالخطأ 404، فمن الأفضل مؤقتًا توحيد الاستخدام على صيغة generateContent لتجنب وجود منطقتين مختلفتين من منطق الاستدعاء داخل المشروع نفسه وما يسببه ذلك من زيادة في تكلفة الصيانة.
الخلاصة
بعد أن أصبح Interactions API رسميًا في يونيو 2026، فهو فعلًا يمثّل الاتجاه طويل الأمد الذي تريده Google لطريقة استدعاء Gemini. ميزات مثل إدارة الحالة على الخادم والقدرة على تتبّع خطوات التنفيذ تجعله جذابًا جدًا لتطبيقات الوكلاء الذكية، لكنه ما يزال يفتقر إلى دعم واضح في Batch API، والتخزين المؤقت الصريح، وبيانات الفيديو الوصفية، بينما يظل generateContent مدعومًا بالكامل وسيستمر تحديثه على المدى القريب. والأهم من ذلك، أنه عند استدعاء Gemini عبر بوابة APIYI، فإن نتائج الاختبار الفعلي حتى الآن تُظهر أن المسارات المرتبطة بـ Interactions API تعطي جميعها الخطأ 404، وأن generateContent هو الصيغة الوحيدة المتاحة حاليًا. إذا كنت تحتاج إلى استدعاء موثوق ومستقر لعائلة نماذج Gemini، فنوصي باستخدام APIYI apiyi.com عبر صيغة generateContent الأصلية، وسيتم تحديث الوثائق فور دعم النمط الجديد في البوابة.
لقد أجرى فريق APIYI التقني التحقق من البيانات التجريبية ومراجعة المعلومات الرسمية. وإذا كنت ترغب في معرفة المزيد من التفاصيل حول استدعاء نماذج Gemini، فلا تتردد في التواصل مع الدعم الفني عبر APIYI apiyi.com.
المراجع
-
Google AI for Developers – نظرة عامة على Interactions API: مفهوم الـ Interaction، والطرق الأساسية، وشرح القدرات
- الرابط:
ai.google.dev/gemini-api/docs/interactions-overview
- الرابط:
-
Google AI for Developers – generateContent (Legacy): حالة دعم واجهة API القديمة ونطاق قدراتها
- الرابط:
ai.google.dev/gemini-api/docs/interactions
- الرابط:
-
الوثائق الرسمية لـ APIYI – حالة دعم Gemini Interactions API: نتائج اختبار نقاط النهاية على البوابة وتوصيات الاستدعاء
- الرابط:
docs.apiyi.com/api-capabilities/gemini/interactions-api
- الرابط:
