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 أو أكثر، وإلا فقد تُرجع محتوى فارغًا فقط.
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.
usage موحّدًا، وتُقرأ تكلفة هذه المكالمة بشكل موحّد عبر بروتوكولات النماذج من usage.cost. إن cost هي معاينة تكلفة اختيارية؛ وعندما تكون معاينة السعر غير متاحة مؤقتًا، ستظل استجابة النموذج تُرجع بشكل طبيعي، لكنها قد لا تتضمن هذا الحقل. تخضع الفاتورة النهائية لسجل الاستخدام.
Streaming(متدفق)
أرسل طلب POST إلى/v1beta/models/{model}:streamGenerateContent?alt=sse:
usageMetadata وusage الموحّد، وتظل التكلفة ضمن usage.cost:
data: [DONE]. إذا كانت معاينة السعر النهائي غير متاحة مؤقتًا، فسيظل usage يعيد استخدام token، لكنه سيحذف cost.
النماذج المدعومة
الميزات المتقدمة
تعليمات النظام
إعدادات التوليد
وضع JSON
وضع التفكير (Thinking)
يمكن للنماذج التي تدعم ميزة التفكير (مثل gemini-2.5-flash وgemini-2.5-pro) تفعيل وضع التفكير:استدعاء الدوال
محادثة متعددة الجولات
فهم الصور
إعدادات الأمان
يمكن التحكم في تصفية المحتوى عبرsafetySettings:

