كيفية استخدام Google Nano Banana 2 API

إن بناء تطبيقات باستخدام تقنية توليد الصور بالذكاء الاصطناعي يبدو وكأنه سحر—إلى أن تصطدم بجدار من وثائق واجهة برمجة التطبيقات المعقدة، ومشاكل المصادقة، وكوابيس تصحيح الأخطاء. لقد رأيت ما يمكن أن يفعله Nano Banana 2: صور مذهلة يتم إنشاؤها من موجهات نصية، ومخرجات بجودة احترافية بسرعات فائقة، وميزات مثل اتساق الموضوع التي تجعل سير عمل الصور المتعددة ممكنًا. ولكن دمجها فعليًا في قاعدة التعليمات البرمجية الخاصة بك؟ هذا هو المكان الذي يتعثر فيه معظم المطورين.

ربما تكون قد حاولت الخوض في وثائق Google، وتجميع تدفقات المصادقة، واختبار الطلبات يدويًا في سطر الأوامر (CLI). ربما تكون قد استهلكت بالفعل حصة واجهة برمجة التطبيقات (API) في تصحيح أخطاء الطلبات المشوهة، أو تساءلت لماذا تعود صورك ضبابية في كل مرة. الحقيقة هي أن دمج أي واجهة برمجة تطبيقات جديدة، خاصةً تلك القوية مثل Nano Banana 2، يتطلب أكثر من مجرد قراءة الوثائق. أنت بحاجة إلى سير عمل يتيح لك الاختبار بسرعة، والتكرار على الموجهات، وإدارة استدعاءات واجهة برمجة التطبيقات بكفاءة.

في هذا الدليل، سنستعرض كل ما تحتاج لمعرفته لدمج Nano Banana 2 في تطبيقاتك، بدءًا من إعداد مشروعك على Google Cloud وصولاً إلى كتابة تعليمات برمجية جاهزة للإنتاج في Python و JavaScript. ولكن ما يميز هذا الدليل هو أننا سنوضح لك كيفية اختبار وتصحيح كل خطوة باستخدام Apidog، لذلك لن تقتصر على نسخ التعليمات البرمجية فحسب، بل ستبني سير عمل يمكنك الحفاظ عليه وتوسيع نطاقه.

المتطلبات الأساسية

قبل البدء، تأكد من أن لديك:

• حساب Google Cloud (أو قم بالتسجيل في cloud.google.com)
• فهم أساسي لواجهات برمجة التطبيقات (REST APIs)
• Python 3.8+ أو Node.js 18+ مثبتًا
• عميل واجهة برمجة تطبيقات مثل Apidog للاختبار

يفترض هذا الدليل أنك على دراية بإجراء طلبات HTTP والتعامل مع بيانات JSON. إذا كنت جديدًا في عالم واجهات برمجة التطبيقات، فراجع دليل اختبار واجهة برمجة التطبيقات الخاص بنا للمبادئ الأساسية.

إعداد مشروعك على Google Cloud

لاستخدام واجهة برمجة تطبيقات Nano Banana 2، تحتاج إلى مشروع Google Cloud مع تمكين Generative Language API.

الخطوة 1: إنشاء مشروع جديد

1. انتقل إلى وحدة تحكم Google Cloud
2. انقر على "تحديد مشروع" ← "مشروع جديد"
3. أدخل اسم المشروع (على سبيل المثال، "nano-banana-image-gen")
4. انقر على "إنشاء"
5. انتظر حتى يتم إنشاء المشروع

الخطوة 2: تكوين الوصول إلى واجهة برمجة التطبيقات (API)

1. انتقل إلى "APIs & Services" ← "Credentials"
2. انقر على "Create Credentials" ← "API Key"
3. انسخ مفتاح واجهة برمجة التطبيقات (API key) الخاص بك (ستحتاجه لاحقًا)

نصيحة احترافية:

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

هناك طريقتان للحصول على وصول إلى واجهة برمجة التطبيقات:

