كيفية استخدام واجهة برمجة تطبيقات Gemini 3.5 Flash؟

تم إطلاق واجهة برمجة تطبيقات Gemini 3.5 Flash مع إطلاق النموذج في 19 مايو 2026. Flash هو المتغير الوحيد لعائلة 3.5 المتاح اليوم؛ يصل Pro في يونيو. يرشدك هذا الدليل خلال الإعداد الكامل للمطور لـ Flash: الحصول على مفتاح، إجراء أول مكالمة لك، التعامل مع المدخلات المتعددة الوسائط، التدفق، استخدام الأدوات، واختبار كل شيء بشكل صحيح باستخدام Apidog.

إذا كنت قد استخدمت واجهة برمجة تطبيقات Gemini من قبل، فإن النمط لم يتغير. القطعة الجديدة الوحيدة هي سلسلة اسم النموذج: gemini-3.5-flash. إذا كنت جديدًا في هذا المجال، يمكنك إجراء طلبات Flash تعمل في حوالي عشر دقائق.

ما تحصل عليه مع واجهة برمجة تطبيقات Gemini 3.5 Flash

ثلاثة أشياء مهمة في اليوم الأول:

gemini-3.5-flash: مباشر الآن، سريع، رخيص، متعدد الوسائط
نقطة نهاية بنفس نمط OpenAPI: بديل مباشر للمشاريع التي تستدعي بالفعل Gemini 3 أو 3.1
طبقة مجانية على AI Studio: حوالي 1,500 طلب/يوم بدون بطاقة ائتمان

القدرات المكشوفة من خلال واجهة برمجة تطبيقات Flash:

سياق إدخال 1M توكن، إخراج 64K توكن
إدخال نص + صورة، إخراج نص + منظم
استدعاء وظائف أصلي واستخدام الأدوات (83.6% MCP Atlas)
استجابات متدفقة (أسرع بحوالي 4 مرات في إخراج التوكنات/الثانية من النماذج الرائدة الأخرى)
تسجيل استرجاع السياق الطويل في قمة جدول Google MRCR v2
تحليل الرسوم البيانية والمستندات (84.2% CharXiv)

للحصول على تفاصيل التسعير بما في ذلك أسعار التوكنات الفردية وخصومات وضع الدُفعات، راجع دليل تسعير Gemini 3.5 Flash.

الخطوة 1: احصل على مفتاح واجهة برمجة تطبيقات Gemini 3.5 Flash الخاص بك

مساران، اعتمادًا على ما إذا كنت تريد حصصًا مجانية أو نطاقًا مدفوعًا.

المسار أ، Google AI Studio (الطبقة المجانية)

اذهب إلى aistudio.google.com
سجل الدخول باستخدام حساب Google
انقر على الحصول على مفتاح API في شريط التنقل الأيسر
اختر مشروعًا موجودًا أو أنشئ واحدًا
انقر على إنشاء مفتاح API، ثم انسخه

هذا هو نفس التدفق المغطى في دليل مفتاح واجهة برمجة تطبيقات Gemini المجاني الخاص بنا. يعمل المفتاح مع gemini-3.5-flash فورًا مع الحصة اليومية المجانية.

المسار ب، Vertex AI (للإنتاج)

لأعباء العمل الإنتاجية مع الفوترة وسجلات التدقيق:

قم بتمكين واجهة برمجة تطبيقات Vertex AI في وحدة تحكم Google Cloud
أنشئ حساب خدمة باستخدام aiplatform.user
قم بتنزيل بيانات الاعتماد JSON
المصادقة عبر gcloud auth application-default login أو ملف JSON

تُوجّه Vertex Flash ضمن نمط SDK مختلف قليلاً. تبدأ معظم الفرق باستخدام AI Studio وتنتقل عند الحاجة إلى ضوابط المؤسسة.

الخطوة 2: تثبيت حزمة SDK

تتوفر حزمة SDK الرسمية لـ Google GenAI للغات Python و Node.js و Go و Java. اختر لغتك:

# بايثون
pip install -U google-genai

# Node.js
npm install @google/genai

# Go
go get google.golang.org/genai

