حل 3 طرق لإخراج صور PNG من APIYI Nano Banana 2: حقيقة تقليص صور 4K من 30 ميجابايت إلى 8 ميجابايت

ملاحظة المؤلف: شرح مفصل لكيفية إخراج Nano Banana 2 API للصور بتنسيق PNG بدلاً من JPEG، وتحليل الأسباب التقنية وراء انخفاض حجم صور 4K في AI Studio من 30 ميجابايت إلى 8 ميجابايت، مع تغطية فروقات التحكم في التنسيق بين Vertex AI و AI Studio.

يواجه العديد من المطورين هذا الارتباك عند استخدام Nano Banana 2 API لتوليد الصور: API يعيد بيانات بتنسيق base64، فهل هي في الأصل PNG أم JPEG عند حفظها؟ والأكثر حيرة هو أن صور 4K بنفس الدقة، انخفض حجمها في AI Studio من أكثر من 30 ميجابايت إلى حوالي 8 ميجابايت. ستوضح هذه المقالة حقيقة التحكم في التنسيق وتغيرات الحجم بدءاً من الآليات الأساسية لـ API.

القيمة الجوهرية: بعد قراءة هذا المقال، ستتقن الطريقة الصحيحة لإخراج صور بتنسيق PNG عبر Nano Banana 2 API، وستفهم السبب الجذري لتقلص حجم صور 4K.

النقاط الجوهرية لتنسيق مخرجات صور Nano Banana 2 API

لنوضح حقيقة أساسية: بيانات الصور التي يعيدها Nano Banana 2 API مشفرة بـ base64، لكن base64 هو مجرد طريقة ترميز للنقل، بينما البيانات الثنائية الأساسية هي التي تحدد تنسيق الصورة فعلياً.

الآلية الأساسية لمخرجات صور Nano Banana 2 API

يتم إرجاع مخرجات الصور لـ Nano Banana 2 (معرف النموذج: gemini-3.1-flash-image-preview) عبر كائن inlineData، والهيكل كالتالي:

{
  "candidates": [{
    "content": {
      "parts": [{
        "inlineData": {
          "mime_type": "image/png",
          "data": "<BASE64_IMAGE_DATA>"
        }
      }]
    }
  }]
}

هناك خطأ أكدته جوجل رسمياً (GitHub Issue #1824): حقل mime_type في الاستجابة معلن عنه كـ image/png، لكن بيانات البايتات المفكوكة قد تكون بتنسيق JPEG. هذا يعني أنه لا يمكنك الوثوق ببساطة بنوع MIME الذي يعيده API، ويجب عليك تحديد التنسيق الحقيقي من خلال بايتات رأس الملف (magic bytes).

طريقة التحديد بسيطة: رأس ملف JPEG هو \xff\xd8، ورأس ملف PNG هو \x89PNG\r\n\x1a\n.

3 طرق لاستخراج صور بتنسيق PNG من Nano Banana 2 API

هذا هو جوهر المقال: كيف تضمن حصولك على صور بتنسيق PNG حقيقي.

الطريقة الأولى: التحويل عبر عميل Python (موصى به لـ AI Studio)

بما أن Gemini API في AI Studio لا يدعم التحكم في تنسيق الملف من جهة الخادم، فإن الطريقة الأكثر موثوقية هي التحويل من جهة العميل:

import base64
from PIL import Image
from io import BytesIO

# استدعاء Nano Banana 2 لتوليد الصورة
from google import genai
from google.genai import types

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["قطة برتقالية تغفو تحت أشعة الشمس"],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(
            image_size="4K",
            aspect_ratio="1:1"
        ),
    )
)

# الحفظ بتنسيق PNG (بغض النظر عن التنسيق الذي يعيده الـ API فعلياً)
for part in response.parts:
    if image := part.as_image():
        image.save("output.png", format="PNG")  # فرض الحفظ بتنسيق PNG بدون فقدان للجودة

النقطة الجوهرية هنا هي تحديد format="PNG" بشكل صريح داخل image.save("output.png", format="PNG"). إذا لم تقم بتحديد معامل format، ستقوم مكتبة Pillow باستنتاج التنسيق بناءً على امتداد الملف—وهو أمر يعمل في معظم الحالات، لكن التصريح الصريح أكثر أماناً.