الخيار 1: Google Cloud Console (موصى به للإنتاج)

اتبع الخطوات المذكورة أعلاه—مفتاح واجهة برمجة التطبيقات الذي أنشأته هو بيانات الاعتماد للوصول الخاص بك.

الخيار 2: Google AI Studio (موصى به للتطوير)

1. انتقل إلى Google AI Studio
2. سجّل الدخول باستخدام حسابك على Google
3. انقر على "Get API Key" في شريط التنقل
4. انقر على "Create API Key" (أو اختر مشروعًا موجودًا)
5. انسخ مفتاح واجهة برمجة التطبيقات الخاص بك

مفتاح AI Studio رائع للتطوير والاختبار. للإنتاج، استخدم مفتاح Google Cloud Console لإدارة وأمان أفضل.

أول طلب واجهة برمجة تطبيقات لك

دعنا نقم بطلب بسيط لتوليد الصور للتحقق من أن كل شيء يعمل.

باستخدام cURL

curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp-image-generation:predict?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cute banana character wearing sunglasses, fun cartoon style",
    "number_of_images": 1
  }'

فهم الاستجابة

{
  "predictions": [
    {
      "image": {
        "mimeType": "image/png",
        "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
      },
      "generatedImageId": "img_abc123xyz",
      "metadata": {
        "prompt": "A cute banana character wearing sunglasses, fun cartoon style",
        "seed": 12345,
        "finishReason": "SUCCESS"
      }
    }
  ],
  "metadata": {
    "modelVersion": "gemini-3.1-flash-image-preview",
    "processingTimeMs": 1250,
    "contentAuthenticity": {
      "synthID": "enabled",
      "c2pa": "enabled"
    }
  }
}

يحتوي حقل `data` على صورة PNG مشفرة بنظام base64. ستحتاج إلى فك تشفيرها لحفظ الصورة أو عرضها.

دمج Python

إليك كيفية دمج Nano Banana 2 في تطبيقات Python الخاصة بك:

تثبيت مكتبة العميل

pip install google-generativeai

توليد الصور الأساسي

import google.generativeai as genai
import base64
import os

# Configure the API with your key
# قم بتكوين واجهة برمجة التطبيقات باستخدام مفتاحك
genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))

# Create the model
# أنشئ النموذج
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

# Generate an image
# ولّد صورة
response = model.generate_images(
    prompt="A modern minimalist office with natural lighting, indoor plants, standing desk, 4k quality",
    number_of_images=1
)

# Save the image
# احفظ الصورة
if response.generated_images:
    image_data = response.generated_images[0].image_bytes
    with open("output_image.png", "wb") as f:
        f.write(image_data)
    print("Image saved to output_image.png") # تم حفظ الصورة في output_image.png

توليد الصور المتقدم مع المعلمات

import google.generativeai as genai
from PIL import Image
import io

genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))

model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

# Generate with advanced parameters
# توليد باستخدام معلمات متقدمة
response = model.generate_images(
    prompt="A futuristic cityscape at night with neon lights, flying cars, cyberpunk aesthetic",
    number_of_images=1,
    aspect_ratio="16:9",
    negative_prompt="blurry, low quality, distorted, ugly", # موجه سلبي: ضبابي، جودة منخفضة، مشوه، قبيح
    safety_filter_level="block_medium_and_above"
)

# Process the response
# معالجة الاستجابة
for idx, generated_image in enumerate(response.generated_images):
    # Convert to PIL Image
    # تحويل إلى صورة PIL
    image = Image.open(io.BytesIO(generated_image.image_bytes))

    # Save with custom name
    # حفظ باسم مخصص
    image.save(f"generated_image_{idx}.png")

    # Access metadata
    # الوصول إلى البيانات الوصفية
    print(f"Image {idx}: {generated_image.finish_reason}") # الصورة {idx}: {finish_reason}
    print(f"Seed: {generated_image.seed}") # البذرة: {seed}

توليد الصور على دفعات

import google.generativeai as genai
import os

genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

# Generate multiple images at once
# توليد صور متعددة في وقت واحد
prompts = [
    "A red sports car on a mountain road", # سيارة رياضية حمراء على طريق جبلي
    "A cozy coffee shop interior", # ديكور مقهى مريح
    "A minimalist bedroom design", # تصميم غرفة نوم بسيط
    "A tropical beach sunset" # غروب الشمس على شاطئ استوائي
]

# Generate all images
# توليد جميع الصور
for idx, prompt in enumerate(prompts):
    response = model.generate_images(
        prompt=prompt,
        number_of_images=1,
        aspect_ratio="16:9"
    )

    if response.generated_images:
        image_data = response.generated_images[0].image_bytes
        with open(f"image_{idx + 1}.png", "wb") as f:
            f.write(image_data)
        print(f"Generated: image_{idx + 1}.png") # تم التوليد: image_{idx + 1}.png

مثال على اتساق الشخصية

import google.generativeai as genai

genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

# Base character description
# وصف الشخصية الأساسية
base_character = "A friendly cartoon robot with round body, blue eyes, antenna on head, white and light blue color scheme"

# Generate base character (note the seed for consistency)
# توليد الشخصية الأساسية (لاحظ البذرة للاتساق)
response1 = model.generate_images(
    prompt=base_character + ", front view, standing pose",
    number_of_images=1,
    seed=42  # Important: note this seed # مهم: لاحظ هذه البذرة
)

base_seed = response1.generated_images[0].seed
print(f"Base character seed: {base_seed}") # بذرة الشخصية الأساسية: {base_seed}

# Generate variations using the same seed
# توليد اختلافات باستخدام نفس البذرة
poses = [
    "sitting pose", # وضعية الجلوس
    "waving hand", # تلويح باليد
    "holding a ball", # يحمل كرة
    "walking" # يمشي
]

for pose in poses:
    response = model.generate_images(
        prompt=f"{base_character}, {pose}, same character as seed {base_seed}",
        number_of_images=1,
        seed=base_seed  # Same seed maintains consistency # نفس البذرة تحافظ على الاتساق
    )

    if response.generated_images:
        filename = f"robot_{pose.replace(' ', '_')}.png"
        with open(filename, "wb") as f:
            f.write(response.generated_images[0].image_bytes)
        print(f"Generated: {filename}") # تم التوليد: {filename}

دمج JavaScript/Node.js

تثبيت مكتبة العميل

npm install @google/generative-ai

توليد الصور الأساسي

const { GoogleGenerativeAI } = require("@google/generative-ai");
const fs = require("fs");
const path = require("path");

// Initialize with API key
// التهيئة بمفتاح واجهة برمجة التطبيقات
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

async function generateImage() {
  // Get the model
  // احصل على النموذج
  const model = genAI.getGenerativeModel({
    model: "gemini-3.1-flash-image-preview",
  });

  // Generate image
  // توليد الصورة
  const result = await model.generateImages({
    prompt: "A beautiful sunset over the ocean with palm trees silhouette", // غروب شمس جميل فوق المحيط مع صورة ظلية لأشجار النخيل
    numberOfImages: 1,
  });

  // Process the response
  // معالجة الاستجابة
  if (result.generatedImages && result.generatedImages.length > 0) {
    const imageData = result.generatedImages[0].imageBytes;

    // Save to file
    // حفظ إلى ملف
    fs.writeFileSync("sunset.png", Buffer.from(imageData, "base64"));
    console.log("Image saved to sunset.png"); // تم حفظ الصورة في sunset.png

    // Log metadata
    // تسجيل البيانات الوصفية
    console.log("Seed:", result.generatedImages[0].seed); // البذرة:
    console.log("Finish Reason:", result.generatedImages[0].finishReason); // سبب الانتهاء:
  }
}

generateImage().catch(console.error);

التعامل مع استجابات Base64

const { GoogleGenerativeAI } = require("@google/generative-ai");
const fs = require("fs");

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

