دليل استخدام Gemini 3.8 Flash API: API التفاعلات، مستويات التفكير، وأول استدعاء في Apidog

أصدرت جوجل Gemini 3.8 Flash في 2 سبتمبر 2026، ومعرف نموذج واجهة برمجة التطبيقات (API model ID) هو السلسلة النصية الواضحة gemini-3.8-flash، بدون لاحقة معاينة. يحتفظ بسعر Gemini 3.7 Flash التمهيدي البالغ 0.75 دولار لكل مليون رمز إدخال و 3.75 دولار لكل مليون رمز إخراج حتى 31 ديسمبر 2026، وتصفه جوجل بأنه نموذج "يعمل بجهد أكبر": فهو يتخذ المزيد من خطوات الاستدلال ويستدعي الأدوات في كثير من الأحيان في المهام المعقدة، مما يظهر في فاتورة الرموز الخاصة بك.

يغطي هذا الدليل المسار الكامل لتكامل عملي: الحصول على مفتاح في AI Studio، إرسال أول طلب عبر Interactions API (واجهة برمجة تطبيقات جوجل الرئيسية لـ Gemini 3.x الآن)، مكافئ generateContent القديم الذي لا يزال معظم الكود الحالي يستخدمه، أين يذهب thinking_level في كل منهما، البث المباشر (streaming)، وكيفية قراءة thoughtsTokenCount حتى لا تفاجئك تكلفة التفكير أبدًا. كل استدعاء هو HTTP عادي مع JSON، لذا يمكنك بناء واختبار كل منها في Apidog قبل أن يدخل في كود التطبيق.

للحصول على نظرة عامة عن النموذج والمعايير وما الذي تغير، ابدأ بـ ما هو Gemini 3.8 Flash. يحتوي منشور إطلاق جوجل على الإطار الرسمي.

نظرة سريعة على Gemini 3.8 Flash API

تفصيلان بارزان قبل أن تكتب الكود. مستوى التفكير الافتراضي هو medium، وليس high كما في Gemini 3 Pro. ويتم احتساب رموز التفكير بسعر الإخراج على صفحة التسعير الرسمية، لذا فإن المستوى الذي تختاره هو قرار يتعلق بالتكلفة بقدر ما هو قرار يتعلق بالجودة. يعرض تفصيل التسعير الأرقام لكل مهمة.

الخطوة 1: الحصول على مفتاح API في AI Studio

افتح Google AI Studio، سجل الدخول باستخدام حساب جوجل، وأنشئ مفتاح API من صفحة المفاتيح. يعمل المفتاح على المستوى المجاني فورًا، مع حدود للمعدل وتحذير بأن جوجل تقول إن بيانات المستوى المجاني "تستخدم لتحسين منتجاتنا". اربط حساب فوترة للانتقال إلى المستوى 1 (Tier 1) للحصول على حدود الإنتاج.

export GEMINI_API_KEY="AIza..."

تقرأ حزمة SDK الرسمية لـ Python مفتاح GEMINI_API_KEY من البيئة، لذا لا يحتاج genai.Client() إلى أية وسيطات. قم بتثبيتها باستخدام pip install google-genai.

الخطوة 2: أول استدعاء لك باستخدام Interactions API

تعتبر جوجل الآن Interactions API الطريقة الأساسية لاستدعاء نماذج Gemini 3.x. الطلب هو كائن JSON واحد: النموذج، input، و generation_config اختياري حيث يوجد thinking_level.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain HTTP caching in 3 sentences.",
    "generation_config": {"thinking_level": "medium"}
  }'

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

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain HTTP caching in 3 sentences.",
    generation_config={"thinking_level": "medium"},
)

print(interaction.output_text)

اترك temperature و top_p و top_k خارجًا. إرشادات جوجل لكل نموذج من نماذج Gemini 3 هي إبقاء درجة الحرارة على قيمتها الافتراضية 1.0، لأن خفضها "قد يسبب حلقات أو أداءً متدهورًا". إذا نسخت إعدادًا من نموذج أقدم، فهذا هو السطر الأول الذي يجب حذفه.