import base64
from PIL import Image
from io import BytesIO

def detect_and_save(base64_data: str, output_path: str, target_format: str = "PNG"):
    """
    الكشف عن التنسيق الحقيقي لصورة base64 وتحويلها وحفظها

    Args:
        base64_data: بيانات الصورة المشفرة بـ base64
        output_path: مسار حفظ الملف
        target_format: التنسيق المستهدف (PNG/JPEG/WEBP)
    """
    image_bytes = base64.b64decode(base64_data)

    # الكشف عن التنسيق الحقيقي عبر الـ magic bytes
    if image_bytes[:2] == b'\xff\xd8':
        actual_format = "JPEG"
    elif image_bytes[:8] == b'\x89PNG\r\n\x1a\n':
        actual_format = "PNG"
    elif image_bytes[:4] == b'RIFF':
        actual_format = "WEBP"
    else:
        actual_format = "غير معروف"

    print(f"التنسيق الفعلي الذي أعاده الـ API: {actual_format}")
    print(f"حجم البيانات الأصلية: {len(image_bytes) / 1024 / 1024:.2f} MB")

    # فتح الصورة باستخدام Pillow وتحويلها للتنسيق المطلوب
    img = Image.open(BytesIO(image_bytes))
    print(f"أبعاد الصورة: {img.size[0]}x{img.size[1]}")

    if target_format == "PNG":
        img.save(output_path, format="PNG", optimize=True)
    elif target_format == "JPEG":
        img.save(output_path, format="JPEG", quality=95)
    elif target_format == "WEBP":
        img.save(output_path, format="WEBP", quality=90)

    import os
    saved_size = os.path.getsize(output_path) / 1024 / 1024
    print(f"حجم الملف بعد الحفظ: {saved_size:.2f} MB ({target_format})")

الطريقة الثانية: التحكم في التنسيق عبر خادم Vertex AI

إذا كنت تستخدم Vertex AI لاستدعاء Nano Banana 2، يمكنك تحديد تنسيق الإخراج مباشرة في الطلب، وهي الطريقة الوحيدة التي تدعم التحكم في التنسيق من جهة الخادم:

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

os.environ["GOOGLE_CLOUD_PROJECT"] = "your-project-id"
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

client = genai.Client(http_options=HttpOptions(api_version="v1"))

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["قطة برتقالية تغفو تحت أشعة الشمس"],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(
            image_size="4K",
            aspect_ratio="1:1",
            output_mime_type="image/png",         # تحديد مخرجات PNG
            # compression_quality=75,             # فعال فقط مع JPEG، من 0-100
        ),
    )
)

الطريقة الثالثة: المعالجة الموحدة عبر خدمة وكيل APIYI

عند الاستدعاء عبر خدمة وكيل APIYI، تقوم المنصة بمعالجة مشكلات توافق التنسيق تلقائياً:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://vip.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-3.1-flash-image-preview",
    messages=[
        {"role": "user", "content": "قطة برتقالية تغفو تحت أشعة الشمس"}
    ]
)

🎯 نصيحة اختيار التنسيق: اختر PNG إذا كنت تحتاج إلى جودة بدون فقدان، واختر JPEG إذا كنت تحتاج إلى حجم صغير (جودة 95 تقترب من الجودة الأصلية).
ننصح بإجراء الاختبارات عبر منصة APIYI apiyi.com، حيث تعالج المنصة توافق التنسيقات بشكل موحد، مما يوفر عليك عناء فك تشفير base64 والكشف اليدوي عن التنسيقات.

مقارنة قدرات التحكم في التنسيق لـ Nano Banana 2 API

هذه نقطة يخلط فيها الكثير من المطورين: قدرات التحكم في التنسيق تختلف تماماً بين AI Studio و Vertex AI.

مقارنة دعم معاملات التنسيق في Nano Banana 2 API

وهذا يعني: إذا كنت تستخدم AI Studio لاستدعاء Nano Banana 2، فلا يمكنك التحكم من جهة الخادم في ما إذا كان الإخراج PNG أو JPEG. التنسيق الذي يعيده الـ API يعتمد على السلوك الافتراضي لخوادم Google—وهذا السلوك الافتراضي يحتوي حالياً على خطأ (قد يدعي أنه PNG بينما هو في الواقع JPEG).