async function generateAndProcessImage() {
  const model = genAI.getGenerativeModel({
    model: "gemini-3.1-flash-image-preview",
  });

  const result = await model.generateImages({
    prompt: "Professional headshot of a person in business attire, studio lighting", // لقطة رأس احترافية لشخص يرتدي زي عمل، إضاءة استوديو
    numberOfImages: 1,
    aspectRatio: "1:1",
    resolution: "1024x1024"
  });

  const generatedImage = result.generatedImages[0];

  // Decode base64
  // فك تشفير base64
  const imageBuffer = Buffer.from(generatedImage.imageBytes, "base64");

  // Save with metadata in filename
  // حفظ مع البيانات الوصفية في اسم الملف
  const filename = `portrait_${generatedImage.seed}.png`;
  fs.writeFileSync(filename, imageBuffer);

  return {
    filename,
    seed: generatedImage.seed,
    finishReason: generatedImage.finishReason
  };
}

generateAndProcessImage()
  .then(info => console.log("Generated:", info)) // تم التوليد:
  .catch(err => console.error("Error:", err)); // خطأ:

مثال على Express.js REST API

const express = require("express");
const { GoogleGenerativeAI } = require("@google/generative-ai");
const multer = require("multer");
const fs = require("fs");

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

app.use(express.json());

// Image generation endpoint
// نقطة نهاية توليد الصور
app.post("/api/generate", async (req, res) => {
  try {
    const { prompt, aspect_ratio, negative_prompt, number_of_images } = req.body;

    const model = genAI.getGenerativeModel({
      model: "gemini-2.0-flash-exp-image-generation",
    });

    const result = await model.generateImages({
      prompt,
      numberOfImages: number_of_images || 1,
      aspectRatio: aspect_ratio || "1:1",
      negativePrompt: negative_prompt
    });

    // Convert images to base64 for response
    // تحويل الصور إلى base64 للاستجابة
    const images = result.generatedImages.map((img, idx) => ({
      id: idx,
      seed: img.seed,
      finishReason: img.finishReason,
      data: img.imageBytes // Base64 encoded
    }));

    res.json({
      success: true, // نجاح: صحيح
      images,
      metadata: {
        modelVersion: result.response?.metadata?.modelVersion,
        processingTimeMs: result.response?.metadata?.processingTimeMs
      }
    });
  } catch (error) {
    console.error("Generation error:", error); // خطأ في التوليد:
    res.status(500).json({
      success: false, // نجاح: خطأ
      error: error.message
    });
  }
});

// Batch generation endpoint
// نقطة نهاية التوليد الدفعي
app.post("/api/generate/batch", async (req, res) => {
  try {
    const { prompts } = req.body;
    const model = genAI.getGenerativeModel({
      model: "gemini-3.1-flash-image-preview",
    });

    const results = [];

    for (const prompt of prompts) {
      const result = await model.generateImages({
        prompt,
        numberOfImages: 1
      });

      results.push({
        prompt,
        seed: result.generatedImages[0]?.seed,
        success: !!result.generatedImages[0] // نجاح:
      });
    }

    res.json({ success: true, results }); // نجاح: صحيح
  } catch (error) {
    res.status(500).json({ success: false, error: error.message }); // نجاح: خطأ
  }
});

app.listen(3000, () => {
  console.log("Server running on port 3000"); // الخادم يعمل على المنفذ 3000
});

المعلمات المتقدمة

يدعم Nano Banana 2 معلمات مختلفة لضبط توليد الصور بدقة:

مرجع المعلمات

خيارات الدقة

# Available resolutions
# الدقات المتاحة
resolutions = [
    "512x512",    # Thumbnail, social media # صورة مصغرة، وسائل تواصل اجتماعي
    "768x768",    # Small web images # صور ويب صغيرة
    "1024x1024",  # Standard square # مربع قياسي
    "1024x768",   # 4:3 landscape # 4:3 أفقي
    "1280x720",   # HD ready # جاهز عالي الدقة
    "1920x1080",  # Full HD # عالي الدقة الكامل
    "2048x2048",  # High quality # جودة عالية
    "3840x2160"   # 4K # 4K
]

