كيف تستخدم Gemini 3.7 Flash API؟

أطلقت Google نموذج Gemini 3.7 Flash في 13 أغسطس 2026، بعد ثلاثة أسابيع من إطلاق 3.6 Flash، وتصفه بأنه "نموذجها الأكثر ذكاءً وقدرة على إنجاز المهام الشاقة". الخبر الرئيسي للمطورين: قفزت درجات الترميز الوكيلية (agentic coding) بقوة (ارتفع DeepSWE v1.1 من 49.0% إلى 65.3%)، والسعر التمهيدي هو نصف سعر إطلاق 3.6 Flash، وواجهة برمجة التطبيقات (API surface) لم تتغير. إذا كنت تستخدم Gemini بالفعل، فما عليك سوى تبديل معرف نموذج واحد. وإذا لم تكن كذلك، فهذه هي أرخص نقطة دخول قدمتها Google على الإطلاق لنموذج بهذه القدرة.

هذا الدليل هو دليلك العملي السريع. ستحصل على مفتاح API، وتُجري مكالمتك الأولى باستخدام cURL، وتنقلها إلى Python و Node.js، وتدفق الاستجابات، وتضبط generationConfig، وتربط كل ذلك بـ Apidog لتتمكن من تكرار المطالبات دون حرق الرموز المميزة في حلقة تعليمات برمجية. المواصفات من الإعلان الرسمي: سياق 1M رمز مميز، إخراج 64k رمز مميز، إدخال متعدد الوسائط، استدعاء الدوال، البحث كأداة، واستخدام الحاسوب.

إذا قمت بالبناء باستخدام الجيل السابق، فإن شكل الطلب يتوافق مع دليل Gemini 3 Flash Preview API الخاص بنا؛ هذه المقالة تغطي كل ما هو جديد في سير عمل 3.7.

زر

باختصار

• معرف النموذج هو gemini-3.7-flash. نقطة النهاية: POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent مع الرأس x-goog-api-key: <KEY>.
• تبلغ الأسعار التمهيدية 0.75 دولار لكل مليون رمز إدخال و 3.75 دولار لكل مليون رمز إخراج حتى 31 ديسمبر 2026. اعتبارًا من 1 يناير 2027، ستتضاعف إلى 1.50 دولار و 7.50 دولار.
• المواصفات: سياق إدخال 1 مليون رمز مميز، وحد إخراج 64 ألف رمز مميز. يقبل الإدخال النصوص والصور ومقاطع الفيديو والصوت وملفات PDF. الإخراج هو نص.
• فروقات المعيارية مقارنة بـ 3.6 Flash: DeepSWE من 49.0% إلى 65.3%، FrontierCode من 34.4% إلى 43.6%، AutomationBench من 17.0% إلى 30.4%، WebDev Arena Elo من 1538 إلى 1588.
• يستخدم التدفق :streamGenerateContent?alt=sse. يحتفظ جسم الطلب بمخطط contents بالإضافة إلى generationConfig الخاص بـ Google.
• اختبر نقطة النهاية في Apidog قبل كتابة رمز التطبيق: استورد المواصفات، وخزّن المفتاح كمتغير بيئة، وشاهد أجزاء SSE وهي تظهر مباشرة.

ما الذي يميز Gemini 3.7 Flash

تضحي نماذج Flash ببعض الذكاء الأقصى من أجل السرعة والسعر، ويقلل الإصدار 3.7 هذا التبادل أكثر من أي إصدار سبقه. فروق المعايير مقارنة بـ 3.6 Flash كبيرة بشكل غير عادي لفترة ثلاث أسابيع: قفز DeepSWE v1.1 من 49.0% إلى 65.3%، و FrontierCode 1.1 Main من 34.4% إلى 43.6%، و AutomationBench من 17.0% إلى 30.4%. صعد WebDev Arena Elo 50 نقطة، من 1538 إلى 1588.

اقرأ هذه الأرقام كإشارة حول مدى ملاءمة عبء العمل. استخدم 3.7 Flash عندما:

• تدير حلقات وكيلية. تضاعفت درجة AutomationBench تقريبًا، وتقول Google إن النموذج "يفكر بجدية أكبر في التخطيط متعدد الخطوات واستدعاء الأدوات." تعد خطوط الأنابيب الوكيلية ذات المنعطفات العديدة القصيرة والمكثفة بالأدوات هي حالة الاستخدام المستهدفة.
• تولد أو تصحح التعليمات البرمجية. تدعي Google أن 3.7 أفضل في تصحيح الأخطاء وأكثر قدرة على إنتاج تعليمات برمجية قابلة للنشر من المحاولة الأولى. مكاسب DeepSWE و FrontierCode تدعم ذلك.
• تعالج المستندات. قفز GDP.pdf من 22.0% إلى 34.0%، و PDF هو نوع إدخال من الدرجة الأولى. يحتفظ استرجاع السياق الطويل أيضًا: 97.0% في اختبار 128k-needle.
• تحتاج إلى إدخال متعدد الوسائط بميزانية محدودة. يدخل النص والصور ومقاطع الفيديو والصوت وملفات PDF جميعها عبر نفس مصفوفة contents.

للحصول على تفاصيل الميزات الكاملة، بما في ذلك درجة Harvey LAB-AA في المجال القانوني البالغة 90.7%، والحماية المحدثة من CBRN والهجمات الإلكترونية، راجع ما هو الجديد في Gemini 3.7 Flash. سياق يستحق المعرفة: لا يزال Gemini 3.5 Pro متأخرًا، و تفيد Axios بأن Google تتعمد شحن تحديثات Flash قبل نموذجها الرئيسي التالي.

احصل على مفتاح API

هناك مساران، وهما ليسا متكافئين.

AI Studio (المسار السريع). افتح aistudio.google.com/apikey، انقر فوق Get API key، واختر مشروع Google Cloud، وانسخ السلسلة. يعمل المفتاح فورًا مع generativelanguage.googleapis.com، وتمنحك الطبقة المجانية حصة كافية لإنشاء النماذج الأولية. يتوفر Gemini 3.7 Flash في أكثر من 160 دولة.

Vertex AI (مسار الإنتاج). إذا كانت بنيتك التحتية تعيش على GCP، فاستخدم Vertex. يتحول المصادقة من مفتاح API إلى OAuth (حسابات الخدمة أو الرموز المميزة قصيرة الأجل)، وتُوجّه المكالمات عبر aiplatform.googleapis.com، وتحصل على IAM وسجلات التدقيق ونقاط نهاية إقليمية. يظل معرف النموذج وجسم الطلب متطابقين؛ يتغير فقط عنوان URL وآلية المصادقة.

ابدأ بإنشاء النماذج الأولية على AI Studio، ثم انتقل إلى Vertex قبل حركة مرور الإنتاج. في كلتا الحالتين، قم بتصدير المفتاح مرة واحدة:

export GEMINI_API_KEY="AIza..."

لا تقم أبدًا بتضمين المفتاح في التعليمات البرمجية مباشرة أو تمريره كمعلمة استعلام ?key= في الإنتاج؛ ينتهي الأمر بسلاسل الاستعلام في سجلات الخادم.

نقطة النهاية والمصادقة

نقطة النهاية الأساسية لاستدعاء متزامن:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent

يبدل التدفق لاحقة الطريقة ويضيف علامة SSE:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:streamGenerateContent?alt=sse

المصادقة هي رأس واحد: x-goog-api-key: $GEMINI_API_KEY. هذا هو handshake بأكمله. لا توجد رموز حامل، ولا مخطط توقيع، ولا إعداد جلسة.

أول طلب لك في cURL

إليك مكالمة عمل كاملة:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{ "text": "Review this SQL for injection risk: SELECT * FROM orders WHERE id = ${orderId}" }]
    }],
    "generationConfig": {
      "temperature": 0.3,
      "maxOutputTokens": 1024
    }
  }'

