DEV Community

Cover image for كيف تستخدم Gemini 3.7 Flash API؟
Yusuf Khalidd
Yusuf Khalidd

Posted on Originally published at apidog.com

كيف تستخدم 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، ولم يتغير سطح واجهة برمجة التطبيقات. إذا كنت تستخدم Gemini بالفعل، فكل ما تحتاجه هو تبديل معرف نموذج واحد.

جرّب Apidog اليوم

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

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

باختصار

  • معرف النموذج هو gemini-3.7-flash.
  • نقطة النهاية المتزامنة: 
  POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent
Enter fullscreen mode Exit fullscreen mode
  • استخدم الرأس x-goog-api-key: <KEY> للمصادقة.
  • الأسعار التمهيدية هي 0.75 دولار لكل مليون رمز إدخال و3.75 دولار لكل مليون رمز إخراج حتى 31 ديسمبر 2026. اعتبارًا من 1 يناير 2027، تصبح 1.50 دولار و7.50 دولار.
  • يدعم النموذج سياق إدخال بحجم مليون رمز مميز وحد إخراج يبلغ 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.
  • اختبر نقطة النهاية أولًا في 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.

مخطط شريطي يوضح التحسن في أداء Gemini 3.7 Flash مقارنة بـ 3.6 Flash في معايير DeepSWE و FrontierCode و AutomationBench و WebDev Arena Elo.

استخدم Gemini 3.7 Flash عندما:

  • تدير حلقات وكيلية: تضاعفت درجة AutomationBench تقريبًا. وهو مناسب لخطوط الأنابيب التي تعتمد على تخطيط متعدد الخطوات واستدعاءات أدوات متكررة.
  • تولد أو تراجع تعليمات برمجية: مكاسب 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: المسار الأسرع

  1. افتح aistudio.google.com/apikey.
  2. انقر Get API key.
  3. اختر مشروع Google Cloud.
  4. انسخ المفتاح.

يعمل المفتاح مباشرة مع generativelanguage.googleapis.com. توفر الطبقة المجانية حصة مناسبة للنماذج الأولية، ويتوفر Gemini 3.7 Flash في أكثر من 160 دولة.

Vertex AI: مسار الإنتاج

استخدم Vertex AI إذا كانت بنيتك التحتية تعمل على GCP وتحتاج إلى:

  • مصادقة OAuth عبر حسابات الخدمة أو الرموز قصيرة الأجل.
  • IAM.
  • سجلات التدقيق.
  • نقاط نهاية إقليمية.

في Vertex AI، تتغير نقطة النهاية إلى aiplatform.googleapis.com وآلية المصادقة، بينما يظل معرف النموذج وجسم الطلب متطابقين.

ابدأ بـ AI Studio للنماذج الأولية، ثم انتقل إلى Vertex AI قبل تمرير حركة إنتاج حقيقية.

صدّر المفتاح كمتغير بيئة:

export GEMINI_API_KEY="AIza..."
Enter fullscreen mode Exit fullscreen mode

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

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

استخدم هذه النقطة لطلب متزامن:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent
Enter fullscreen mode Exit fullscreen mode

وللتدفق باستخدام Server-Sent Events:

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

المصادقة تحتاج إلى الرأس التالي فقط:

x-goog-api-key: $GEMINI_API_KEY
Enter fullscreen mode Exit fullscreen mode

أول طلب عبر 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
    }
  }'
Enter fullscreen mode Exit fullscreen mode

تحتوي الاستجابة على مصفوفة candidates. يحتوي كل مرشح على:

  • content.parts: النص أو استدعاءات الدوال عند تعريف الأدوات.
  • finishReason: سبب توقف التوليد.
  • usageMetadata: أعداد رموز الإدخال والإخراج.

راقب usageMetadata في كل طلب، لأن رموز الإخراج تكلف خمسة أضعاف رموز الإدخال بالسعر التمهيدي.

تستخدم Gemini المخطط contents الذي يتكون من role وparts، وليس مخطط messages الشائع في واجهات OpenAI. انتبه لهذا التحويل عند الترحيل من مزود آخر.

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

ثبّت أو حدّث SDK الرسمي:

pip install --upgrade google-generativeai
Enter fullscreen mode Exit fullscreen mode

استخدم النموذج مع تعليمات نظام وإعدادات توليد:

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)
Enter fullscreen mode Exit fullscreen mode

لإرسال 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)
Enter fullscreen mode Exit fullscreen mode

هذا النمط مناسب لاستخراج بيانات منظمة من المستندات الواقعية غير المنتظمة.

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

استخدم حزمة @google/generative-ai:

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()));
Enter fullscreen mode Exit fullscreen mode

استخدم responseSchema مع responseMimeType: "application/json" لضمان أن يتلقى كودك كائن 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)
Enter fullscreen mode Exit fullscreen mode

في HTTP الخام، استخدم:

:streamGenerateContent?alt=sse
Enter fullscreen mode Exit fullscreen mode

يحتوي كل سطر data: على حمولة candidates جزئية. تصل usageMetadata في الكتلة النهائية، لذلك لا تحسب الاستخدام النهائي قبل إغلاق التدفق.

ضبط generationConfig