# Using specific resolution
# استخدام دقة محددة
response = model.generate_images(
    prompt="Professional product photography of a watch", # تصوير منتجات احترافي لساعة
    resolution="2048x2048"
)

نسب الأبعاد

aspect_ratios = [
    "1:1",    # Square (Instagram posts) # مربع (منشورات انستغرام)
    "4:3",    # Standard photo # صورة قياسية
    "16:9",   # Landscape (YouTube, web) # أفقي (يوتيوب، ويب)
    "9:16",   # Portrait (Stories, TikTok) # عمودي (قصص، تيك توك)
    "21:9",   # Ultrawide # عريض جداً
    "3:4",    # Portrait standard # عمودي قياسي
    "2:3"     # Portrait photo # صورة عمودية
]

# Using specific aspect ratio
# استخدام نسبة أبعاد محددة
response = model.generate_images(
    prompt="Modern office interior design", # تصميم داخلي لمكتب حديث
    aspect_ratio="16:9"
)

التعامل مع الاستجابات

تحليل بنية الاستجابة

import google.generativeai as genai

genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

response = model.generate_images(
    prompt="A fantasy castle on a mountain", # قلعة خيالية على جبل
    number_of_images=2
)

# Access predictions (generated images)
# الوصول إلى التنبؤات (الصور المولدة)
for idx, image in enumerate(response.generated_images):
    print(f"Image {idx + 1}:") # الصورة {idx + 1}:
    print(f"  - Seed: {image.seed}") #   - البذرة: {image.seed}
    print(f"  - Finish Reason: {image.finish_reason}") #   - سبب الانتهاء: {image.finish_reason}
    print(f"  - Image Bytes Length: {len(image.image_bytes)}") #   - طول بايتات الصورة: {len(image.image_bytes)}

# Access metadata
# الوصول إلى البيانات الوصفية
print("\nMetadata:") # البيانات الوصفية:
print(f"  - Model Version: {response.response.metadata.model_version}") #   - إصدار النموذج: {response.response.metadata.model_version}
print(f"  - Processing Time: {response.response.metadata.processing_time_ms}ms") #   - وقت المعالجة: {response.response.metadata.processing_time_ms} مللي ثانية
print(f"  - SynthID: {response.response.metadata.content_authenticity.synth_id}") #   - SynthID: {response.response.metadata.content_authenticity.synth_id}

التحويل إلى صيغ مختلفة

from PIL import Image
import io
import base64

def image_to_different_formats(image_bytes):
    """Convert generated image to multiple formats."""
    # تحويل الصورة المولدة إلى صيغ متعددة.
    # Load as PIL Image
    # تحميل كصورة PIL
    img = Image.open(io.BytesIO(image_bytes))

    # Save as PNG
    # حفظ كـ PNG
    img.save("image.png", "PNG")

    # Save as JPEG (with quality)
    # حفظ كـ JPEG (مع الجودة)
    img.save("image.jpg", "JPEG", quality=95)

    # Convert to WebP (smaller file size)
    # تحويل إلى WebP (حجم ملف أصغر)
    img.save("image.webp", "WEBP", quality=85)

    # Get base64 for embedding
    # الحصول على base64 للتضمين
    buffered = io.BytesIO()
    img.save(buffered, format="PNG")
    base64_str = base64.b64encode(buffered.getvalue()).decode()

    return base64_str

معالجة الأخطاء

تعد معالجة الأخطاء بشكل صحيح أمرًا ضروريًا لتطبيقات الإنتاج:

معالجة الأخطاء في Python

import google.generativeai as genai
from google.api_core.exceptions import (
    ResourceExhausted, # استنزاف الموارد
    InvalidArgument, # وسيطة غير صالحة
    ServiceUnavailable # الخدمة غير متاحة
)

genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))
model = genai.GenerativeModel("gemini-3.1-flash-image-preview")

def generate_image_with_retry(prompt, max_retries=3):
    """Generate image with retry logic."""
    # توليد صورة مع منطق إعادة المحاولة.

    for attempt in range(max_retries):
        try:
            response = model.generate_images(
                prompt=prompt,
                number_of_images=1
            )
            return response

        except ResourceExhausted as e:
            # Rate limit or quota exceeded
            # تجاوز حد المعدل أو الحصة
            print(f"Rate limited (attempt {attempt + 1}/{max_retries})") # تم تجاوز حد المعدل (المحاولة {attempt + 1}/{max_retries})
            if attempt < max_retries - 1:
                import time
                time.sleep(2 ** attempt)  # Exponential backoff # تراجع أسي
            else:
                raise Exception("Rate limit exceeded. Please try again later.") # تم تجاوز حد المعدل. يرجى المحاولة مرة أخرى لاحقًا.

        except InvalidArgument as e:
            # Invalid prompt or parameters
            # موجه أو معلمات غير صالحة
            raise ValueError(f"Invalid request: {e}") # طلب غير صالح: {e}

        except ServiceUnavailable as e:
            # Service temporarily unavailable
            # الخدمة غير متاحة مؤقتًا
            print(f"Service unavailable (attempt {attempt + 1}/{max_retries})") # الخدمة غير متاحة (المحاولة {attempt + 1}/{max_retries})
            if attempt < max_retries - 1:
                import time
                time.sleep(5)  # Wait 5 seconds # انتظر 5 ثواني
            else:
                raise Exception("Service unavailable. Please try again later.") # الخدمة غير متاحة. يرجى المحاولة مرة أخرى لاحقًا.

    return None

# Usage
# الاستخدام
try:
    result = generate_image_with_retry("A beautiful landscape") # منظر طبيعي جميل
    if result:
        print("Image generated successfully") # تم توليد الصورة بنجاح
except Exception as e:
    print(f"Error: {e}") # خطأ: {e}

معالجة الأخطاء في JavaScript

const { GoogleGenerativeAI } = require("@google/generative-ai");

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

