دليل استدعاء Nano Banana Pro API الكامل: أرخص من KIE.ai بنسبة 44%، تكامل سريع بتنسيق جوجل الأصلي

ملاحظة المؤلف: شرح مفصل لطريقة استدعاء واجهة برمجة تطبيقات (API) لـ Nano Banana Pro، باستخدام تنسيق Gemini الأصلي من جوجل. من خلال منصة APIYI، تبلغ التكلفة 0.05 دولار فقط لكل عملية، وهو ما يوفر 44% مقارنة بـ KIE.ai، مع دعم توليد صور بدقة 1K و2K و4K.

عند استدعاء واجهة برمجة تطبيقات Nano Banana Pro، يختار العديد من المطورين KIE.ai كخيار أول، ولكن في الحقيقة هناك بدائل أكثر توفيراً واستقراراً. سيوضح لك هذا المقال كيفية استدعاء Nano Banana Pro باستخدام تنسيق Google Gemini API الأصلي، وكيفية تقليل تكلفة الاستدعاء الواحد إلى 0.05 دولار عبر منصة APIYI — أي أقل بنسبة 44% من KIE.ai.

القيمة الجوهرية: بعد قراءة هذا المقال، ستتقن الطريقة القياسية لاستدعاء Nano Banana Pro API، وستتعرف على فروق الأسعار بين المنصات، وستتمكن من توليد صور احترافية بدقة 4K بأقل التكاليف.

نظرة عامة على المعلمات الأساسية لـ Nano Banana Pro API

لماذا يستخدم Nano Banana Pro تنسيق جوجل الأصلي؟

إن Nano Banana Pro (اسم النموذج gemini-3-pro-image-preview) هو نموذج احترافي لتوليد الصور أطلقته Google DeepMind. يعتمد تصميم واجهة برمجة التطبيقات (API) الخاصة به على بروتوكول Gemini الأصلي، وهو يختلف جوهرياً عن تنسيق OpenAI:

• معلمات وضع الاستجابة: يجب التصريح عن responseModalities: ["IMAGE"] داخل generationConfig بدلاً من response_format المستخدم في OpenAI.
• التحكم في الدقة: يتم تحديد الدقة (1K/2K/4K) عبر حقل resolution بدلاً من أبعاد البكسل.
• نسبة العرض إلى الارتفاع: يتم استخدام سلسلة نصية لـ aspectRatio (مثل "16:9") بدلاً من قيم الطول والعرض العددية.

إذا حاولت الاستدعاء باستخدام تنسيق OpenAI SDK، فستواجه أخطاء في تحليل المعلمات. الطريقة الصحيحة هي استخدام Google Generative AI SDK أو إرسال طلبات HTTP مباشرة إلى النقاط الطرفية (Endpoints) المتوافقة.

ماذا يمكن لـ Nano Banana Pro أن ينتج؟

يتفوق هذا النموذج بشكل ملحوظ في السيناريوهات التالية، متجاوزاً المنافسين في فئته:

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

مقارنة أسعار واجهة برمجة تطبيقات Nano Banana Pro عبر المنصات المختلفة

قبل اختيار منصة الاستدعاء، من المهم فهم الفروق الحقيقية في التكلفة بين المنصات المختلفة:

💰 مقارنة التكلفة: بافتراض توليد 100 صورة بدقة 4K يومياً، ستكون التكلفة الشهرية عبر جوجل الرسمي حوالي 720 دولاراً، وعبر KIE.ai حوالي 360 دولاراً، بينما عبر APIYI (apiyi.com) ستحتاج فقط إلى 150 دولاراً، مما يوفر أكثر من 570 دولاراً شهرياً.

المزايا الجوهرية لـ APIYI مقارنة بـ KIE.ai:

1. سعر أقل: 0.05 دولار للمرة مقابل 0.09 دولار في KIE.ai، مما يوفر 44%.
2. توافق التنسيقات: يدعم تنسيق Gemini API الأصلي من جوجل مباشرة، دون الحاجة لتحويل التنسيقات.
3. سرعة أكبر: خطوط تسريع محسنة، مع استجابة أكثر استقراراً في الاختبارات الفعلية.
4. واجهة موحدة: يدعم في الوقت نفسه النماذج الرائدة مثل GPT وClaude وGemini، مما يسهل التبديل بين النماذج المتعددة.

البدء السريع مع واجهة برمجة تطبيقات Nano Banana Pro

الطريقة الأولى: استخدام Google Generative AI SDK (موصى به)

تثبيت SDK:

pip install google-generativeai

مثال بسيط للاستدعاء (تحويل النص إلى صورة، 10 أسطر من الكود):

import google.generativeai as genai
import base64

genai.configure(
    api_key="YOUR_API_KEY",
    # استخدام نقطة نهاية APIYI، السعر 0.05 دولار فقط للمرة
    client_options={"api_endpoint": "vip.apiyi.com"}
)

model = genai.GenerativeModel("gemini-3-pro-image-preview")
response = model.generate_content(
    "قطة برتقالية تجلس في حقل من دوار الشمس، ضوء شمس ساطع، أسلوب واقعي، دقة 4K عالية الوضوح",
    generation_config=genai.GenerationConfig(
        response_modalities=["IMAGE"],
        resolution="4K",
        aspect_ratio="16:9"
    )
)

# حفظ الصورة
for part in response.candidates[0].content.parts:
    if part.inline_data:
        with open("output.png", "wb") as f:
            f.write(base64.b64decode(part.inline_data.data))
        print("تم حفظ الصورة: output.png")

🚀 بداية سريعة: بعد التسجيل في APIYI (apiyi.com)، يمكنك الحصول على مفتاح API ورصيد اختبار مجاني. ما عليك سوى نسخ الكود أعلاه واستبدال YOUR_API_KEY للتشغيل مباشرة دون أي إعدادات إضافية.

import google.generativeai as genai
import base64
import os
from pathlib import Path
from typing import Optional, List


def setup_client(api_key: str):
    """تهيئة عميل واجهة برمجة تطبيقات Nano Banana Pro"""
    genai.configure(
        api_key=api_key,
        # الاستدعاء عبر APIYI، السعر 0.05 دولار للمرة، أقل بنسبة 79% من السعر الرسمي
        client_options={"api_endpoint": "vip.apiyi.com"}
    )
    return genai.GenerativeModel("gemini-3-pro-image-preview")


def text_to_image(
    model,
    prompt: str,
    resolution: str = "2K",       # 1K / 2K / 4K
    aspect_ratio: str = "1:1",    # 1:1 / 16:9 / 9:16 / 4:3 / 3:4
    output_path: str = "output.png"
) -> str:
    """
    تحويل النص إلى صورة: توليد صورة بناءً على وصف نصي

    Args:
        model: مثيل النموذج الذي تم تهيئته
        prompt: وصف الصورة (يدعم العربية والصينية والإنجليزية)
        resolution: دقة الإخراج 1K/2K/4K
        aspect_ratio: نسبة العرض إلى الارتفاع
        output_path: مسار الحفظ

    Returns:
        مسار الملف المحفوظ
    """
    response = model.generate_content(
        prompt,
        generation_config=genai.GenerationConfig(
            response_modalities=["IMAGE"],
            resolution=resolution,
            aspect_ratio=aspect_ratio
        )
    )

    for part in response.candidates[0].content.parts:
        if part.inline_data and part.inline_data.mime_type.startswith("image/"):
            with open(output_path, "wb") as f:
                f.write(base64.b64decode(part.inline_data.data))
            return output_path

    raise ValueError("لم ترجع واجهة برمجة التطبيقات بيانات صورة، يرجى التحقق مما إذا كان الموجه قد فعل تصفية المحتوى")


def image_to_image(
    model,
    prompt: str,
    reference_image_path: str,
    resolution: str = "2K",
    output_path: str = "edited_output.png"
) -> str:
    """
    تحويل صورة إلى صورة: تحرير أو تحويل النمط بناءً على صورة مرجعية

    Args:
        model: مثيل النموذج الذي تم تهيئته
        prompt: تعليمات التحرير (مثل "تغيير الخلفية إلى ليل")
        reference_image_path: مسار الصورة المرجعية
        resolution: دقة الإخراج
        output_path: مسار الحفظ

    Returns:
        مسار الملف المحفوظ
    """
    # قراءة الصورة المرجعية
    with open(reference_image_path, "rb") as f:
        image_data = base64.b64encode(f.read()).decode()

    # اكتشاف تنسيق الصورة
    ext = Path(reference_image_path).suffix.lower()
    mime_map = {".jpg": "image/jpeg", ".jpeg": "image/jpeg",
                ".png": "image/png", ".webp": "image/webp"}
    mime_type = mime_map.get(ext, "image/png")

    response = model.generate_content(
        [
            {"inline_data": {"mime_type": mime_type, "data": image_data}},
            prompt
        ],
        generation_config=genai.GenerationConfig(
            response_modalities=["IMAGE"],
            resolution=resolution
        )
    )

    for part in response.candidates[0].content.parts:
        if part.inline_data and part.inline_data.mime_type.startswith("image/"):
            with open(output_path, "wb") as f:
                f.write(base64.b64decode(part.inline_data.data))
            return output_path

    raise ValueError("فشلت معالجة صورة إلى صورة، يرجى التأكد من صحة تنسيق الصورة المرجعية")


def batch_generate(
    model,
    prompts: List[str],
    resolution: str = "2K",
    output_dir: str = "batch_output"
) -> List[str]:
    """
    توليد الصور دفعة واحدة

    Args:
        model: مثيل النموذج
        prompts: قائمة الموجهات
        resolution: الدقة
        output_dir: دليل المخرجات

    Returns:
        قائمة بمسارات الملفات المولدة
    """
    os.makedirs(output_dir, exist_ok=True)
    results = []

    for i, prompt in enumerate(prompts):
        output_path = f"{output_dir}/image_{i+1:03d}.png"
        try:
            path = text_to_image(model, prompt, resolution, output_path=output_path)
            results.append(path)
            print(f"[{i+1}/{len(prompts)}] تم التوليد بنجاح: {path}")
        except Exception as e:
            print(f"[{i+1}/{len(prompts)}] فشل التوليد: {e}")
            results.append(None)

    return results


# مثال على الاستخدام
if __name__ == "__main__":
    # تهيئة العميل - الاستدعاء عبر APIYI (apiyi.com)، 0.05 دولار للمرة
    model = setup_client("YOUR_APIYI_API_KEY")

    # مثال تحويل النص إلى صورة
    path = text_to_image(
        model,
        prompt="صورة عرض منتج بأسلوب عصري بسيط، خلفية بيضاء، إضاءة استوديو احترافية، مناسبة للتجارة الإلكترونية",
        resolution="4K",
        aspect_ratio="1:1",
        output_path="product_4k.png"
    )
    print(f"تم توليد صورة المنتج بدقة 4K: {path}")

    # مثال تحويل صورة إلى صورة (تعديل صورة موجودة)
    edited = image_to_image(
        model,
        prompt="تغيير الخلفية في الصورة إلى مشهد طبيعي خارجي، مع الحفاظ على العنصر الرئيسي كما هو",
        reference_image_path="product_4k.png",
        resolution="4K",
        output_path="product_outdoor.png"
    )
    print(f"الصورة بعد التحرير: {edited}")

الطريقة الثانية: استخدام طلبات HTTP المباشرة (مناسبة لأي لغة برمجة)

إذا كنت لا ترغب في تثبيت SDK، يمكنك إرسال طلب HTTP POST مباشرة:

import requests
import base64
import json

API_KEY = "YOUR_APIYI_API_KEY"
# نقطة نهاية APIYI المتوافقة مع تنسيق جوجل الأصلي
BASE_URL = "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
    "contents": [
        {
            "role": "user",
            "parts": [
                {
                    "text": "غرفة مركز بيانات مليئة بالتكنولوجيا، تأثير أضواء نيون زرقاء، دقة 4K فائقة الوضوح، جودة سينمائية"
                }
            ]
        }
    ],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "resolution": "4K",
        "aspectRatio": "16:9"
    }
}

response = requests.post(BASE_URL, headers=headers, json=payload)
data = response.json()

# استخراج وحفظ الصورة
image_data = data["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
with open("datacenter_4k.png", "wb") as f:
    f.write(base64.b64decode(image_data))
print("اكتمل توليد الصورة!")

ملاحظة: الكود أعلاه يستخدم نقطة النهاية المتوافقة من APIYI (apiyi.com)، وهي متوافقة تماماً مع تنسيق Gemini API الأصلي من جوجل، دون الحاجة لأي تحويل في التنسيقات، وبسعر 0.05 دولار للمرة.

Nano Banana Pro 核心参数详解

分辨率与宽高比完整参数表

支持的宽高比（aspectRatio 参数值）：

横向: "16:9"  "4:3"  "3:2"  "21:9"
方形: "1:1"
竖向: "9:16"  "3:4"  "2:3"  "9:21"
自定义: "4:5"（Instagram 推荐）

提示词最佳实践

Nano Banana Pro 对提示词质量非常敏感，以下是经过验证的写法规律：

高质量提示词结构：主体描述 + 风格定义 + 光效/质感 + 分辨率/品质词

✅ 推荐写法：
"一位穿着传统汉服的年轻女性站在古典园林中，
 工笔画风格，柔和自然光，细节丰富，4K超清，
 高度写实"

❌ 避免写法：
"画一个女生"（过于模糊）

文字渲染专项提示词（Nano Banana Pro 的核心优势）：

"一张活动海报，标题文字'2026 AI 峰会'，
 中英双语，现代设计风格，深蓝色背景，
 白色标题字体，字迹清晰可读"

Nano Banana Pro API 实际使用场景

场景一：电商产品图批量生成

# 批量生成电商产品展示图
product_prompts = [
    "无线蓝牙耳机，纯白背景，专业产品摄影，正面视角，4K",
    "无线蓝牙耳机，深灰背景，侧面45度，展示耳机细节，4K",
    "无线蓝牙耳机，生活场景，佩戴效果图，户外阳光，4K"
]

results = batch_generate(
    model,
    product_prompts,
    resolution="4K",
    output_dir="product_images"
)
# 3张图，APIYI 总成本：$0.15（KIE.ai 需 $0.27）

场景二：营销海报文字设计

Nano Banana Pro 最突出的能力之一是在图像中精准渲染文字，这是同类模型很难做到的：

poster_prompt = """
设计一张双十一促销海报：
- 标题：双十一大促销
- 副标题：全场5折起
- 背景：红色渐变，节日喜庆风格
- 文字颜色：金黄色，大号醒目字体
- 底部：活动时间 2026.11.11-11.13
要求：中文文字清晰可读，排版专业
"""

path = text_to_image(model, poster_prompt, resolution="4K", aspect_ratio="9:16")
# 竖版手机海报，$0.05/张

💡 场景建议：对于需要大批量生成图像的场景（如电商产品图、营销素材），建议通过 APIYI apiyi.com 平台调用，不仅价格最低，还提供详细的调用日志和用量统计，便于成本控制。

场景三：Node.js / TypeScript 项目集成

如果你的项目使用 JavaScript/TypeScript，可以通过 HTTP 请求直接集成：

import axios from "axios";
import * as fs from "fs";

const API_KEY = "YOUR_APIYI_API_KEY";
// APIYI 兼容谷歌原生格式，价格 $0.05/次
const BASE_URL = "https://vip.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent";

interface GenerateImageOptions {
  prompt: string;
  resolution?: "1K" | "2K" | "4K";
  aspectRatio?: string;
  outputPath?: string;
}

async function generateImage({
  prompt,
  resolution = "2K",
  aspectRatio = "1:1",
  outputPath = "output.png",
}: GenerateImageOptions): Promise<string> {
  const response = await axios.post(
    BASE_URL,
    {
      contents: [{ role: "user", parts: [{ text: prompt }] }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        resolution,
        aspectRatio,
      },
    },
    {
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${API_KEY}`,
      },
    }
  );

  const imageData =
    response.data.candidates[0].content.parts[0].inlineData.data;
  fs.writeFileSync(outputPath, Buffer.from(imageData, "base64"));
  return outputPath;
}

// 使用示例
generateImage({
  prompt: "现代简约风格 App 启动页，深色主题，科技感强，4K",
  resolution: "4K",
  aspectRatio: "9:16",
  outputPath: "app_splash.png",
}).then((path) => console.log(`生成完成: ${path}`));

成本优化策略

在实际项目中，合理控制 Nano Banana Pro API 的调用成本非常重要：

🎯 选择建议：对于初创团队和个人开发者，推荐先在 APIYI apiyi.com 平台上用免费额度进行测试，验证图像质量符合需求后再规模化调用。平台提供按量计费，无最低消费限制。

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

الخلاصة

النقاط الجوهرية لاستدعاء Nano Banana Pro API:

1. استخدام تنسيق Gemini الأصلي: يجب استخدام SDK الخاص بـ google-generativeai أو طلبات HTTP الأصلية، فتنسيق OpenAI SDK غير متوافق.
2. أفضل سعر مع APIYI: التكلفة هي 0.05 دولار لكل عملية، وهو أقل بنسبة 44% من KIE.ai (0.09 دولار) وأقل بنسبة 79% من جوجل الرسمي (0.24 دولار).
3. 3 بارامترات رئيسية: responseModalities: ["IMAGE"] و resolution (1K/2K/4K) و aspectRatio.
4. رسم النصوص هو الميزة الأساسية: للملصقات التسويقية، والإنفوجرافيك، والمحتوى ثنائي اللغة، يعد Nano Banana Pro الخيار الأفضل حالياً.

بالنسبة للفرق التي تحتاج إلى استدعاءات ضخمة أو نشر في بيئة الإنتاج، نوصي بالوصول عبر APIYI (apiyi.com)؛ حيث تعمل المنصة باستقرار وتوفر سجلات API مفصلة ومراقبة للاستهلاك، مما يساعد في التحكم الدقيق في تكاليف توليد الصور.

المصادر والمراجع

1. وثائق توليد الصور عبر Google Gemini API

   • الرابط: ai.google.dev/gemini-api/docs/image-generation
   • الوصف: شرح معلمات API الرسمية وقيود الاستخدام لـ Nano Banana Pro

2. Google Generative AI Python SDK

   • الرابط: github.com/google-gemini/generative-ai-python
   • الوصف: تثبيت SDK ومرجع API الكامل، الكود الوارد في هذا المقال يعتمد على هذا الـ SDK

3. وثائق ربط Nano Banana Pro على منصة APIYI

   • الرابط: docs.apiyi.com
   • الوصف: شرح توافق APIYI مع التنسيقات الأصلية من جوجل وتفاصيل التسعير

المؤلف: الفريق التقني
للتواصل التقني: نرحب بمشاركة أعمالك التي أنشأتها باستخدام Nano Banana Pro في قسم التعليقات. لمزيد من تقنيات توليد الصور بالذكاء الاصطناعي، يمكنك زيارة المجتمع التقني لـ APIYI عبر apiyi.com