مقارنة أحجام الملفات بتنسيقات Nano Banana 2 API المختلفة

بالنسبة لنفس الصورة المولدة بالذكاء الاصطناعي بدقة 4K (4096×4096)، تختلف الأحجام بشكل كبير حسب التنسيق:

تنسيق PNG هو تنسيق بدون فقدان، وحجم الملف يعكس مباشرة تعقيد معلومات الصورة (قيمة الإنتروبيا). كلما زادت تفاصيل الصورة وتعقدت أنسجتها، زاد حجم ملف PNG. هذا هو الأساس لفهم تغير حجم صور 4K في القسم التالي.

تلميح: إذا كان سيناريو تطبيقك لا يتطلب قناة شفافية، فإن JPEG بجودة 95 لا يمكن تمييزه بصرياً عن PNG، لكن حجمه يبلغ ربع إلى ثلث حجم PNG فقط. يمكنك المقارنة السريعة بين تأثير التنسيقين في سيناريوهات حقيقية عبر منصة APIYI apiyi.com.

حقيقة تقليص حجم صور 4K في واجهة برمجة تطبيقات Nano Banana 2

هذا هو السؤال الأكثر إلحاحاً لدى العديد من المستخدمين: لماذا انخفض حجم صور 4K الناتجة عن Nano Banana 2 في AI Studio من أكثر من 30 ميجابايت إلى حوالي 8 ميجابايت؟

تغير حجم صور واجهة برمجة تطبيقات Nano Banana 2 ليس بسبب الصيغة

لنستبعد أولاً سوء فهم شائع: هذا الانخفاض في الحجم ليس بسبب تحويل الصور من PNG إلى JPEG. إذا قمت بفحص "bytes السحرية" (magic bytes)، ستجد أن صيغة البيانات المعادة لم تتغير.

السبب الحقيقي هو أن جوجل قامت بتعديل معلمات حساب النموذج على جانب الخادم، مما أدى إلى تقليل تعقيد المعلومات (قيمة الإنتروبيا) في الصور المولدة. هناك ثلاث آليات محددة لذلك:

السبب الأول: تقليل خطوات الاستدلال (السبب الرئيسي)

عندما يقوم نموذج الانتشار (Diffusion Model) بتوليد صورة، فإنه يمر بعدة جولات من تكرارات إزالة الضجيج. تحدد خطوات إزالة الضجيج بشكل مباشر مدى ثراء تفاصيل الصورة:

• سابقاً: ربما كان يتم استخدام 50-100 خطوة تكرار لإزالة الضجيج، مما ينتج صوراً ذات أنسجة غنية وتفاصيل دقيقة.
• حالياً: ربما انخفض العدد إلى 20-40 خطوة، مما يجعل الصورة واضحة بشكل عام ولكن مع انخفاض في التفاصيل الموضعية وتعقيد الأنسجة.

تقليل خطوات إزالة الضجيج ← تقليل تفاصيل الأنسجة ← انخفاض إنتروبيا المعلومات ← حجم أصغر بعد ضغط PNG بدون فقدان.

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

السبب الثاني: تحسين المعالجة المسبقة على جانب الخادم

بعد اكتمال التوليد وقبل الترميز إلى صيغة PNG، ربما أضافت جوجل معالجة طفيفة لإزالة الضجيج وتبسيط الألوان:

• تقليل الضجيج بشكل طفيف يقلل من التفاصيل عالية التردد.
• تقليل مستويات تدرج الألوان يقلل من دقة انتقالات الألوان.
• هذه المعالجات تجعل ضغط PNG أكثر كفاءة (بكسلات متشابهة أكثر، ونسبة ضغط أعلى).

السبب الثالث: تعديل دقة الفاصلة العائمة

ربما تم تحويل استدلال النموذج من FP32 (فاصلة عائمة 32 بت) إلى FP16 (فاصلة عائمة 16 بت):

• دقة حسابات FP16 هي نصف دقة FP32، كما أن استهلاك وحدة معالجة الرسومات (GPU) ينخفض بشكل كبير.
• انخفاض الدقة يؤدي إلى تدرجات ألوان أقل سلاسة مما كانت عليه، وينعكس ذلك في النهاية على انخفاض حجم ملف PNG.

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