async function generateImageWithRetry(prompt, maxRetries = 3) {
  const model = genAI.getGenerativeModel({
    model: "gemini-3.1-flash-image-preview",
  });

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const result = await model.generateImages({
        prompt,
        numberOfImages: 1
      });
      return result;
    } catch (error) {
      console.error(`Attempt ${attempt + 1} failed:`, error.message); // فشلت المحاولة {attempt + 1}:

      if (error.message.includes("RESOURCE_EXHAUSTED")) {
        // Rate limited
        // تم تجاوز حد المعدل
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Rate limited. Retrying in ${delay}ms...`); // تم تجاوز حد المعدل. إعادة المحاولة في {delay} مللي ثانية...
        await new Promise(resolve => setTimeout(resolve, delay));
      } else if (error.message.includes("INVALID_ARGUMENT")) {
        // Invalid prompt
        // موجه غير صالح
        throw new Error(`Invalid prompt: ${error.message}`); // موجه غير صالح:
      } else if (attempt === maxRetries - 1) {
        throw error;
      }
    }
  }

  return null;
}

// Usage
// الاستخدام
generateImageWithRetry("A serene mountain lake at sunrise") // بحيرة جبلية هادئة عند شروق الشمس
  .then(result => {
    if (result) {
      console.log("Image generated successfully"); // تم توليد الصورة بنجاح
    }
  })
  .catch(err => {
    console.error("Failed to generate image:", err.message); // فشل توليد الصورة:
  });

رموز الأخطاء الشائعة

الاختبار باستخدام Apidog

Apidog هو أداة ممتازة لاختبار وتصحيح أخطاء دمج واجهة برمجة تطبيقات Nano Banana 2 الخاصة بك:

إعداد مساحة عمل Apidog الخاصة بك

1. افتح Apidog وأنشئ مشروعًا جديدًا
2. أضف متغيرات البيئة:

GEMINI_API_KEY: مفتاح_واجهة_برمجة_التطبيقات_الخاص_بك_هنا
BASE_URL: https://generativelanguage.googleapis.com/v1beta

إنشاء طلبات واجهة برمجة التطبيقات

نقطة النهاية (Endpoint): POST /models/gemini-3.1-flash-image-preview:predict

الرؤوس (Headers):

Authorization: Bearer {{GEMINI_API_KEY}}
Content-Type: application/json

جسم الطلب (Request Body):

{
  "prompt": "{{prompt}}",
  "number_of_images": 1,
  "aspect_ratio": "1:1"
}

معلمات الاستعلام (Query Parameters):

key: {{GEMINI_API_KEY}}

كتابة نصوص الاختبار

// Test: Successful generation
// اختبار: توليد ناجح
pm.test("Image generation successful", function() { // تم توليد الصورة بنجاح
    var jsonData = pm.response.json();
    pm.expect(jsonData.predictions).to.have.property('image'); // يجب أن تحتوي التوقعات على خاصية 'image'
    pm.expect(jsonData.predictions[0].metadata.finishReason).to.eql('SUCCESS'); // يجب أن يكون سبب الانتهاء 'SUCCESS'
});

// Test: Response contains metadata
// اختبار: الاستجابة تحتوي على بيانات وصفية
pm.test("Response has required metadata", function() { // الاستجابة تحتوي على البيانات الوصفية المطلوبة
    var jsonData = pm.response.json();
    pm.expect(jsonData.metadata).to.have.property('modelVersion'); // يجب أن تحتوي البيانات الوصفية على خاصية 'modelVersion'
    pm.expect(jsonData.metadata).to.have.property('processingTimeMs'); // يجب أن تحتوي البيانات الوصفية على خاصية 'processingTimeMs'
});

// Test: Content authenticity verified
// اختبار: تم التحقق من أصالة المحتوى
pm.test("Content authenticity enabled", function() { // أصالة المحتوى ممكّنة
    var jsonData = pm.response.json();
    pm.expect(jsonData.metadata.contentAuthenticity.synthID).to.eql('enabled'); // يجب أن يكون synthID ممكّنًا
});

// Test: Response time acceptable
// اختبار: وقت الاستجابة مقبول
pm.test("Response time under 5 seconds", function() { // وقت الاستجابة أقل من 5 ثوانٍ
    pm.expect(pm.response.responseTime).to.be.below(5000); // يجب أن يكون وقت الاستجابة أقل من 5000
});

إنشاء مجموعة للاختبار الدفعي

احفظ هذه الطلبات في Apidog لبناء مجموعة اختبار:

1. توليد أساسي (Basic Generation) - توليد صورة واحدة
2. توليد دفعي (Batch Generation) - موجهات متعددة
3. اتساق الشخصية (Character Consistency) - اختبار البذرة المتطابقة
4. معالجة الأخطاء (Error Handling) - اختبار الموجه غير الصالح
5. اختبار الأداء (Performance Test) - طلبات متزامنة متعددة

أفضل الممارسات للإنتاج

عند نشر Nano Banana 2 في بيئة الإنتاج:

1. تأمين مفتاح واجهة برمجة التطبيقات الخاص بك

# Never hardcode API keys
# لا تكتب مفاتيح API مباشرة أبدًا
# Use environment variables
# استخدم متغيرات البيئة
import os

API_KEY = os.environ.get("GEMINI_API_KEY")

# Or use a secrets manager
# أو استخدم مدير الأسرار
# AWS Secrets Manager, HashiCorp Vault, etc.

2. تنفيذ التخزين المؤقت (Caching)

import hashlib
import redis

redis_client = redis.Redis(host='localhost', port=6379, db=0)

def generate_image_cached(prompt, seed=None):
    """Generate image with caching."""
    # توليد صورة مع التخزين المؤقت.
    # Create cache key from prompt + seed
    # إنشاء مفتاح التخزين المؤقت من الموجه + البذرة
    cache_key = f"image:{hashlib.md5(f'{prompt}:{seed}'.encode()).hexdigest()}"

    # Check cache
    # تحقق من التخزين المؤقت
    cached = redis_client.get(cache_key)
    if cached:
        return cached

    # Generate new image
    # توليد صورة جديدة
    response = model.generate_images(prompt=prompt, seed=seed)
    image_data = response.generated_images[0].image_bytes

    # Cache for 24 hours
    # تخزين مؤقت لمدة 24 ساعة
    redis_client.setex(cache_key, 86400, image_data)

    return image_data

3. تحديد المعدل (Rate Limiting)

from flask import Flask, request, jsonify
from flask_limiter import Limiter

app = Flask(__name__)
limiter = Limiter(app, key_func=lambda: request.headers.get("X-API-Key"))

@app.route("/generate", methods=["POST"])
@limiter.limit("10 per minute")  # Adjust based on your quota # اضبط بناءً على حصتك
def generate():
    # Your generation logic
    # منطق التوليد الخاص بك
    pass

4. المراقبة والتسجيل

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def generate_with_logging(prompt):
    logger.info(f"Generating image for prompt: {prompt[:50]}...") # يتم توليد صورة للموجه: {prompt[:50]}...

    start_time = time.time()
    try:
        response = model.generate_images(prompt=prompt)
        elapsed = time.time() - start_time

        logger.info(f"Generated successfully in {elapsed:.2f}s") # تم التوليد بنجاح في {elapsed:.2f} ثانية
        return response

    except Exception as e:
        elapsed = time.time() - start_time
        logger.error(f"Failed after {elapsed:.2f}s: {e}") # فشل بعد {elapsed:.2f} ثانية: {e}
        raise

5. Webhook للمعالجة غير المتزامنة

للمهام الدفعية الكبيرة، استخدم Webhooks:

# Request with webhook
# طلب باستخدام webhook
response = model.generate_images(
    prompt="Generate 10 product images", # توليد 10 صور منتج
    number_of_images=10,
    webhook_url="https://your-server.com/webhook/nano-banana"
)

# Your webhook handler
# معالج webhook الخاص بك
@app.route("/webhook/nano-banana", methods=["POST"])
def handle_webhook():
    data = request.json

    if data["status"] == "completed": # إذا كانت الحالة "مكتملة"
        images = data["images"]
        # Process completed images
        # معالجة الصور المكتملة
    elif data["status"] == "failed": # إذا كانت الحالة "فشلت"
        # Handle failure
        # معالجة الفشل
        pass

    return jsonify({"received": True}) # تم الاستلام: صحيح

الخاتمة

توفر واجهة برمجة تطبيقات Nano Banana 2 طريقة قوية لدمج توليد الصور بالذكاء الاصطناعي في تطبيقاتك. بفضل دعمها للغات برمجة متعددة، والمعلمات المرنة، ومعالجة الأخطاء القوية، يمكنك بناء كل شيء بدءًا من مولدات الصور البسيطة وصولاً إلى سير عمل الإنتاج المعقدة.

النقاط الرئيسية:

• البدء يتطلب مشروع Google Cloud ومفتاح API
• مجموعات تطوير البرامج (SDKs) لـ Python و JavaScript تجعل التكامل مباشرًا
• المعلمات المتقدمة مثل البذور والموجهات السلبية تمنحك تحكمًا دقيقًا
• Apidog يساعد في اختبار وتصحيح دمج واجهة برمجة التطبيقات الخاصة بك
• تتطلب عمليات النشر في بيئة الإنتاج الأمان، والتخزين المؤقت، وتحديد المعدل، والمراقبة

ابدأ بالأمثلة الأساسية في هذا الدليل، ثم أضف الميزات المتقدمة تدريجيًا كلما أصبحت أكثر ارتياحًا للعمل مع واجهة برمجة التطبيقات.

الخطوة التالية: