تجنب أخطاء استدعاء نموذج Nano Banana Pro API: إعداد imageConfig يحدد الدقة، لا تضف معامل size

يقع العديد من المطورين عند استدعاء واجهة برمجة تطبيقات Nano Banana Pro (التي تقابل نموذج gemini-3-pro-image-preview من Google) لأول مرة في فخ شائع: إعادة استخدام معامل size: "1024x1024" من حقبة OpenAI / DALL-E، مما يؤدي إما إلى عدم تغير دقة الصورة مهما حاولت تعديلها، أو ظهور خطأ 400 مباشرة، أو تجاهل الخادم للمعامل بصمت.

هذا هو "الخطأ الأكثر شيوعاً" عند استدعاء Nano Banana Pro API. الطريقة الصحيحة هي: يتم تحديد الدقة من خلال معاملين هما imageConfig.imageSize (للتحكم في الوضوح 1K/2K/4K) و imageConfig.aspectRatio (لنسبة الأبعاد 1:1/16:9/…)، ولا يجب تمرير أي حقل باسم size. سنشرح في هذا المقال كل ما تحتاج لمعرفته، مع توفير أكواد curl / Python / Node.js جاهزة للنسخ والتشغيل.

نقاط أساسية لاستدعاء Nano Banana Pro API

قبل البدء بلصق الأكواد، تذكر هذه القواعد الثلاث الذهبية — فبمجرد فهمها، ستصبح 90% من تفاصيل هذا المقال واضحة:

تسمية النموذج: Nano Banana Pro = gemini-3-pro-image-preview (يُعرف أيضاً بـ Gemini 3 Pro Image)، وهو ينتمي إلى سلسلة نماذج توليد/تعديل الصور من Google Gemini 3. قد يسميه البعض Nano Banana 2، لكنه في الجوهر نفس النموذج.
البروتوكول هو بروتوكول Gemini الأصلي: ليس متوافقاً مع بروتوكول OpenAI Chat Completions. مسار الطلب هو :generateContent، والحقول في المستوى الأعلى لجسم الطلب هي contents و generationConfig، ولا توجد حقول messages أو size بأسلوب OpenAI.
الدقة = imageSize × aspectRatio: يتحكم imageSize في مستوى الوضوح (512 / 1K / 2K / 4K)، بينما يتحكم aspectRatio في نسبة أبعاد الصورة (1:1 / 16:9 / 9:16 / …). كلاهما يحدد معاً عدد البكسلات النهائي.

📌 خلاصة القول: عند استدعاء Nano Banana Pro باستخدام بروتوكول Gemini، تخلص تماماً من عادة استخدام size: "1024x1024" الخاصة بـ OpenAI. خدمة وكيل API الخاص بـ APIYI (apiyi.com) تدعم بروتوكول Gemini الأصلي بالكامل، وأي صيغة صحيحة لـ imageConfig تعمل مع Google ستعمل أيضاً مع APIYI.

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

المعامل	الموقع	الوظيفة	مثال للقيمة
`imageSize`	`generationConfig.imageConfig`	مستوى الوضوح	`"512"` / `"1K"` / `"2K"` / `"4K"`
`aspectRatio`	`generationConfig.imageConfig`	نسبة الأبعاد	`"1:1"` / `"16:9"` / `"9:16"` / `"4:3"` إلخ
`responseModalities`	`generationConfig`	نمط المخرجات	`["IMAGE"]` (مطلوب)
`contents[].parts[].text`	`contents`	موجه نصي	نص حر
`contents[].parts[].inline_data`	`contents`	صورة الإدخال (base64)	تحتوي على `mime_type` و `data`

⚠️ حقل size غير موجود في الجدول: لأنه ببساطة ليس معاملًا صالحًا في بروتوكول Gemini، لذا لا تقم بتمريره.

لماذا يجب ألا تضيف معامل `size`؟ الأسباب المتعلقة بطبقة البروتوكول

هذا هو الجزء الأهم في هذا المقال. سنشرح الأمر بعمق من خلال ثلاثة مستويات.

مستوى البروتوكول: Gemini و OpenAI معياران مستقلان

