Gemini 3.1 Pro

طلبات Gemini بالتنسيق الأصلي، والإدخال متعدد الوسائط، والتفكير، والأدوات، والتخزين المؤقت، والبث. يشمل حدود النموذج وحالة التحقق.

استخدم gemini-3.1-pro-preview بتنسيق Gemini الأصلي. تتضمن صفحة النموذج Playground والأسعار الحالية؛ ويشرح دليل إصدارات النموذج المعرّفين الرسميين.

معرّف النموذج

معرّف النموذج	حد الإدخال	جهد التفكير الافتراضي
`gemini-3.1-pro-preview`	1,048,576 توكن	`high`

مثال سريع

curl https://api.seedrouter.ai/v1beta/models/gemini-3.1-pro-preview:generateContent \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"thinkingConfig":{"thinkingLevel":"low"},"maxOutputTokens":1024}}'

يوضع النموذج في URL. الحقل contents مطلوب. تتضمن الإجابة الحقول الأصلية candidates وfinishReason وusageMetadata؛ احتفظ بأجزاء المحتوى كاملة، بما فيها thoughtSignature، في سجل المحادثة.

نقاط النهاية

العملية	نقطة النهاية
استجابة JSON	`POST /v1beta/models/gemini-3.1-pro-preview:generateContent`
أحداث مرسلة من الخادم	`POST /v1beta/models/gemini-3.1-pro-preview:streamGenerateContent?alt=sse`

تتضمن مواصفة OpenAPI جميع مخططات الطلبات والاستجابات المتداخلة. تستخدم الحقول الاختيارية قيم API الافتراضية عند حذفها. تمرّر SeedRouter جسم الطلب المرسَل من دون تصفية الحقول غير المعروفة أو إزالة الحقول غير المدعومة أو التحقق من قيم معلمات النموذج. تقرّر Gemini API قبول الطلب من عدمه.

معلمات الطلب

يحدّد URL النموذج gemini-3.1-pro-preview. تتضمن مواصفات الطلب 12 حقلاً في المستوى الأعلى. الحقول اختيارية ما لم تُعلّم بأنها مطلوبة؛ ويختلف حذف الحقل عن قيمة JSON null. يُحفظ JSON الحرّ الذي يقبل null حيث يسمح المخطط الرسمي بذلك.

الحقل	النوع	مطلوب	القيمة الافتراضية والقيود
`contents`	object[]	نعم	محادثة غير فارغة؛ يحتوي كل محتوى على `parts` غير فارغة
`systemInstruction`	object	لا	أجزاء نصية فقط؛ لا تُدرج هوية المستخدم تلقائياً
`generationConfig`	object	لا	معلمات التوليد في الجدول التالي
`tools`	object[]	لا	تعريفات الدوال وإعدادات الأدوات المضمّنة
`toolConfig`	object	لا	إعدادات اختيار الدوال والاسترجاع
`safetySettings`	object[]	لا	إعداد واحد لكل فئة؛ لا تُكرّر الفئات
`cachedContent`	string	لا	مورد `cachedContents/{id}` موجود؛ يتطلب صلاحية وصول متوافقة
`serviceTier`	string	لا	`unspecified`، `standard`، `flex`، `priority`؛ المعالجة العادية قياسية
`labels`	object	لا	قيم نصية؛ مفاتيح وقيم بأحرف صغيرة، بحد أقصى 63 نقطة ترميز Unicode لكل منها
`model`	string	لا	اسم مورد اختياري؛ يحدّد URL النموذج الفعلي
`store`	boolean	لا	تفضيل عام لتخزين الطلب؛ لم يُتحقق من تأثيره الخاص بالنموذج
`continuationToken`	string	لا	رمز عام معتم؛ لم تُثبت المتابعة ضمن إمكانات 3.1 Pro

معلمات التوليد