الخطوة 3: المحادثات متعددة الأدوار باستخدام previous_interaction_id

تحتفظ Interactions API بحالة المحادثة على الخادم افتراضيًا. لمتابعة محادثة، أرسل id الاستجابة السابقة كـ previous_interaction_id مع إدخال المستخدم الجديد فقط. لا تعيد إرسال السجل.

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    input="Now give one example of a Cache-Control header.",
    previous_interaction_id=interaction.id,
)
print(follow_up.output_text)

إذا كانت قواعد الامتثال الخاصة بك تحظر التخزين من جانب الخادم، فقم بتعيين store: false. المفاضلة هي أنك تدير الحالة بنفسك، بما في ذلك إرسال كتل تفكير النموذج وتوقيعات التفكير مرة أخرى تمامًا كما تلقيتها في كل دورة. هذه هي نفس القاعدة التي تعيق استخدام الأدوات، والمغطاة في دليل استدعاء الوظائف لـ 3.8 Flash.

الخطوة 4: مسار generateContent القديم

لا يزال معظم كود Gemini في الإنتاج يستدعي generateContent. تسميها جوجل قديمة، لكنها "مدعومة بالكامل" بدون تاريخ إيقاف، لذا لا يتعين عليك إعادة كتابة أي شيء اليوم. غطى دليل Gemini 3.7 Flash API الخاص بنا هذا المسار فقط؛ الشكل متطابق لـ 3.8 Flash، ويقع إعداد التفكير في مكان مختلف عما هو عليه في Interactions.

في generateContent، يقع المستوى تحت generationConfig.thinkingConfig.thinkingLevel، بصيغة camelCase:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Explain HTTP caching in 3 sentences."}]}],
    "generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
  }'

يستخدم مكافئ بايثون كائنات تكوين محددة النوع:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain HTTP caching in 3 sentences.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
print(response.text)

إذا كنت قادمًا من إعداد استخدم thinking_budget كعدد صحيح، فاستبدله بالتعداد النصي (string enum). كما تم حذف candidate_count في Gemini 3 وما بعده. تقع القائمة الكاملة، مع JSON قبل وبعد كل تغيير، في دليل الترحيل من 3.7 إلى 3.8 Flash.

إليك نفس مجموعة الاهتمامات جنبًا إلى جنب، حتى تتمكن من الترجمة بين واجهتي برمجة التطبيقات دون إعادة قراءة كلا الوثيقتين:

الخطوة 5: البث المباشر وقراءة تكلفة التفكير

لواجهات الدردشة، استبدل اسم الطريقة بـ streamGenerateContent وأضف ?alt=sse للحصول على أحداث مرسلة من الخادم (server-sent events)، جزء جزئي واحد من candidates لكل حدث:

curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"List three HTTP caching headers."}]}]}'

سواء كان بثًا مباشرًا أم لا، تنتهي كل استجابة generateContent بكائن usageMetadata. اقرأه في كل استدعاء:

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}

thoughtsTokenCount هو الرقم الذي يجب مراقبته في 3.8 Flash. يتم احتساب رموز التفكير كرموز إخراج بسعر 3.75 دولار لكل مليون خلال الفترة التمهيدية، وتصرح جوجل بأن النموذج "قد يستخدم المزيد من الرموز لزيادة الأداء، خاصة في مستويات الجهد العالية". قامت Artificial Analysis بقياس حوالي 48 ألف رمز إخراج لكل مهمة في تشغيلها على مستوى high، بزيادة 30% عن 3.7 Flash، مما دفع التكلفة لكل مهمة من 0.40 دولار إلى 0.58 دولار بأسعار رمزية لم تتغير. جاءت تشغيلاتهم على مستويي medium و low بتكلفة 0.41 دولار و 0.24 دولار لكل مهمة على التوالي. يحول دليل مستويات التفكير هذه الأرقام إلى استراتيجية لكل مسار.