استنتاج رئيسي: هذا إجراء اتخذته جوجل للموازنة بين عدد المستخدمين وجودة الخدمة خلال فترة نقص طاقة إنتاج TPU. الدقة (عدد البكسلات) ثابتة، لكن كثافة المعلومات (كمية المعلومات الفريدة التي يحملها كل بكسل) قد انخفضت. لا يمكن للمستخدمين استعادة جودة الـ 30 ميجابايت السابقة عبر معلمات الواجهة.

🎯 نصيحة للتعامل: إذا كانت متطلباتك لجودة تفاصيل الصورة عالية جداً، يمكنك تجربة: 1) استخدام معلمة compressionQuality=100 في Vertex AI؛ 2) التأكيد على متطلبات التفاصيل والأنسجة في الموجه (Prompt)؛ 3) توليد صورة بدقة 2K ثم تكبيرها إلى 4K باستخدام نموذج فائق الدقة (Super-Resolution).
من خلال APIYI (apiyi.com)، يمكنك اختبار تأثير مجموعات مختلفة من المعلمات في وقت واحد للعثور على التوازن الأمثل بين الجودة والحجم.

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

ملخص

النقاط الجوهرية للتحكم في تنسيق مخرجات الصور لنموذج Nano Banana 2 عبر API:

1. AI Studio لا يدعم التحكم في التنسيق من جانب الخادم: يجب عليك فك ترميز base64 من جانب العميل ثم استخدام مكتبة Pillow لحفظ الصورة بصيغة PNG صراحةً، مع ضرورة التحقق من البايتات السحرية (magic bytes) للتأكد من التنسيق الفعلي.
2. Vertex AI يدعم outputMimeType: يمكنك تحديد image/png أو image/jpeg مباشرة في الطلب، بالإضافة إلى التحكم في جودة ضغط JPEG.
3. تقليص حجم صور 4K يعود لتعديلات في القوة الحوسبية: انخفاض الحجم من 30 ميجابايت إلى 8 ميجابايت ليس بسبب تغيير التنسيق، بل لأن جوجل قللت خطوات الاستدلال ودقة الفاصلة العائمة مما أدى إلى خفض إنتروبيا المعلومات، ولا يمكن للمستخدم استعادة الجودة عبر المعلمات.

بعد فهم هذه الآليات الأساسية، يمكنك اختيار استراتيجية الحفظ الأكثر ملاءمة لاحتياجاتك الفعلية.

نوصي باستخدام APIYI (apiyi.com) للتحقق السريع من تأثير التنسيقات والمعلمات المختلفة، حيث توفر المنصة رصيداً مجانياً وواجهة موحدة، وتدعم طرق استدعاء متعددة لنموذج Nano Banana 2.

📚 المراجع

1. وثائق تطوير توليد الصور في Gemini: مرجع API الرسمي، يتضمن شرح معلمات ImageConfig.

   • الرابط: ai.google.dev/gemini-api/docs/image-generation
   • ملاحظة: لفهم المعلمات والقيود عند الاستدعاء عبر AI Studio.

2. مرجع Vertex AI ImageOutputOptions: الوثائق الكاملة لمعلمات التحكم في التنسيق الخاصة بـ Vertex AI.

   • الرابط: docs.cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/Shared.Types/ImageOutputOptions
   • ملاحظة: تتضمن شرحاً تفصيلياً لـ mimeType و compressionQuality.

3. GitHub Issue #1824 – عدم تطابق نوع MIME: تقرير عن خطأ برمجي حيث يدعي الـ API إرجاع PNG بينما يعيد JPEG فعلياً.

   • الرابط: github.com/googleapis/python-genai/issues/1824
   • ملاحظة: لمعرفة التفاصيل التقنية لهذا الخطأ المعروف والحلول المؤقتة.

4. مركز وثائق APIYI: دليل التحكم في التنسيق عند استدعاء Nano Banana 2 عبر الواجهة الموحدة.

   • الرابط: docs.apiyi.com
   • ملاحظة: مناسب للمطورين الذين يحتاجون إلى تبسيط سير عمل معالجة التنسيقات.

المؤلف: فريق APIYI التقني
النقاش التقني: نرحب بمشاركتكم في قسم التعليقات، ولمزيد من المعلومات يمكنكم زيارة مركز وثائق APIYI على docs.apiyi.com.