الحقل داخل `generationConfig`	النوع	القيمة الافتراضية والقيود
`maxOutputTokens`	integer	1–65,536، بما يشمل التفكير؛ القيمة الافتراضية للنموذج 65,536
`thinkingConfig`	object	`thinkingLevel`: `low`، `medium`، `high` (الافتراضي `high`)؛ تُقبل الكتابة بالأحرف الكبيرة. `includeThoughts`: boolean، الافتراضي false. `thinkingBudget`: integer، لا يُجمع مع `thinkingLevel`؛ لم يُثبت نطاق رقمي خاص بالنموذج
`temperature`	number	0–2؛ توصي Google بالقيمة الافتراضية 1.0
`topP`	number	0–1؛ احذفه لاستخدام القيمة الافتراضية للنموذج
`topK`	integer	اختياري؛ لم يُثبت نطاق قابل للضبط خاص بالنموذج
`candidateCount`	integer	1 بالضبط
`stopSequences`	string[]	خمس متتاليات كحد أقصى
`responseMimeType`	string	الافتراضي `text/plain`؛ يتطلب إخراج مخطط JSON القديم `application/json`
`responseSchema`	object	لهجة المخطط الرسمية؛ لا يُجمع مع `responseJsonSchema`
`responseJsonSchema`	JSON	JSON Schema؛ لا يُجمع مع `responseSchema`
`responseFormat`	object	إعدادات تنسيق النص؛ `text.mimeType` و`text.schema` الاختياري. يتطلب المخطط نوع MIME خاصاً بـ JSON
`responseModalities`	string[]	نص فقط: `TEXT`؛ القيمة الفارغة تعني نصاً
`mediaResolution`	enum	`MEDIA_RESOLUTION_UNSPECIFIED`، `LOW`، `MEDIUM`، `HIGH` بالبادئة `MEDIA_RESOLUTION_`
`seed`	integer	قيمة موقّعة من 32 بت؛ لم يُتحقق من السلوك الحتمي الخاص بالنموذج
`presencePenalty`	number	حقل عام؛ لم يُتحقق من تأثيره أو نطاقه الخاص بالنموذج
`frequencyPenalty`	number	حقل عام؛ لم يُتحقق من تأثيره أو نطاقه الخاص بالنموذج
`responseLogprobs`	boolean	حقل عام؛ لم يُتحقق من إتاحته الخاصة بالنموذج
`logprobs`	integer	0–20؛ يتطلب `responseLogprobs: true`؛ لم يُتحقق من دعم النموذج
`enableEnhancedCivicAnswers`	boolean	حقل عام؛ لم يُتحقق من دعم النموذج
`enableAffectiveDialog`	boolean	حقل عام؛ لم يُتحقق من دعم النموذج
`audioTranscriptionConfig`	object	حقل عام؛ لم يُتحقق من خياراته الخاصة بالنموذج
`translationConfig`	object	حقل عام؛ لم يُتحقق من خياراته الخاصة بالنموذج

يسرد مستند OpenAPI الأنواع المتداخلة وقيم التعداد والخصائص المطلوبة والحدود الموثّقة لكل رسالة. تصف المخططات المعلمات الرسمية؛ وليست قائمة سماح لطلبات SeedRouter. تُحفظ الحقول والقيم التي يقدّمها المستدعي. قبول المخطط لحقل لا يثبت دعمه في كل نموذج أو حساب. لا يدعم هذا النموذج التفكير minimal أو معالجة Agentic Video.

الإخراج المنظّم

{
  "contents": [{"parts": [{"text": "Return a JSON object with ok set to true."}]}],
  "generationConfig": {
    "thinkingConfig": {"thinkingLevel": "low"},
    "maxOutputTokens": 1024,
    "responseMimeType": "application/json",
    "responseJsonSchema": {
      "type": "object",
      "properties": {"ok": {"type": "boolean"}},
      "required": ["ok"]
    }
  }
}

لا يمكن استخدام الحقلين القديمين responseSchema وresponseJsonSchema معاً. يتطلب كلاهما responseMimeType: "application/json". يجب أن يحدّد مخطط responseFormat.text الأحدث JSON أيضاً. استخدم صيغ تعداد REST (APPLICATION_JSON وTEXT_PLAIN) في تلك الرسالة. تمرّ الطلبات من دون تغيير؛ ولا تُعاد كتابة أنواع MIME للوسائط أو JSON الحرّ للدوال.

الدوال والأدوات المضمّنة

استخدم tools[].functionDeclarations مع اسم وأحد الحقلين parameters أو parametersJsonSchema، وليس كليهما. تتبع مخططات الاستجابة قاعدة عدم الجمع نفسها. يُضبط اختيار الدوال في toolConfig.functionCallingConfig؛ ويتطلب allowedFunctionNames الوضع ANY أو VALIDATED وأسماء معلنة.

يدعم النموذج العادي استدعاء الدوال؛ ولا يلزم إصدار customtools. ينفّذ تطبيقك الدوال المعادة ويقدّم نتائجها في الدور التالي من المحادثة. احتفظ بكل thoughtSignature أصلي وكل استدعاء دالة واستجابة دالة. لا تقرّب المعرّفات الرقمية عند تسلسل وسيطات الدوال المعتمة.

تدرج Google كلاً من Search وMaps وتنفيذ الشيفرة وURL context ضمن إمكانات النموذج. يُدرج File Search لـ AI Studio فقط. تتطلب موارد التخزين المؤقت والبحث في الملفات الموجودة صلاحية وصول وفق بيانات الاعتماد التي تخدم الطلب. يظهر Computer Use وإعداد MCP الأصلي في المخطط العام، لكن لم تُثبت إتاحتهما لهذا النموذج. لا ينفّذ Playground دوالك المخصّصة.

الإدخال متعدد الوسائط والأمان