تستخدم واجهة برمجة تطبيقات الصور الخاصة بـ OpenAI (مثل DALL-E 2/3 و gpt-image-1) معامل size: "1024x1024" كـ "سلسلة نصية" في المستوى الأعلى؛ بينما صممت Google واجهة برمجة تطبيقات الصور لـ Gemini 3 باستخدام كائن imageConfig متداخل، وهذان المعياران مستقلان تماماً عن بعضهما. وبما أن Nano Banana Pro يعتمد على بروتوكول Gemini الأصلي، فإن:

❌ size: "1024x1024" —— بروتوكول Gemini لا يحتوي على هذا الحقل.
❌ size: "1K" —— لا يوجد هذا الحقل.
❌ n: 4 —— لا يوجد حقل "توليد N من الصور دفعة واحدة" كما في OpenAI.
✅ imageConfig.imageSize: "1K" —— صحيح.
✅ imageConfig.aspectRatio: "16:9" —— صحيح.

مستوى السلوك: ماذا يحدث عند إرسال `size` بشكل إضافي؟

عادةً ما تتعامل الخوادم مع هذا الموقف بثلاث طرق، ولا واحدة منها هي ما تريده:

التجاهل الصامت: تقوم بوابة الربط (Gateway) بحذف الحقول غير المعروفة باعتبارها حقولاً غير صالحة، فتظن أن طلبك قد تم تنفيذه، بينما في الواقع يتم إخراج الصورة بدقة 1K ونسبة 1:1 افتراضياً.
إرجاع خطأ 400 مباشرة: البوابات التي تطبق فحصاً صارماً للمخطط (Schema) سترفض الطلب فوراً بسبب وجود حقل غير معروف.
التأثير على الفوترة/التوجيه: قد تقوم بعض طبقات الوكيل (Proxy) بالتعامل مع size كإشارة توجيه وتوجيه الطلب إلى إصدار خاطئ من نقطة النهاية.

مستوى الهندسة: تجنب الديون البرمجية الفوضوية

تقوم العديد من الفرق بتغليف واجهات برمجة تطبيقات متعددة مثل OpenAI و Gemini و Stability في طبقة استدعاء واحدة، ويعتادون على إعادة استخدام "حقل size عام"، وهو ما يبدو أنيقاً ولكنه في الواقع بيئة خصبة للأخطاء. نوصي عند استدعاء واجهات Gemini الأصلية مثل Nano Banana Pro، بإنشاء مسار تحويل منفصل، حيث يتم تعيين size صراحةً إلى imageConfig.imageSize + imageConfig.aspectRatio بدلاً من تمرير size الأصلي مباشرة.

💡 نصيحة: عند استخدام APIYI (apiyi.com) لاستدعاء Nano Banana Pro، اكتب دالة تحويل معاملات بسيطة، لتقوم بتفكيك السلاسل النصية التي اعتاد عليها فريقك مثل "1024x1024" إلى imageSize: "1K" + aspectRatio: "1:1"، وذلك لمنع حدوث تداخل في المعاملات من المصدر.

جدول المقارنة الكامل لـ imageSize × aspectRatio

مستويات imageSize والفوترة

imageSize	الحد الأقصى التقريبي للدقة	مخرجات الرموز (Tokens)	السعر (مرجع)	السيناريو الموصى به
`"512"`	مستوى 512×512	منخفض	الأرخص	صور مصغرة / مسودات
`"1K"`	مستوى 1024×1024	~1120	≈ $0.134	الخيار الافتراضي
`"2K"`	مستوى 2048×2048	~1120	≈ $0.134	ملصقات عالية الدقة
`"4K"`	مستوى 4096×4096	~2000	≈ $0.24 (أغلى بنسبة ~80%)	جودة الطباعة

💰 تنبيه التكلفة: دقة 4K أغلى بنسبة 80% تقريباً من 1K/2K، فلا تستخدمها بشكل عشوائي. في معظم تطبيقات الويب/الهواتف، تكفي دقة 1K، ولا تلجأ إلى 4K إلا عند الحاجة القصوى لدقة فائقة. يرجى مراجعة الأسعار المحدثة على موقع APIYI (apiyi.com).

قائمة دعم aspectRatio الكاملة

