حل مشكلة خطأ API للصور في Nano Banana 2: 3 خطوات للتبديل إلى تنسيق استدعاء generateContent الصحيح

ملاحظة من الكاتب: شرح مفصل للسبب الجذري لخطأ API توليد الصور "not supported model for image generation" في Nano Banana 2، وكيفية التبديل من تنسيق OpenAI إلى تنسيق Google الأصلي generateContent للاستدعاء الصحيح.

هل واجهت خطأ <span style="color: #ff6b35; font-weight: bold;">not supported model for image generation</span> عند استخدام Nano Banana 2 لتوليد الصور؟ هذا أحد أكثر مشاكل استدعاء API صور Gemini شيوعًا بين المطورين حاليًا. ستوضح هذه المقالة السبب الجذري للخطأ والطريقة الصحيحة للاستدعاء، لمساعدتك على إصلاح خطأ API صور Nano Banana 2 بسرعة.

القيمة الأساسية: بعد قراءة هذه المقالة، ستتعرف على الاختلافات في استدعاء API بين نموذج صور Gemini ونموذج Imagen، وستتقن الاستخدام الصحيح لنقطة النهاية generateContent، لحل مشكلة الخطأ في 3 خطوات.

السبب الأساسي لخطأ API صور Nano Banana 2

شرح مفصل لخطأ API صور Nano Banana 2

عند استخدام نقطة النهاية /v1/images/generations المتوافقة مع تنسيق OpenAI لاستدعاء Nano Banana 2 (gemini-3.1-flash-image-preview) أو Nano Banana Pro (gemini-3-pro-image-preview)، سيعيد النظام الخطأ التالي:

not supported model for image generation, only imagen models are supported
(request id: 20260315043447253411115cvUiXJMF)
new_api_error convert_request_failed, 500

السبب الأساسي لهذا الخطأ هو: نماذج صور Gemini ونماذج Imagen هما نموذجان مختلفان تمامًا في البنية.

• نماذج Imagen (مثل imagen-3.0-generate-001) هي نماذج متخصصة لتوليد الصور، وتستخدم نقطة النهاية /v1/images/generations أو :predict
• نماذج صور Gemini (سلسلة Nano Banana) هي نماذج لغة متعددة الوسائط، يمكنها إخراج النصوص والصور في نفس الوقت، ويجب استخدام نقطة النهاية :generateContent

ببساطة، لقد استخدمت "قناة مخصصة لتحويل النص إلى صورة" لاستدعاء "نموذج محادثة متعدد الوسائط"، وبالتالي حدث الخطأ بسبب عدم تطابق التنسيق.

تنسيق الاستدعاء الصحيح لواجهة برمجة تطبيقات Nano Banana 2 للصور

مقارنة بين الاستدعاء الخاطئ والصحيح

مثال على طلب خاطئ لواجهة برمجة تطبيقات Nano Banana 2 للصور

إليك طريقة الاستدعاء الخاطئة التي ستؤدي إلى خطأ:

# ❌ خطأ: استخدام تنسيق OpenAI لاستدعاء Nano Banana 2
curl -X POST https://api.apiyi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "قطة برتقالية لطيفة تنام تحت أشعة الشمس",
    "size": "1024x1024",
    "n": 1
  }'
# الإرجاع: not supported model for image generation

مثال على طلب صحيح لواجهة برمجة تطبيقات Nano Banana 2 للصور

إليك طريقة الاستدعاء الصحيحة باستخدام تنسيق generateContent:

# ✅ صحيح: استخدام تنسيق Google الأصلي generateContent
curl -X POST https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "قطة برتقالية لطيفة تنام تحت أشعة الشمس"}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

🎯 تلميح تقني: عند استدعاء Nano Banana 2 عبر منصة APIYI (apiyi.com)، لا تحتاج إلى تكوين حساب Google Cloud بشكل منفصل، يمكنك استخدام مفتاح API موحد لاستدعاء نقطة نهاية generateContent مباشرة.

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