لمعرفة ما استدل عليه النموذج، أضف “includeThoughts”: true داخل thinkingConfig. تعود ملخصات التفكير كأجزاء موسومة بـ “thought”: true؛ تخطى هذه الأجزاء عند تجميع الإجابة المرئية.

أخطاء ستواجهها في الساعة الأولى

• thinking_level: "minimal" يفشل في التحقق. يدعم Gemini 3.8 Flash فقط low و medium و high. إرسال minimal يعيد خطأ 400 INVALID_ARGUMENT مع الرسالة "Thinking level MINIMAL is not supported for this model. Please retry with other thinking level." (تم التحقق من ذلك باستدعاء مباشر في 3 سبتمبر 2026)، والحل هو تغيير كلمة واحدة إلى low. تعد إعدادات 3.x القديمة والمقتطفات المنسوخة هي المصدر المعتاد.
• 429 يعني أنك وصلت إلى حد مستواك، وليس خطأ برمجيًا. تشرح صفحة حدود المعدل المستويات: المستوى المجاني محدود المعدل، يفتح المستوى 1 (Tier 1) عند ربط حساب فوترة، يتطلب المستوى 2 (Tier 2) إنفاق 100 دولار بالإضافة إلى ثلاثة أيام، ويتطلب المستوى 3 (Tier 3) 1000 دولار بالإضافة إلى 30 يومًا. يتم عرض أرقام الطلبات في الدقيقة والرموز في الدقيقة لكل نموذج فقط في صفحة حدود المعدل في AI Studio لحسابك، لذا تحقق هناك بدلاً من الوثوق برقم من منشور مدونة. عند 429، تراجع وحاول مرة أخرى؛ في حالات 429 المتكررة بكمية منخفضة، قم بترقية المستوى. للمهام غير المتصلة بالإنترنت، Batch API هو الحل الأفضل: يعمل بخصم 50% (0.375 دولار / 1.875 دولار لكل مليون رمز خلال الفترة التمهيدية) ولديه حدوده الخاصة للرموز المضافة إلى قائمة الانتظار تبلغ 3 ملايين في المستوى 1، و 400 مليون في المستوى 2، و مليار في المستوى 3. يوضح دليل وضع الدفعة في Gemini شكل الطلب.
• فقدان call_id في نتيجة وظيفة. إذا كنت تستخدم الأدوات، يجب أن يحمل كل function_result (Interactions) كلاً من call_id و name في 3.8 Flash، ويجب أن يحمل كل functionResponse القديم id المطابق بالإضافة إلى name. حذف أي منهما يفشل الدور.

اختبر كلتا نقطتي النهاية في Apidog قبل إطلاقهما

بمجرد أن يعمل كلا الطلبين من الطرفية (terminal)، انقلها إلى مكان يمكن للفريق بأكمله تشغيلها. قم بتنزيل Apidog، أنشئ مشروعًا، وأضف نقطتي النهاية أعلاه كطلبات محفوظة. أربع عادات تؤتي ثمارها:

• أبعد المفتاح عن الطلب. أضف GEMINI_API_KEY كمتغير بيئة وارجع إليه كـ {{GEMINI_API_KEY}} في رأس x-goog-api-key. لا يحتوي الطلب المحفوظ أبدًا على السر، والتبديل بين مفتاح المستوى المجاني ومفتاح مدفوع هو تغيير بيئة واحد.
• تحقق من الحالة واستخدام الرموز. أضف تأكيدًا بأن الحالة هي 200، ثم تأكيد مسار JSON بأن usageMetadata.thoughtsTokenCount يبقى أقل من حد أقصى تختاره لكل موجه. هذا الحد الأقصى هو إنذار انحدار التكلفة لديك: إذا أدت تحديث موجه أو تغيير صامت في النموذج إلى زيادة رموز التفكير، فسيفشل الاختبار قبل أن تفشل الفاتورة. يغطي دليل اختبار SSE البديل للبث المباشر، والذي يعرضه Apidog كتدفق أحداث مدمج بدلاً من أجزاء خام.
• أرسل نفس الموجه بجميع المستويات الثلاثة. كرر الطلب مع low و medium و high، وقارن thoughtsTokenCount ووقت الاستجابة جنبًا إلى جنب. يمنحك ذلك أرقامًا حقيقية لموجهاتك بدلاً من متوسطات المؤشر.
• جدولتها. حول الطلبات إلى سيناريو اختبار وقم بتشغيلها على جدول زمني، بحيث يظهر تغيير في حد المعدل، أو تغيير في التحقق مثل إزالة minimal، أو ارتفاع في الرموز في تقرير، وليس في الإنتاج. كيفية جدولة اختبارات API في Apidog يشرح الإعداد.

لا يقوم Apidog بتشغيل النموذج أو استبدال حزمة SDK. بل يمنحك نسخة محفوظة وقابلة للمشاركة والتحقق من استدعاءات HTTP، وهو الجزء الذي يتجاهله معظم الفرق حتى يتعطل شيء ما.

الأسئلة الشائعة

• أي نقطة نهاية يجب أن تستخدمها المشاريع الجديدة؟ Interactions API. تسمي جوجل generateContent قديمة، وهي لا تزال مدعومة بالكامل، ولكن الميزات الجديدة تهبط على Interactions أولاً وحالة الخادم تجعل كود المحادثات متعددة الأدوار أقصر. احتفظ بـ generateContent للخدمات الحالية حتى يكون لديك سبب للترحيل.
• هل أحتاج إلى حساب مدفوع لاستدعاء Gemini 3.8 Flash؟ لا. يعمل مفتاح AI Studio المجاني، مع حدود للمعدل وشروط استخدام البيانات من جوجل. يسرد دليل الاستخدام المجاني ما سيمنحه لك المستوى المجاني وما لن يمنحه، بما في ذلك حقيقة أن تطبيق Gemini يتطلب خطة AI Pro أو Ultra لـ 3.8 Flash.
• هل 3.8 Flash أبطأ من 3.7 Flash؟ لكل رمز، لا. قال لوغان كيلباتريك من جوجل إنه بنفس السرعة تقريبًا، وقامت Artificial Analysis بقياس حوالي 300 رمز إخراج في الثانية. لكل مهمة يستغرق وقتًا أطول عند مستوى high (2.5 دقيقة مقابل 2.2 في تشغيلاتهم) لأنه يولد المزيد من الرموز.
• هل يمكنني الاستمرار في استدعاء Gemini 3.7 Flash؟ نعم. تقول جوجل إن 3.7 Flash "مدعوم بالكامل" ولم تنشر أي تاريخ لإيقافه. إذا لم يوفر لك الإنفاق الإضافي للرموز على 3.8 Flash أي فائدة لمهامك، فإن البقاء على ما هو عليه خيار صحيح.
• هل يدعم 3.8 Flash Live API أو توليد الصور؟ لا. إنه ينتج نصًا فقط. لا يتم دعم توليد الصوت وتوليد الصور و Live API في هذا النموذج.

إلى أين تتجه بعد ذلك

لديك الآن مساران عمليان للاستدعاء، ونمط متعدد الأدوار، وفحص استخدام الرموز. من هنا، قم بتوصيل الأدوات باستخدام دليل استدعاء الوظائف، وحدد مستوياتك لكل مسار باستخدام منشور مستويات التفكير، وإذا كنت لا تزال تقرر ما إذا كنت ستنتقل أم لا، فإن مقارنة 3.8 Flash مقابل 3.7 Flash توضح المقايضة. حافظ على تشغيل سيناريو Apidog بحيث يظهر انحراف التكلفة كاختبار فاشل.