يعيد الرد مصفوفة candidates. يحمل كل مرشح كائن content مع parts (نص، أو استدعاءات دالة إذا قمت بتحديد أدوات) و finishReason. تعيش أعداد الرموز المميزة في usageMetadata في المستوى الأعلى؛ راقب هذه الكتلة، لأن الرموز المميزة للإخراج تكلف خمسة أضعاف ما تكلغه الرموز المميزة للإدخال بالسعر التمهيدي.

لاحظ المخطط: تستخدم Google contents مع role و parts، وليس شكل messages الخاص بـ OpenAI. احصل على هذا التعيين بشكل صحيح أولاً إذا كنت تقوم بالترحيل من مزود آخر.

دليل بدء سريع لـ Python

قم بتثبيت أو ترقية SDK الرسمي:

pip install --upgrade google-generativeai

استدعاء أساسي مع تعليمات نظام:

import os
import google.generativeai as genai

genai.configure(api_key=os.environ["GEMINI_API_KEY"])

model = genai.GenerativeModel(
    model_name="gemini-3.7-flash",
    system_instruction="You are a code reviewer. Flag issues as blocking or non-blocking.",
    generation_config={
        "temperature": 0.3,
        "max_output_tokens": 2048,
    },
)

response = model.generate_content(
    "Review this Flask route for security issues:\n\n"
    "@app.route('/user/<id>')\n"
    "def get_user(id):\n"
    "    return db.execute(f'SELECT * FROM users WHERE id = {id}')"
)

print(response.text)
print("input tokens:", response.usage_metadata.prompt_token_count)
print("output tokens:", response.usage_metadata.candidates_token_count)

يتم تضمين الإدخال متعدد الوسائط في نفس مصفوفة contents. لإرسال ملف PDF، قم بتحميله عبر Files API وأشر إليه كجزء:

invoice = genai.upload_file("q3-invoice.pdf")

response = model.generate_content([
    invoice,
    "Extract the invoice number, total, and due date as JSON.",
])
print(response.text)

يظهر مكسب معيار GDP.pdf (من 22.0% إلى 34.0%) في عبء العمل هذا بالضبط: استخراج منظم من المستندات الفوضوية الواقعية.

دليل بدء سريع لـ Node.js

إن Node SDK هو @google/generative-ai ويعكس شكل Python:

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-3.7-flash",
  generationConfig: {
    temperature: 0.3,
    maxOutputTokens: 2048,
    responseMimeType: "application/json",
    responseSchema: {
      type: "object",
      properties: {
        severity: { type: "string", enum: ["blocking", "non-blocking"] },
        issues: { type: "array", items: { type: "string" } },
      },
      required: ["severity", "issues"],
    },
  },
});

const result = await model.generateContent(
  "Review this Express handler: app.get('/search', (req, res) => res.send(eval(req.query.q)))"
);

console.log(JSON.parse(result.response.text()));

سطر responseSchema مهم أكثر مما يبدو. فهو يجبر المرشح على كائن قابل للتحليل، بحيث لا يلمس الكود النهائي نصًا حرًا. قم بإقرانه بـ responseMimeType: "application/json" وإلا سيتم تجاهله.

التدفق

بالنسبة لواجهات مستخدم الدردشة وأي شيء يواجه المستخدم، استخدم التدفق. في Python، أضف stream=True:

stream = model.generate_content(
    "Explain the N+1 query problem with a concrete ORM example.",
    stream=True,
)

for chunk in stream:
    if chunk.text:
        print(chunk.text, end="", flush=True)

عبر HTTP الخام، اطلب :streamGenerateContent?alt=sse وقم بتحليل أحداث خادم الويب (server-sent events). يحمل كل سطر data: حمولة candidates جزئية؛ تتضمن الكتلة النهائية usageMetadata، لذا فإن حساب الرموز المميزة يكون دقيقًا فقط بعد إغلاق التدفق.

ضبط generationConfig

المعلمات التي ستستخدمها غالبًا، بترتيب تقريبي حسب التأثير:

تكلف الرموز المميزة للإخراج 3.75 دولار لكل مليون بالسعر التمهيدي و 7.50 دولار اعتبارًا من يناير 2027، لذا قم بتحديد الإخراج بما يتطلبه حالة الاستخدام الخاصة بك، وليس السقف البالغ 64 ألفًا. توجد معادلة الرموز المميزة الكاملة، مع أمثلة عملية لكل عبء عمل، في تفصيل تسعير Gemini 3.7 Flash.

بخلاف generationConfig، يقبل جسم الطلب أيضًا tools (إعلانات الوظائف، البحث كأداة، استخدام الكمبيوتر) و toolConfig لفرض استدعاءات الأدوات. يعد استخدام الأدوات هو المجال الذي تحسن فيه 3.7 Flash أكثر من غيره، ويستحق دليلًا تفصيليًا خاصًا به: راجع دليل استدعاء وظائف Gemini 3.7 Flash للحصول على إعلانات واستدعاءات متوازية ونمط حلقة الاستجابة.

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

تكرار المطالبات داخل نص Python البرمجي بطيء ومكلف: التعديل، إعادة التشغيل، التمرير، التكرار، وكل دورة تستهلك رموزًا مميزة. الحلقة الأسرع هي قفل شكل الطلب في عميل API أولاً، ثم نقله إلى التعليمات البرمجية بمجرد أن تبدو الاستجابات صحيحة.

يتعامل Apidog مع مخطط طلب Gemini أصلاً. الإعداد:

1. أنشئ مشروعًا واستورد مواصفات Generative Language API OpenAPI من وثائق Google API. تصل المجموعة مُسماة مسبقًا، لذا فإن generateContent على بعد بحث واحد.
2. أضف متغير بيئة باسم GEMINI_API_KEY وقم بربطه برأس x-goog-api-key على مستوى البيئة. يرثه كل طلب، ولا يظهر المفتاح أبدًا في جسم طلب محفوظ.
3. خزّن معرف النموذج كمتغير مضبوط على gemini-3.7-flash. عندما ترغب في إجراء اختبار A/B مقابل gemini-3.6-flash، يمكنك تغيير متغير واحد بدلاً من تعديل عناوين URL عبر عشرات الطلبات المحفوظة.
4. أنشئ مصفوفة contents في محرر JSON المرئي. تُعرض الأجزاء المتداخلة بوضوح، ويكشف التحقق من صحة المخطط عن أي جسم طلب غير سليم قبل أن تنفق رمزًا مميزًا واحدًا على خطأ 400.
5. اطلب نقطة نهاية التدفق. يعرض Apidog أجزاء SSE مباشرة، حتى تتمكن من مشاهدة تجميع الإجابة بالضبط بالطريقة التي سيراها بها SDK الخاص بك، بما في ذلك زمن الانتقال.
6. احفظ الاستجابات الجيدة كأمثلة. ستصل عمليات الاختبار اللاحقة إلى البيانات الثابتة (fixture) بدلاً من API المباشر. هذا هو أكبر موفر للرموز المميزة في سير العمل بأكمله.

بمجرد حفظ الطلبات، قم بربطها في سيناريوهات اختبار مع تأكيدات على finishReason، ومخطط الاستجابة، وعدد الرموز المميزة في usageMetadata. وهذا يحول اختبار الضغط اليدوي إلى مجموعة اختبار تراجعي يمكنك تشغيلها مع كل تغيير في المطالبة؛ يتم تناول نفس النمط الذي تستخدمه فرق ضمان الجودة في دليل اختبار API لمهندسي ضمان الجودة.

معالجة الأخطاء وحدود المعدل

تُرجع أخطاء Gemini كائن error على المستوى الأعلى يتضمن code و status و message. هذه هي الأخطاء التي ستواجهها:

ثلاث عادات تحافظ على استقرار الإنتاج:

• لف كل استدعاء في مساعد إعادة المحاولة الذي يتعامل مع الأخطاء 429 و 5xx مع تأخير أسي متذبذب. تعيد SDKs المحاولة عدة مرات بمفردها، لكن غلافًا رقيقًا يمنحك تسجيلًا وقطع دائرة يمكنك التحكم فيه.
• لا تخترع أرقام حدود معدل. تختلف الحدود حسب المستوى وتتغير بمرور الوقت؛ اقرأ القيم المباشرة على صفحة تسعير وحدود Gemini API وقم بالتنبيه عند 80% من الحصة.
• ثبت معرف النموذج خلف متغير بيئة. إذا تسبب تغيير سلوك 3.7 في تعطيل مطالبة، يصبح التراجع إلى gemini-3.6-flash تغييرًا في التكوين بدلاً من نشر.

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

هل Gemini 3.7 Flash مجاني للاستخدام؟

يقدم AI Studio طبقة مجانية بحصة يومية كافية لإنشاء النماذج الأولية، والسعر التمهيدي المدفوع هو 0.75 دولار لكل مليون رمز إدخال حتى 31 ديسمبر 2026. إذا كنت ترغب في تمديد المسار المجاني، يغطي دليلنا حول الوصول المجاني إلى Gemini API المستويات وحدودها.

ما الفرق بين استدعائه عبر AI Studio و Vertex AI؟

نفس النموذج، نفس جسم الطلب، آلية عمل مختلفة. يستخدم AI Studio مفتاح API مقابل generativelanguage.googleapis.com؛ بينما يستخدم Vertex OAuth مقابل aiplatform.googleapis.com ويضيف IAM وتسجيل التدقيق ونقاط النهاية الإقليمية. ابدأ في AI Studio، وتدرج إلى Vertex عندما يصبح حجم الحركة حقيقيًا.

هل يمكنني إرسال الصور والصوت وملفات PDF إلى Gemini 3.7 Flash؟

نعم. الإدخال متعدد الوسائط: تنتقل النصوص والصور والفيديو والصوت وملفات PDF جميعها كأجزاء في مصفوفة contents، إما مضمنة كـ base64 أو بالإشارة إليها عبر Files API. الإخراج هو نص فقط.

ما هو حجم نافذة السياق وحد الإخراج؟

1 مليون رمز مميز للإدخال، 64 ألف رمز مميز للإخراج. تشير درجة استرجاع 128k-needle البالغة 97.0% إلى أن استدعاء السياق الطويل موثوق به بشكل جيد يتجاوز ما تحتاجه معظم التطبيقات، لكن تقسيم المدخلات الطويلة لا يزال يوفر المال لأن كل رمز إدخال يتم فوترته.

هل يجب علي الترقية من Gemini 3.6 Flash؟

بالنسبة لأعباء عمل الوكلاء والبرمجة، الفجوات في المعايير كبيرة بما يكفي ليكون الجواب عادة نعم، وتبديل معرف النموذج هو سطر واحد. الاختلافات السلوكية التي تستحق اختبار الانحدار قبل قلب حركة الإنتاج مغطاة في دليل ترحيل 3.6 إلى 3.7 Flash.

مكانة 3.7 Flash في بنيتك التحتية

يعد Gemini 3.7 Flash إصدارًا نادرًا انخفض فيه السعر بينما ارتفعت القدرة. حتى نهاية عام 2026، ستدفع نصف سعر إطلاق 3.6 Flash لنموذج يحقق 16 نقطة أعلى في DeepSWE وضعفًا تقريبًا في AutomationBench. الافتراضي المنطقي: وجه حلقات الوكيل، ومهام التعليمات البرمجية، واستخراج المستندات إلى 3.7 Flash الآن، ضع في اعتبارك فترة السعر التمهيدي لتخطيط الميزانية، واحتفظ بمسار تراجع إلى 3.6 خلف متغير بيئة.

ابدأ باستدعاء cURL أعلاه، وتأكد من شكل الاستجابة، ثم انقل الطلب إلى عميل API قبل كتابة رمز التطبيق. قم بتنزيل Apidog لاستيراد مواصفات Gemini، وربط مفتاحك مرة واحدة، واختبار الطلبات المتزامنة والتدفقية واستدعاء الأدوات من مساحة عمل واحدة. عندما تكون المطالبة صحيحة، يستغرق نقلها إلى Python أو Node دقائق لأنك تعرف بالفعل كيف تبدو حركة المرور السلكية.