3 خطوات لإصلاح أخطاء واجهة برمجة تطبيقات Nano Banana 2 للصور

الخطوة 1: تغيير نقطة نهاية API

قم بتحويل عنوان الطلب من تنسيق OpenAI إلى تنسيق generateContent:

# نقطة النهاية الخاطئة
https://api.apiyi.com/v1/images/generations

# نقطة النهاية الصحيحة (Nano Banana 2)
https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent

# نقطة النهاية الصحيحة (Nano Banana Pro)
https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent

الخطوة 2: تعديل هيكل جسم الطلب

قم بتغيير معاملات prompt + size الخاصة بـ OpenAI إلى هيكل contents + generationConfig الأصلي من Google. المعاملات الرئيسية:

• contents.parts.text: نص وصف الصورة
• generationConfig.responseModalities: يجب تعيينها إلى ["TEXT", "IMAGE"]

الخطوة 3: معالجة بيانات الاستجابة

الصور التي يتم إرجاعها بواسطة generateContent مشفرة بـ Base64 مضمنة، وليست روابط URL. تحتاج إلى استخراج الصور وفك تشفيرها من الاستجابة.

مثال بسيط جدًا باستخدام Python

import requests
import base64

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apiyi.com"  # واجهة APIYI الموحدة

response = requests.post(
    f"{BASE_URL}/v1beta/models/gemini-3.1-flash-image-preview:generateContent",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "contents": [{"parts": [{"text": "قطة برتقالية لطيفة تنام تحت أشعة الشمس"}]}],
        "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
    }
)

result = response.json()
for part in result["candidates"][0]["content"]["parts"]:
    if "inlineData" in part:
        img_data = base64.b64decode(part["inlineData"]["data"])
        with open("output.png", "wb") as f:
            f.write(img_data)
        print("تم حفظ الصورة كـ output.png")
    elif "text" in part:
        print("وصف النموذج:", part["text"])

import requests
import base64
import os
from typing import Optional

def generate_image(
    prompt: str,
    model: str = "gemini-3.1-flash-image-preview",
    aspect_ratio: str = "1:1",
    output_path: str = "output.png",
    api_key: Optional[str] = None
) -> dict:
    """
    إنشاء صورة باستخدام نقطة نهاية generateContent لـ Nano Banana 2

    Args:
        prompt: وصف الصورة
        model: اسم النموذج
        aspect_ratio: نسبة العرض إلى الارتفاع (1:1, 16:9, 9:16, 4:3, 3:4)
        output_path: مسار ملف الإخراج
        api_key: مفتاح API

    Returns:
        قاموس يحتوي على مسار الملف ووصف النموذج
    """
    api_key = api_key or os.getenv("APIYI_API_KEY")
    base_url = "https://api.apiyi.com"  # واجهة APIYI الموحدة

    response = requests.post(
        f"{base_url}/v1beta/models/{model}:generateContent",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        },
        json={
            "contents": [{"parts": [{"text": prompt}]}],
            "generationConfig": {
                "responseModalities": ["TEXT", "IMAGE"],
                "imageConfig": {"aspectRatio": aspect_ratio}
            }
        },
        timeout=60
    )

    if response.status_code != 200:
        raise Exception(f"فشل طلب API: {response.status_code} - {response.text}")

    result = response.json()
    candidates = result.get("candidates", [])
    if not candidates:
        raise Exception("لم يتم إرجاع نتائج صالحة")

    output = {"text": "", "image_path": ""}
    for part in candidates[0]["content"]["parts"]:
        if "inlineData" in part:
            img_data = base64.b64decode(part["inlineData"]["data"])
            with open(output_path, "wb") as f:
                f.write(img_data)
            output["image_path"] = output_path
        elif "text" in part:
            output["text"] = part["text"]

    return output