لست بحاجة إلى حزمة SDK على الإطلاق إذا كنت تستدعي نقطة نهاية REST مباشرة، راجع مثال curl أدناه.

الخطوة 3: إجراء أول استدعاء Flash لك

بايثون

import os
from google import genai

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

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how OAuth 2.0 PKCE flow works in 3 short paragraphs."
)

print(response.text)

Node.js

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: "Explain how OAuth 2.0 PKCE flow works in 3 short paragraphs.",
});

console.log(response.text);

curl

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "Explain how OAuth 2.0 PKCE flow works in 3 short paragraphs."}]
    }]
  }'

هذا هو المسار السعيد لـ Flash. من هنا، تقوم بإضافة الميزات التي تحتاجها بالفعل.

الاستجابات المتدفقة

مخرجات Flash سريعة. التدفق يجعل السرعة مرئية لمستخدميك.

بايثون

stream = client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Write a 5-step tutorial on writing a REST API client in Go."
)

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

Node.js

const stream = await ai.models.generateContentStream({
  model: "gemini-3.5-flash",
  contents: "Write a 5-step tutorial on writing a REST API client in Go.",
});

for await (const chunk of stream) {
  process.stdout.write(chunk.text);
}

تتغير نقطة النهاية من :generateContent إلى :streamGenerateContent لاستدعاءات REST الخام.

المدخلات المتعددة الوسائط مع Flash

يأخذ Gemini 3.5 Flash الصور جنبًا إلى جنب مع النص. درجة CharXiv Reasoning البالغة 84.2% حقيقية، وفهم المخططات يعمل بالفعل على هذا النموذج.

بايثون (صورة من القرص)

import os
from google import genai
from google.genai import types

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

with open("dashboard.png", "rb") as f:
    image_bytes = f.read()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        types.Part.from_bytes(data=image_bytes, mime_type="image/png"),
        "Extract every metric in this dashboard as a JSON object."
    ]
)

print(response.text)

أنواع MIME المدعومة: image/png، image/jpeg، image/webp، image/heic، image/heif. تعمل ملفات PDF والفيديو أيضًا عبر types.Part.from_uri().

استدعاء الوظائف واستخدام الأدوات مع Flash

استدعاء الأدوات هو ما يميز Flash عن أسلافه. تعني درجة MCP Atlas البالغة 83.6% أن Flash يختار الأداة الصحيحة بشكل أكثر موثوقية من جيل 3.1.

بايثون

from google.genai import types

weather_tool = types.Tool(
    function_declarations=[{
        "name": "get_current_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["city"]
        }
    }]
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What's the weather in Singapore right now?",
    config=types.GenerateContentConfig(tools=[weather_tool])
)

for part in response.candidates[0].content.parts:
    if part.function_call:
        print(f"Call: {part.function_call.name}")
        print(f"Args: {dict(part.function_call.args)}")

يعيد Flash كائن function_call بالاسم والوسائط. تقوم بتنفيذ الوظيفة محليًا، وإرسال النتيجة مرة أخرى، ومتابعة المحادثة. يتطابق النمط مع ما تستخدمه الفرق بالفعل مع واجهة برمجة تطبيقات Gemini 3 Flash.

الإخراج المنظم (وضع JSON)

اجبر Flash على إخراج JSON عن طريق تعيين نوع MIME للاستجابة ومخططها:

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="List 3 popular API testing tools with their pricing.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema={
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "price_per_month": {"type": "number"},
                    "free_tier": {"type": "boolean"}
                },
                "required": ["name", "free_tier"]
            }
        }
    )
)

import json
data = json.loads(response.text)

JSON تم التحقق منه في كل استدعاء. لا يوجد تحليل باستخدام التعابير النمطية، ولا حلقات إعادة المحاولة.

التسعير (اعتبارًا من مايو 2026)

أسعار الدفع حسب الاستخدام لـ gemini-3.5-flash:

الفئة	الإدخال	الإخراج
قياسي	~1.50 دولار / 1 مليون توكن	~9.00 دولارات / 1 مليون توكن
الإدخال المخزن مؤقتًا	سعر مخفض	غير متوفر
وضع الدُفعات	خصم ~50%	خصم ~50%

لأعباء عمل الدُفعات، يمنحك وضع الدُفعات في واجهة برمجة تطبيقات Gemini خصمًا بنسبة 50% على المهام التي لا تحتاج إلى زمن استجابة فوري. يستحق التحقق قبل الالتزام بالتوسع.

للحصول على تفاصيل التسعير الكاملة بما في ذلك سيناريوهات التكلفة الحقيقية لأعباء عمل SaaS اليومية وحلقات الوكيل، راجع تحليل تسعير Flash الخاص بنا. للمرجع الرسمي من Google، راجع تسعير واجهة برمجة تطبيقات Gemini للمطورين.

اختبار دمج Gemini 3.5 Flash الخاص بك مع Apidog

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

يتعامل Apidog مع سطح واجهة برمجة تطبيقات Gemini Flash بالكامل في مساحة عمل واحدة:

احفظ نقطة نهاية Flash كطلب: الصق عنوان URL الكامل، أرفق مفتاح x-goog-api-key الخاص بك، واضغط على إرسال
إعادة التشغيل عبر إصدارات النموذج: استبدل gemini-3.5-flash بـ gemini-3-flash الأقدم على نفس الطلب، وقم بمقارنة المخرجات
تدفق الاستجابات مباشرة: يعرض Apidog أجزاء التدفق فور وصولها، مع توقيتات لكل جزء
التحقق من صحة مخطط JSON للإخراج: تكتشف التأكيدات الانحراف عند تغيير المطالبات
محاكاة نقطة نهاية Flash: أنشئ استجابة وهمية لاختبار الكود الخاص بك دون استنزاف حصة واجهة برمجة التطبيقات
بناء سيناريوهات اختبار لحلقات الوكيل: اربط عدة استدعاءات Flash مع التحقق من استدعاء الأدوات بين الخطوات

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

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

نموذج الأخطاء في Flash بسيط ومباشر. الرموز المهمة:

400: طلب سيء (غالبًا ما يكون صفيف contents مشوهًا أو نوع MIME غير مدعوم)
401: مفتاح واجهة برمجة تطبيقات خاطئ
403: تم استنفاد الحصة أو النموذج غير مفعل
429: تم تحديد المعدل (تراجع وحاول مرة أخرى)
500/503: من جانب الخادم، حاول مرة أخرى مع تراجع أسي

قم بتغليف استدعاءات Flash الخاصة بك بحلقة إعادة محاولة:

import time
from google import genai

def call_with_retry(client, model, prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.models.generate_content(model=model, contents=prompt)
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

يتم إعادة تعيين حصص الطبقة المجانية يوميًا (15 طلبًا في الدقيقة، حوالي 1,500 طلب يوميًا على Flash). يتم إعادة تعيين حصص الطبقة الإنتاجية لكل دقيقة وكل يوم. للمهام عالية الإنتاجية، تحقق من مسار وضع الدُفعات أو استخدم خيار الرجوع المتدرج إلى Gemini 3 Flash عندما تصل إلى الحدود.

الترحيل من Gemini 3.1 إلى 3.5 Flash

تحتاج معظم المشاريع إلى تغيير سلسلة واحدة بالضبط: اسم النموذج.

# قبل
model="gemini-3.1-pro"  # أو gemini-3.1-flash

# بعد
model="gemini-3.5-flash"

ما يجب عليك التحقق منه بعد التبديل:

مخططات الأدوات لا تزال متطابقة، وهي كذلك لمعظم المكالمات، ولكن أعد تشغيل تقييمك
سرعة الإخراج، قد تحتاج واجهة المستخدم المتدفقة لديك إلى تقييد لأن Flash يتدفق أسرع بحوالي 4 مرات
ميزانيات التوكنات، نفس حدود 1M / 64K، لكن النموذج أكثر كثافة، لذا قد يستخدم طلب معين عددًا أقل من توكنات الإخراج
أنماط الرفض، حواجز الأمان أكثر صرامة؛ توقع رفضات مختلفة في الحالات الشاذة

للحصول على تفاصيل ترحيل أعمق، يغطي دليل واجهة برمجة تطبيقات Gemini 3.1 Pro نمط SDK؛ كل شيء يسير إلى الأمام.

أنماط Flash الشائعة

تحليل المستندات ذات السياق الطويل

with open("large_report.pdf", "rb") as f:
    pdf_bytes = f.read()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        types.Part.from_bytes(data=pdf_bytes, mime_type="application/pdf"),
        "Summarize the financial outlook from this report in 5 bullet points."
    ]
)