يحتوي العنصر contents[].parts[] على حمولة واحدة بالضبط: نص أو وسائط مضمّنة أو مرجع ملف أو استدعاء دالة/استجابة دالة أو جزء تنفيذ. وقد يحمل أيضاً توقيعاً أو بيانات وصفية للوسائط. يدعم الإدخال النصوص والصور والصوت والفيديو وملفات PDF؛ والإخراج نص فقط.

للبايتات المضمّنة، استخدم inlineData.mimeType وdata بتنسيق base64. لمراجع الملفات، استخدم fileData.mimeType وfileUri. لا يثبت URL الصحيح الصياغة قدرة النموذج على جلبه. يمكن لبيانات الفيديو الوصفية تحديد إزاحتي البداية والنهاية وقيمة fps موجبة لا تتجاوز 24. تختلف دقة الوسائط العامة عن الدقة المحدّدة لكل جزء. لا يُدعم Agentic Video.

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

تستخدم إعدادات الأمان التنسيق الأصلي الرسمي. يترك حذفها قيم Gemini API الافتراضية سارية؛ وتمرّ الإعدادات المقدّمة صراحةً من دون تغيير.

استجابات JSON والبث

تعيد generateContent استجابة JSON بالتنسيق الأصلي. ترسل streamGenerateContent?alt=sse كائنات JSON أصلية في أحداث SSE من نوع data:. تشمل الحقول المهمة candidates[].content.parts وfinishReason وsafetyRatings وgroundingMetadata وpromptFeedback وmodelVersion وresponseId وusageMetadata.

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

بخلاف Argon، لم تُثبت متابعة الإخراج الأطول في 3.1 Pro. لا تنشئ حلقة متابعة لمجرد أن مخطط الاستجابة العام يتضمن حقل رمز.

الاستخدام والأسعار

يشمل promptTokenCount الإدخال المخزّن مؤقتاً. تُحاسَب cachedContentTokenCount بسعر الإدخال المخزّن مؤقتاً، بدلاً من احتسابها مجدداً كإدخال غير مخزّن مؤقتاً. يشمل الإخراج المفوتر candidatesTokenCount إضافةً إلى thoughtsTokenCount. تسهم توكنات موجّه استخدام الأدوات المبلّغ عنها في الإدخال أيضاً.

عتبة السياق 200,000 توكن إدخال، بما فيها الإدخال المخزّن مؤقتاً؛ وتستخدم المدخلات الأكبر أسعار السياق الطويل. تستخدم مجموعات الحساب المتاحة معادلة سعر النموذج نفسها والمضاعف الحالي الخاص بكل منها. راجع جدول الأسعار المباشر.

Flex وPriority مستويان منفصلان للمعالجة. لا يخفض Flex أسعار الإدخال المخزّن مؤقتاً إلى النصف. يجب ألا تُفرض زيادة Priority على نتيجة يُبلّغ عنها بأنها Standard. إذا لم تثبت استجابة طُلبت بمستوى Priority مستواها الفعلي، يستخدم هذا التكامل أسعار توكنات Standard. رسوم الأدوات وتخزين الذاكرة المؤقتة الصريح منفصلة عن أسعار توكنات التوليد؛ ولا يُقدّم وعد بحصة أدوات مجانية مشتركة. لا تُفرض رسوم على الطلبات الفاشلة.

مجموعات حساب متعددة

يستخدم النموذج googlellm وgooglellm-vertext، مع الاحتفاظ بصلاحيات الحساب وأسعارهما الحالية. يجب كتابة اسم كل مجموعة مطابقاً تماماً. اختر مجموعة متاحة في Playground، أو استخدم ترويسة API الاختيارية:

X-SeedRouter-Group: googlellm

استخدم googlellm-vertext لاختيار المجموعة الثانية. تحدّد المجموعة المختارة السعر والسعة المتاحة؛ ولا يتحوّل الاختيار الصريح بصمت إلى مجموعة أخرى. احذف الترويسة أو استخدم auto للحفاظ على السلوك الافتراضي لمفتاح API.

تحقّق من المجموعات المتاحة لمفتاح API من دون توليد استجابة:

curl "https://api.seedrouter.ai/api/seedrouter/llm/groups?model=gemini-3.1-pro-preview"   -H "Authorization: Bearer YOUR_SEEDROUTER_KEY"

حالة التحقق

تتبع عناصر التحكم والوثائق التنسيق الأصلي الرسمي. تتولى Gemini API التحقق من المعلمات. لا تثبت اختبارات النقل والفوترة دون اتصال الإتاحة في الإنتاج. لا يزال التوليد الفعلي ومجموعتا الحساب وفهم الوسائط وموارد التخزين المؤقت والأدوات المضمّنة ومستويات المعالجة بحاجة إلى تحقق مدفوع من البداية إلى النهاية. لا ندّعي نتيجة مقارنة للجودة تخص إصدار Customtools.