# مثال على الاستخدام
result = generate_image(
    prompt="لوحة مناظر طبيعية بأسلوب الحبر والفرشاة الصيني، مع جبال بعيدة مغطاة بالضباب الخفيف",
    model="gemini-3.1-flash-image-preview",
    aspect_ratio="16:9",
    output_path="landscape.png"
)
print(f"تم حفظ الصورة: {result['image_path']}")
print(f"وصف النموذج: {result['text']}")

اقتراح: احصل على مفتاح API عبر منصة APIYI (apiyi.com)، توفر المنصة رصيد اختبار مجاني، وتدعم استدعاء generateContent لنموذجي Gemini للصور: Nano Banana 2 و Nano Banana Pro.

مقارنة نماذج توليد الصور Nano Banana 2 عبر API

فهم الاختلافات في طرق استدعاء API لنماذج توليد الصور المختلفة يمكن أن يساعدك في تجنب أخطاء التنسيق المشابهة:

شرح المعلمات الرئيسية لـ API صور Nano Banana 2

تدعم نقطة النهاية generateContent معلمات غنية لتوليد الصور:

💡 ملاحظة مهمة: يجب أن يحتوي responseModalities على كل من "TEXT" و "IMAGE"، لأن تعيين ["IMAGE"] فقط سيؤدي إلى فشل الطلب. هذا لأن نماذج صور Gemini هي نماذج متعددة الوسائط وتنتج دائمًا وصفًا نصيًا وصورة معًا.

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

الخلاصة

النقاط الأساسية لأخطاء واجهة برمجة التطبيقات (API) للصور في Nano Banana 2:

1. سبب الخطأ واضح: استخدام /v1/images/generations (تنسيق OpenAI) لاستدعاء نموذج صور Gemini سيؤدي إلى خطأ "not supported model".
2. التبديل إلى generateContent: نقطة النهاية الصحيحة هي /v1beta/models/gemini-3.1-flash-image-preview:generateContent.
3. تعيين responseModalities: يجب تضمين ["TEXT", "IMAGE"] في generationConfig، وإلا لن يتم توليد الصور.

عند مواجهة خطأ في واجهة برمجة التطبيقات (API) لـ Nano Banana 2، الجوهر هو جملة واحدة: استبدل نقطة نهاية توليد الصور الخاصة بـ OpenAI بنقطة النهاية الأصلية لـ Google وهي generateContent.

نوصي باختبار Nano Banana 2 و Nano Banana Pro بسرعة عبر APIYI (apiyi.com)، حيث توفر المنصة رصيدًا مجانيًا وتدعم الاستدعاء المباشر بتنسيق generateContent، دون الحاجة إلى تكوين حساب Google Cloud.

📚 المراجع

1. وثائق توليد الصور في Google Gemini: دليل توليد الصور الرسمي لـ Gemini API

   • الرابط: ai.google.dev/gemini-api/docs/image-generation
   • الوصف: يتضمن شرحًا كاملاً للمعلمات والأمثلة لنقطة النهاية generateContent

2. مرجع API generateContent من Google: وثائق واجهة توليد المحتوى في Gemini API

   • الرابط: ai.google.dev/api/generate-content
   • الوصف: شرح تفصيلي لهيكل الطلب والاستجابة لنقطة النهاية generateContent

3. وثائق توافق Google Gemini مع OpenAI: شرح التوافق بين تنسيق Gemini وOpenAI

   • الرابط: ai.google.dev/gemini-api/docs/openai
   • الوصف: لفهم الميزات التي تدعم تنسيق OpenAI المتوافق وأيها يتطلب التنسيق الأصلي

المؤلف: فريق APIYI التقني
التواصل التقني: نرحب بالنقاش في قسم التعليقات حول مشاكل استدعاء واجهة برمجة تطبيقات (API) للصور Nano Banana 2، للمزيد من المصادر يمكن زيارة مركز وثائق APIYI docs.apiyi.com