المعلمة النوع ماذا تفعل
maxOutputTokens عدد صحيح حد أقصى صارم للإخراج، حتى 64 ألف رمز مميز. أهم إعداد للتحكم بالتكلفة.
temperature عدد من 0 إلى 2. استخدم 0.2–0.4 للكود والاستخراج، و0.7+ للنصوص الإبداعية.
responseMimeType سلسلة اضبطها على application/json لطلب إخراج JSON.
responseSchema كائن يفرض شكلًا محددًا للإخراج عند استخدام نوع MIME الخاص بـ JSON.
topP عدد حد أخذ العينات النووية. اتركه افتراضيًا ما لم تكن تضبطه عمدًا.
stopSequences مصفوفة سلاسل توقف التوليد مبكرًا؛ مفيدة للتحليل القائم على المحددات.

رموز الإخراج تكلف 3.75 دولار لكل مليون رمز بالسعر التمهيدي، و7.50 دولار اعتبارًا من يناير 2027. حدّد maxOutputTokens بناءً على احتياج الحالة الفعلي بدل استخدام الحد الأقصى البالغ 64 ألفًا.

لأمثلة حساب التكلفة حسب عبء العمل، راجع تفصيل تسعير Gemini 3.7 Flash.

إلى جانب generationConfig، يدعم جسم الطلب:

  • tools: إعلانات الدوال، والبحث كأداة، واستخدام الحاسوب.
  • toolConfig: لتحديد سلوك استدعاء الأدوات أو فرضه.

لاستخدام الدوال، والاستدعاءات المتوازية، ونمط حلقة الاستجابة، راجع دليل استدعاء وظائف Gemini 3.7 Flash.

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

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

استخدم Apidog بهذه الخطوات:

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

بعد حفظ الطلبات، اربطها في سيناريوهات اختبار وتحقق من:

  • finishReason
  • مخطط الاستجابة
  • أعداد الرموز في usageMetadata

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

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

تحتوي أخطاء Gemini على كائن error في المستوى الأعلى، ويتضمن code وstatus وmessage.

الرمز الحالة المعنى الإصلاح
400 INVALID_ARGUMENT جسم الطلب غير صالح، أو دور غير صحيح، أو contents فارغ. تحقق من صحة الجسم في Apidog قبل الإرسال.
401 UNAUTHENTICATED المفتاح مفقود أو مُلغى. أعد تصدير GEMINI_API_KEY وتأكد من أن المفتاح نشط في AI Studio.
403 PERMISSION_DENIED المشروع لا يملك الوصول أو الفوترة المطلوبة. راجع إعدادات المشروع وحالة الفوترة.
429 RESOURCE_EXHAUSTED تم بلوغ حد المعدل أو الحصة اليومية. استخدم التراجع التدريجي، أو أرسل الطلبات على دفعات، أو رقِّ المستوى.
500 INTERNAL خطأ خادم عابر. أعد المحاولة بتراجع أسي.
503 UNAVAILABLE الخدمة مثقلة. أعد المحاولة بعد ثوانٍ؛ وفي Vertex جرّب منطقة أخرى.

ثلاث ممارسات ضرورية للإنتاج:

  • غلّف كل استدعاء بمنطق إعادة محاولة: عالج 429 وأخطاء 5xx باستخدام تأخير أسي متذبذب، مع تسجيل ومفتاح قطع دائرة قابل للتحكم.
  • لا تفترض أرقام حدود المعدل: تختلف الحدود حسب المستوى وتتغير بمرور الوقت. راجع القيم الحالية في صفحة تسعير وحدود Gemini API، واضبط التنبيهات عند 80% من الحصة.
  • ثبّت معرف النموذج في متغير بيئة: عند ظهور اختلاف سلوكي، يصبح الرجوع إلى 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 AI مصادقة OAuth مع aiplatform.googleapis.com ويضيف IAM وسجلات التدقيق ونقاط النهاية الإقليمية.

ابدأ بـ AI Studio، ثم انتقل إلى Vertex AI عند نمو حركة الإنتاج.

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

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

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

يدعم النموذج مليون رمز مميز للإدخال و64 ألف رمز مميز للإخراج. ورغم أن اختبار 128k-needle سجل 97.0%، فإن تقسيم المدخلات الطويلة يظل مفيدًا لتقليل تكلفة رموز الإدخال.

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

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

- gemini-3.6-flash
+ gemini-3.7-flash
Enter fullscreen mode Exit fullscreen mode

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

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

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

ابدأ عمليًا بهذه الخطة:

  1. نفّذ طلب cURL للتأكد من المفتاح وشكل الاستجابة.
  2. اختبر المطالبات المتزامنة والتدفقية في Apidog.
  3. احفظ استجابات مرجعية واستخدمها في اختبارات الانحدار.
  4. انقل الطلب المثبت إلى Python أو Node.js.
  5. ثبّت معرف النموذج خلف متغير بيئة، مع إبقاء مسار رجوع إلى gemini-3.6-flash.

عندما تتأكد من شكل حركة الطلب والاستجابة، يصبح نقل التكامل إلى التطبيق خطوة قصيرة بدل دورة طويلة من التخمين وإعادة التشغيل.

Top comments (0)