النسبة	الاستخدام
`"1:1"`	صور الملف الشخصي / مربعات التواصل الاجتماعي
`"16:9"`	غلاف فيديو أفقي / خلفيات سطح المكتب
`"9:16"`	فيديو قصير عمودي / خلفيات الهاتف
`"4:3"`	الصور التقليدية (أفقية)
`"3:4"`	الصور التقليدية (عمودية)
`"3:2"` / `"2:3"`	النسبة القياسية لكاميرات DSLR
`"4:5"` / `"5:4"`	صور إنستغرام
`"21:9"`	شاشات عريضة جداً (طابع سينمائي)
`"1:4"` / `"4:1"`	لافتات إعلانية طويلة (Banner)
`"1:8"` / `"8:1"`	لافتات طويلة جداً لاستخدامات خاصة

التركيبات الشائعة → تعيين البكسل النهائي

imageSize	aspectRatio	البكسل الناتج التقريبي
`1K`	`1:1`	1024 × 1024
`1K`	`16:9`	1024 × 576
`1K`	`9:16`	576 × 1024
`2K`	`1:1`	2048 × 2048
`2K`	`16:9`	2048 × 1152
`4K`	`1:1`	4096 × 4096
`4K`	`9:16`	2304 × 4096
`4K`	`21:9`	4096 × 1728

ملاحظة: قد تختلف البكسلات الفعلية قليلاً بمقدار ±N بسبب قواعد المحاذاة الداخلية للنموذج، لكن هذا لا يؤثر على مستوى الوضوح البصري.

إليك الكود البرمجي الصحيح لاستدعاء واجهة برمجة تطبيقات (API) Nano Banana Pro.

فيما يلي أمثلة بأقل قدر من الكود اللازم للتشغيل بثلاث لغات برمجة. جميع الأمثلة تؤدي المهمة نفسها: إدخال صورة أصلية + موجه (prompt)، والحصول على صورة مخرجة بدقة 1K ونسبة أبعاد 1:1.

نسخة curl (الأكثر وضوحاً لتصحيح الأخطاء)

curl -X POST \
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer مفتاح-APIYI-الخاص-بك" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAA...(بيانات الصورة الأصلية بصيغة base64)"
          }
        },
        {
          "text": "حوّل هذه الصورة إلى نمط سايبربانك، مع الحفاظ على وضعية الشخصية"
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

نسخة Python (يُنصح باستخدام requests مباشرة، دون الاعتماد على أي SDK)

import base64
import requests

with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
    headers={
        "Authorization": "Bearer مفتاح-APIYI-الخاص-بك",
        "Content-Type": "application/json",
    },
    json={
        "contents": [{
            "parts": [
                {"inline_data": {"mime_type": "image/png", "data": img_b64}},
                {"text": "حوّل هذه الصورة إلى نمط سايبربانك، مع الحفاظ على وضعية الشخصية"},
            ]
        }],
        "generationConfig": {
            "responseModalities": ["IMAGE"],
            "imageConfig": {
                "aspectRatio": "1:1",
                "imageSize": "1K",
            },
        },
    },
    timeout=120,
)

data = resp.json()
out_b64 = data["candidates"][0]["content"]["parts"][0]["inline_data"]["data"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(out_b64))

نسخة Node.js (استخدام fetch الأصلي، لتجنب قيام الـ SDK بحذف إعدادات imageConfig)

import fs from "node:fs";

const imgB64 = fs.readFileSync("input.png").toString("base64");

const resp = await fetch(
  "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer مفتاح-APIYI-الخاص-بك",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [{
        parts: [
          { inline_data: { mime_type: "image/png", data: imgB64 } },
          { text: "حوّل هذه الصورة إلى نمط سايبربانك، مع الحفاظ على وضعية الشخصية" },
        ],
      }],
      generationConfig: {
        responseModalities: ["IMAGE"],
        imageConfig: {
          aspectRatio: "1:1",
          imageSize: "1K",
        },
      },
    }),
  },
);

const data = await resp.json();
const outB64 = data.candidates[0].content.parts[0].inline_data.data;
fs.writeFileSync("output.png", Buffer.from(outB64, "base64"));

🔧 لماذا ننصح بشدة باستخدام fetch / requests الأصلي؟: من المعروف في هذا المجال أن بعض حزم SDK (بما في ذلك الإصدارات القديمة من LiteLLM وبعض إصدارات Google Node SDK) تقوم بتصفية الحقول غير المعروفة مثل imageConfig وتعتبرها غير صالحة، مما يؤدي إلى تجاهل إعدادات imageSize و aspectRatio. بناء جسم الطلب (JSON) يدوياً يجنبك هذه المشكلة بنسبة 100%. إذا كنت مصراً على استخدام SDK، يرجى التأكد من التحديث إلى أحدث إصدار والتحقق من جسم الطلب النهائي عبر طباعته (console) في معترض الطلبات (interceptor).

قائمة التحقق لتجنب أخطاء الاستدعاء: 6 أخطاء شائعة

الخطأ 1: تمرير معامل size الخاص بـ OpenAI

// ❌ خطأ: size ليس حقلاً صالحاً في بروتوكول Gemini
{
  "contents": [...],
  "size": "1024x1024",
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" } }
}

// ✅ صحيح: احذف size واحتفظ بـ imageConfig فقط
{
  "contents": [...],
  "generationConfig": { "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }, "responseModalities": ["IMAGE"] }
}

الخطأ 2: استخدام الشرطة السفلية (snake_case) في أسماء الحقول

أسماء حقول imageConfig في واجهة Gemini 3 تستخدم حالة الجمل (camelCase): imageSize، aspectRatio، responseModalities. الأخطاء الشائعة:

❌ image_size / aspect_ratio / response_modalities
✅ imageSize / aspectRatio / responseModalities

الخطأ 3: حذف imageConfig بواسطة الـ SDK

كما ذكرنا سابقاً، بعض إصدارات SDK تقوم بتصفية الحقول غير المعروفة. طريقة التحقق:

اطبع جسم الطلب HTTP الفعلي قبل وبعد استدعاء الـ SDK.
استخدم mitmproxy أو Charles لالتقاط الطلب الفعلي الصادر.
إذا وجدت أن imageConfig قد اختفى، استخدم fetch / requests الأصلي.

الخطأ 4: نسيان responseModalities

// ❌ عند عدم ضبط responseModalities، قد يتم إرجاع نص فقط بدلاً من صورة
{ "generationConfig": { "imageConfig": {...} } }

// ✅ يجب التصريح صراحةً بأن نمط الاستجابة يتضمن IMAGE
{ "generationConfig": { "imageConfig": {...}, "responseModalities": ["IMAGE"] } }

الخطأ 5: عدم تنفيذ التراجع الأسي (Exponential Backoff) عند حدوث خطأ 429

عند تشبع الحمل على الخادم، سيتم إرجاع خطأ مثل:

{ "error": { "message": "حمل الخادم مرتفع حالياً، يرجى المحاولة لاحقاً", "type": "upstream_error", "code": 429 } }

الطريقة الصحيحة هي إعادة المحاولة مع تراجع أسي (3 ثوانٍ ← 6 ثوانٍ ← 12 ثانية)، لا تحاول إعادة الطلب فوراً لأن ذلك سيزيد من الازدحام:

import time

for attempt in range(3):
    resp = requests.post(url, json=body, headers=headers, timeout=120)
    if resp.status_code != 429:
        break
    time.sleep(3 * (2 ** attempt))   # 3 ثوانٍ، 6 ثوانٍ، 12 ثانية

الخطأ 6: وضع صور مرجعية متعددة في مكان خاطئ

يدعم Nano Banana Pro إدخال صور متعددة (صورة أصلية + صور مرجعية). يجب وضع جميع الصور كعناصر inline_data متعددة داخل مصفوفة parts، مع وضع الموجه النصي في نهاية المصفوفة:

// ✅ صحيح: الصور أولاً، ثم النص
"parts": [
  { "inline_data": { "mime_type": "image/png", "data": "base64 الصورة الأصلية" } },
  { "inline_data": { "mime_type": "image/png", "data": "base64 الصورة المرجعية 1" } },
  { "inline_data": { "mime_type": "image/png", "data": "base64 الصورة المرجعية 2" } },
  { "text": "يرجى نقل نمط الصورة الأصلية ليتناسب مع ألوان المرجع 1، واستخدام المرجع 2 لتكوين الصورة" }
]

🧰 ملخص تجنب الأخطاء: اجعل النقاط الست أعلاه جزءاً من "قائمة التحقق" (Checklist) الخاصة بك عند التعامل مع Nano Banana Pro. مراجعتها قبل كل استدعاء جديد ستجنبك أكثر من 90% من الأخطاء البرمجية الشائعة. نقاط نهاية Nano Banana Pro في APIYI (apiyi.com) تتبع بروتوكول Gemini بالكامل، لذا فإن جميع هذه النصائح قابلة للتطبيق.

تفكيك سير عمل استدعاء المستخدم: أين تكمن احتمالية الخطأ الأكبر؟

تتطابق سجلات الاستدعاء التي يشاركها العديد من القراء مع المسار الذي قدمته:

前端 POST /api/generate
  → server.js استخراج المعاملات
  → التحقق من modelKey.startsWith('nano-banana')
  → _generateViaGemini() تجميع جسم الطلب
  → POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent
  → إرجاع النتيجة / إعادة المحاولة

دعونا نحدد المراحل الأكثر عرضة للأخطاء:

المرحلة	المشكلة الشائعة	الاقتراح
معاملات الواجهة الأمامية	تمرير `size: "1024x1024"` كعادة	تقسيمها إلى `imageSize` + `aspectRatio` وتمريرها
تجميع الجسم في server.js	تمرير حقل size إلى Gemini بالخطأ	حذف حقل `size` صراحةً في دالة التجميع
مسار النموذج	توجيه `nano-banana` إلى إصدار 1.5 بدلاً من 3 Pro	كتابة اسم النموذج بدقة `gemini-3-pro-image-preview`
إرسال الطلب	استخدام إصدار SDK يحتوي على تحقق من المخطط (schema)	استخدام `fetch` الأصلي، أو تحديث SDK إلى أحدث إصدار
معالجة الأخطاء	رمي خطأ 429 مباشرة للمستخدم	استخدام إعادة المحاولة مع التراجع الأسي 3 مرات
تحليل الاستجابة	الاعتماد على `text` افتراضياً بينما النتيجة IMAGE	المسار الصحيح `candidates[0].content.parts[0].inline_data.data`

📋 باختصار: هيكل المسار الذي تتبعه صحيح، فقط تخلص من حقل size الزائد في مرحلة "استخراج المعاملات"، وتأكد من أن server.js لا يعيد إضافته خارج generationConfig؛ وبذلك ستكون السلسلة نظيفة تماماً.

الأسئلة الشائعة (FAQ)

س1: هل Nano Banana Pro و Nano Banana 2 هما نفس الشيء؟
نعم. يشير الكثيرون في المجتمع إلى Gemini 3 Pro Image (gemini-3-pro-image-preview) باسم Nano Banana 2 أو Nano Banana Pro، وهي مسميات لنفس النموذج. على منصة APIYI apiyi.com، يجب الاعتماد على اسم النموذج المذكور في الوثائق الرسمية.

س2: ماذا يحدث إذا لم أقم بتمرير imageConfig؟
سيقوم النموذج بالإخراج بناءً على القيم الافتراضية الداخلية (عادةً 1K + 1:1). إذا لم تكن تهتم بالدقة، يمكنك تجاهله؛ أما إذا كانت لديك متطلبات خاصة للأبعاد، يجب تمرير imageConfig صراحةً.

س3: هل يمكنني استخدام بروتوكول Gemini وتمرير size كما في OpenAI؟
لا يمكنك القيام بذلك بشكل موثوق. بروتوكول Gemini لا يحتوي على حقل size، والخلط بينهما سيؤدي فقط إلى سلوكيات غير متوقعة. استخدام imageConfig.imageSize + imageConfig.aspectRatio هو الطريقة الأكثر أماناً.

س4: هل اختيار 4K لـ imageSize يضمن جودة أفضل دائماً؟
ستكون التفاصيل أغنى، لكن التكلفة تقارب الضعف (~$0.24 مقابل ~$0.134)، كما يستغرق وقت التوليد فترة أطول. بالنسبة لصور الويب/التطبيقات، غالباً ما تكون 1K أو 2K كافية. يُنصح باختبار مجموعة من الصور الفعلية ومقارنتها بصرياً قبل اتخاذ القرار.

س5: ما الفرق بين استدعاء Nano Banana Pro عبر APIYI apiyi.com وبين استدعاء Google API مباشرة؟
توفر APIYI مصادقة موحدة بأسلوب OpenAI (Bearer Token) + وصول متاح محلياً + فوترة موحدة، بينما يظل بروتوكول الاستدعاء مطابقاً تماماً لتنسيق Gemini الأصلي. هذا يعني أن imageConfig / aspectRatio / responseModalities التي تراها في وثائق Google الرسمية متكافئة تماماً على APIYI apiyi.com.

س6: لماذا تخرج الصورة بدقة 1K رغم ضبطي لـ imageSize على "2K"؟
هناك 3 أسباب شائعة: (1) استخدام SDK يقوم بتصفية الحقول غير المعروفة، (2) كتابة اسم الحقل كـ image_size، (3) خطأ في مستوى تداخل generationConfig. قم بالتقاط حزمة الشبكة الفعلية أولاً للتأكد من أن جسم الطلب يطابق المواصفات، ثم افحص جانب الخادم.

س7: ماذا أفعل حيال قيود السرعة (429) من المصدر؟
استخدم إعادة المحاولة مع التراجع الأسي (3 ثوانٍ/6 ثوانٍ/12 ثانية). إذا كانت الخدمة حساسة للتأخير، يمكنك التبديل بين مجموعات مختلفة في مساحة عمل APIYI apiyi.com أو طلب حصة مستقلة. لا تكتب أبداً حلقة تكرار لا نهائية لإعادة المحاولة فوراً، لأن ذلك سيؤدي إلى استمرار تقييدك من قبل سياسات الحد من السرعة.

س8: هل هناك حد أقصى لعدد الصور المدخلة؟
واجهة Gemini 3 image تفرض قيوداً على إجمالي حجم الصور في الطلب الواحد (عادةً تُحسب بالميجابايت، راجع الوثائق الرسمية). يُنصح بألا تتجاوز الصور المرجعية 4-5 صور، مع التحكم في حجم كل منها (قم بتغيير الحجم قبل تحويلها إلى base64)، وإلا ستواجه خطأ 413 أو انتهاء مهلة الطلب.

ملخص: اجعل "طريقة المعاملين للدقة" جزءاً من ذاكرتك العضلية

إذا كان عليك تذكر جملة واحدة فقط، فهي:

دقة الإخراج النهائية لنموذج Nano Banana Pro = imageConfig.imageSize × imageConfig.aspectRatio، لا ترسل أي حقول size بنمط OpenAI بعد الآن.

قائمة التحقق الكاملة:

✅ اسم النموذج: gemini-3-pro-image-preview
✅ نقطة النهاية (Endpoint): /v1beta/models/.../generateContent
✅ generationConfig.imageConfig.imageSize ∈ 512 / 1K / 2K / 4K
✅ generationConfig.imageConfig.aspectRatio ∈ 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 21:9 / …
✅ يجب أن يتضمن generationConfig.responseModalities القيمة "IMAGE"
✅ ضع مدخلات الصور المتعددة في مصفوفة parts، واجعل الموجه النصي في النهاية
✅ في حالة حدوث خطأ 429 (تجاوز الحد)، استخدم استراتيجية التراجع الأسي (3 ثوانٍ / 6 ثوانٍ / 12 ثانية)
❌ لا ترسل size: "1024x1024"
❌ لا تكتب image_size / aspect_ratio (تنسيق snake_case خاطئ)
❌ لا تثق بمجموعات أدوات التطوير (SDKs) القديمة التي قد تتجاهل الحقول غير المعروفة، قم بالتقاط حزم البيانات (Packet Capture) للتأكد أولاً

📢 كلمة أخيرة: إذا كنت تقوم بالاتصال بنموذج Nano Banana Pro عبر خدمة وكيل API الخاص بـ APIYI (apiyi.com)، فما عليك سوى نسخ قوالب الأكواد (curl / Python / Node.js) الواردة في هذا المقال مباشرة. جميع المعاملات تتوافق بدقة مع بروتوكول Gemini الأصلي؛ انسخ والصق، ثم استبدل المفتاح، وابدأ العمل.

المؤلف: فريق APIYI · نعمل باستمرار على تنظيم أفضل ممارسات استدعاء النموذج لغة كبير · apiyi.com