الانتقال إلى المحتوى الرئيسي
Google Gemini هو نظام محادثة بالذكاء الاصطناعي قوي جدًا، ويمكنه إنشاء ردود سلسة وطبيعية خلال ثوانٍ بمجرد إدخال مطالبة. يصف هذا المستند بشكل أساسي طريقة استخدام واجهة Gemini Generate Content API، وهي تنسيق واجهة برمجة التطبيقات الأصلي الرسمي من Google، وتدعم نقطتي النهاية generateContent وstreamGenerateContent.

الفرق عن Chat Completions API

تستخدم Gemini Generate Content API تنسيق الطلب الأصلي الرسمي من Google (حقل contents) بدلًا من التنسيق المتوافق مع OpenAI (حقل messages). إذا كنت تستخدم بالفعل Google Gemini SDK أو كنت على دراية بتنسيق واجهة برمجة التطبيقات الرسمي، فيمكنك استخدام هذه الواجهة مباشرةً دون تعديل تنسيق الطلب.

نطاق الدعم الحالي

تقبل الواجهة إدخالات النصوص والصور والفيديو والصوت (عبر inlineData أو fileData)، وإعدادات التفكير وإعلانات الدوال المخصصة. لا تتوفر حتى الآن ضمانات موحدة لإتاحة الحقول الأصلية مثل مخرجات الصوت والأدوات المضمنة والتخزين المؤقت الصريح للسياق؛ يُرجى الرجوع إلى الاستجابة الفعلية للنموذج المحدد. عند إرسال ملفات مثل الصوت باستخدام fileData.fileUri، يُرجى التأكد من إمكانية الوصول إلى الملف مباشرةً عبر HTTPS، وألا يعتمد على حالة تسجيل الدخول، وأن تغطي صلاحية الرابط الموقّع كامل وقت معالجة الطلب. لا تُرجع تحليلات الصوت غير المتدفقة النتائج إلا بعد انتهاء النموذج من المعالجة، وقد تتجاوز 90 ثانية؛ ينبغي للعميل تعيين مهلة إجمالية طويلة بما يكفي وفقًا لحجم الملف وسيناريو العمل، لتجنب قطع الاتصال بينما لا يزال الخادم يعالج الطلب.

عملية التقديم

قبل استخدام Gemini Generate Content API، يُرجى أولًا زيارة صفحة Gemini Generate Content API، والنقر على زر “الحصول” للحصول على بيانات الاعتماد المطلوبة للطلب. إذا لم تقم بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول. يتوفر رصيد مجاني عند أول طلب.

الاستخدام الأساسي

Non-Streaming(غير متدفق)

أرسل طلب POST إلى /v1beta/models/{model}:generateContent:
ملاحظة: سلسلة gemini-3.x من flash هي نماذج تفكير، وستستهلك reasoning tokens أولًا؛ يُرجى تعيين generationConfig.maxOutputTokens إلى 512 أو أكثر، وإلا فقد تُرجع محتوى فارغًا فقط.
مثال على النتيجة المعادة:
تُحتسب حقول token في usageMetadata وفقًا لدلالات Gemini الأصلية:
  • يتضمن promptTokenCount قيمة cachedContentTokenCount، ويُحتسب الجزء المطابق للتخزين المؤقت بسعر قراءة التخزين المؤقت، ولن يُحتسب مجددًا كإدخال عادي.
  • ستتم تسوية promptTokensDetails وcacheTokensDetails إلى text_tokens وimage_tokens وvideo_tokens وaudio_tokens وتفاصيل cached_* المقابلة ضمن usage.prompt_tokens_details. تُضمَّن هذه القيم على التوالي في prompt_tokens وcached_tokens؛ وتُعاد حساب الوسائط المختلفة وفق أسعارها الخاصة فقط، دون احتساب مكرر.
  • يُحتسب كل من candidatesTokenCount وthoughtsTokenCount وفقًا لسعر output token.
  • يُعد toolUsePromptTokenCount رمز إدخال مستقلًا للأداة، ويُحتسب وفقًا لسعر input token.
تعيد Ace Data Cloud بالإضافة إلى ذلك كائن usage موحّدًا، وتُقرأ تكلفة هذه المكالمة بشكل موحّد عبر بروتوكولات النماذج من usage.cost. إن cost هي معاينة تكلفة اختيارية؛ وعندما تكون معاينة السعر غير متاحة مؤقتًا، ستظل استجابة النموذج تُرجع بشكل طبيعي، لكنها قد لا تتضمن هذا الحقل. تخضع الفاتورة النهائية لسجل الاستخدام.

Streaming(متدفق)

أرسل طلب POST إلى /v1beta/models/{model}:streamGenerateContent?alt=sse:
ستُرجع الاستجابة المتدفقة المحتوى تدريجيًا بتنسيق SSE(Server-Sent Events). تحتوي الأحداث الوسيطة عادةً على محتوى تزايدي فقط؛ بينما سيتضمن الحدث النهائي الذي يحتوي على استخدام موثوق usageMetadata وusage الموحّد، وتظل التكلفة ضمن usage.cost:
إغلاق الاتصال يعني انتهاء التدفق؛ ولا يرسل تدفق Gemini الأصلي data: [DONE]. إذا كانت معاينة السعر النهائي غير متاحة مؤقتًا، فسيظل usage يعيد استخدام token، لكنه سيحذف cost.

النماذج المدعومة

الميزات المتقدمة

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

إعدادات التوليد

وضع JSON

وضع التفكير (Thinking)

يمكن للنماذج التي تدعم ميزة التفكير (مثل gemini-2.5-flash وgemini-2.5-pro) تفعيل وضع التفكير:

استدعاء الدوال

محادثة متعددة الجولات

فهم الصور

إعدادات الأمان

يمكن التحكم في تصفية المحتوى عبر safetySettings:

معالجة الأخطاء