يتعامل سياق 1M توكن في Flash مع ملفات PDF الكاملة دون تقسيم.

حلقة الوكيل مع استدعاءات الأدوات

conversation = [{"role": "user", "parts": [{"text": "Book me a flight to Tokyo"}]}]

while True:
    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents=conversation,
        config=types.GenerateContentConfig(tools=[flight_search_tool, booking_tool])
    )

    part = response.candidates[0].content.parts[0]
    if not part.function_call:
        print(part.text)
        break

    result = execute_tool(part.function_call)
    conversation.append({"role": "model", "parts": [part]})
    conversation.append({"role": "user", "parts": [{"function_response": result}]})

هذا هو نمط الحلقة الذي يقيسه Flash في اختبار Terminal-Bench 2.1 (76.2%). عمليات الوكيل الحقيقية تعمل.

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

هل توجد طبقة مجانية لواجهة برمجة تطبيقات Gemini 3.5 Flash؟ نعم، من خلال Google AI Studio مع حصص يومية (حوالي 1,500 طلب/يوم). لا تتطلب بطاقة ائتمان.

هل يدعم Flash نقاط نهاية متوافقة مع OpenAI؟ نعم. توفر Google حزمة توافق مع OpenAI على المسار /v1beta/openai/. يمكنك توجيه أي حزمة SDK لـ OpenAI إليها عن طريق تعيين base_url واستخدام مفتاح Gemini الخاص بك. يبقى اسم النموذج gemini-3.5-flash.

هل يمكنني استخدام Flash مع LangChain أو LlamaIndex؟ نعم، كلاهما لديهما تكاملات Gemini أصلية. مرر model="gemini-3.5-flash" في أغلفتهما الخاصة.

متى يتم شحن Gemini 3.5 Pro؟ يونيو 2026 وفقًا لإعلان إطلاق Google. حتى ذلك الحين، Flash هو البديل الوحيد من 3.5 المتاح.

ما هو الحد الأقصى لحجم الصورة لـ Flash؟ يُنصح بـ 3072×3072. يتم إعادة أخذ عينات للصور الأكبر. للعمل المكثف على التعرف الضوئي على الحروف (OCR)، راجع سير عمل Gemini 2.0 Flash OCR، تنطبق نفس الأنماط.

كيف أقوم باختبار نقاط نهاية التدفق في Apidog؟ افتح الطلب، عيّن :streamGenerateContent كلاحقة لنقطة النهاية، وسيقوم Apidog بعرض أجزاء SSE فور وصولها. مفيد لتصحيح الأخطاء في الاستجابات غير المكتملة.

أين يمكنني رؤية سجلات واجهة برمجة التطبيقات؟ في AI Studio تحت "النشاط"، أو في Vertex AI تحت "مستكشف السجلات" لعمليات النشر الإنتاجية.

ماذا تبني أولاً

قائمة قصيرة بمشاريع البداية التي تستحق الشحن في الأسبوع الأول مع Flash:

بوت أسئلة وأجوبة لملفات PDF: ضع ملف PDF في نافذة السياق 1M، اطرح الأسئلة، وأعد الإجابات المقتبسة
خط أنابيب من الرسم البياني إلى JSON: قم بتغذية لقطات شاشة لوحة المعلومات، واستخراج البيانات المنظمة
وكيل دعم العملاء: استدعاء الوظائف مقابل نظام إدارة علاقات العملاء الخاص بك، يعمل دون مراقبة
مساعد مراجعة الكود: سياق فرق متعدد الملفات، إخراج منظم مع تقييمات للشدة
وكيل البحث الداخلي: اجمع سياق 1M مع استدعاءات الأدوات لواجهات برمجة التطبيقات الداخلية

لكل منها، ينطبق نفس تدفق الاختبار: بناء المطالبة، تغليفها في استدعاء SDK الخاص بك، التحقق من شكل الاستجابة باستخدام Apidog، ثم الشحن.

button