حل 6 أسباب شائعة وإصلاحات لخطأ نموذج صورة Gemini “required oneof field data

title: "حل خطأ 400 'required oneof field data must have one initialized field' عند استدعاء نماذج Gemini للصور"
description: "دليل مفصل لستة أسباب شائعة لخطأ 400 عند استخدام gemini-3.1-flash-image-preview و gemini-3.0-pro-image، مع حلول عملية لكل حالة."
date: 2024-12-20
category: "برمجة"
tags: ["Gemini", "Google AI", "نماذج لغة كبيرة", "توليد الصور", "استكشاف الأخطاء وإصلاحها"]

عند استدعاء gemini-3.1-flash-image-preview (Nano Banana 2) أو gemini-3.0-pro-image (Nano Banana Pro) لتوليد الصور، يواجه العديد من المطورين هذا الخطأ المحير 400:

{
  "status_code": 400,
  "error": {
    "message": "* GenerateContentRequest.contents[0].parts[2].data: required oneof field 'data' must have one initialized field",
    "type": "upstream_error",
    "code": 400
  }
}

المعنى الأساسي لهذا الخطأ هو: حقل data في أحد عناصر parts في جسم الطلب الذي أرسلته فارغ أو تنسيقه غير صحيح. خطأ 400 هو خطأ في معاملات العميل، ولن يتم إصلاحه تلقائيًا، ويجب تصحيح الكود لحله.

يستعرض هذا المقال 6 أسباب شائعة تؤدي إلى هذا الخطأ، مع مقارنة بين الكود الخاطئ والصحيح لكل حالة، لمساعدتك في تحديد المشكلة وإصلاحها بسرعة.

القيمة الأساسية: بعد قراءة هذا المقال، يمكنك استخدام رقم الفهرس parts[N] في رسالة الخطأ لتحديد موقع المشكلة بدقة، والتحقق من الأسباب الستة واحدًا تلو الآخر، وعادةً ما يمكنك إصلاح المشكلة في غضون 5 دقائق.

تحليل أساسي لخطأ "required oneof field data" في نموذج الصور Gemini

تفسير بنية رسالة الخطأ في نموذج صور Gemini

دعنا نحلل بنية رسالة الخطأ، فهذا هو المفتاح لتحديد المشكلة:

GenerateContentRequest.contents[0].parts[2].data
                       ^^^^^^^^     ^^^^^^^^
                       │            │
                       │            └── الـ part الثالث (الترقيم يبدأ من 0)
                       └── كتلة المحتوى الأولى

• contents[0]: تشير إلى كائن المحتوى الأول في جسم الطلب الخاص بك
• parts[2]: تشير إلى العنصر الثالث في مصفوفة الـ parts الخاصة بهذا المحتوى
• data: حقل البيانات لهذا الـ part فارغ أو لم يتم تهيئته بشكل صحيح

منهجية التحقق: تحقق مباشرةً من العنصر [2] في مصفوفة parts الخاص بالعنصر [0] في مصفوفة contents في الكود الخاص بك، لترى ما الذي تم تمريره بالضبط.

6 أسباب شائعة لأخطاء نموذج Gemini للصور وطرق إصلاحها

السبب 1: وجود كائنات فارغة أو سلاسل نصية فارغة في parts

هذا هو السبب الأكثر شيوعًا. يحتوي مصفوفة parts في الطلب على عناصر فارغة مثل {} أو null أو سلسلة نصية فارغة "".

كود خاطئ:

# ❌ يحتوي parts على كائن فارغ
payload = {
    "contents": [{
        "parts": [
            {"text": "Generate a cat image"},
            {},                              # ← كائن فارغ، يؤدي إلى خطأ
            {"text": "in watercolor style"}
        ]
    }]
}

كود صحيح:

# ✅ كل جزء يحتوي على محتوى صالح
payload = {
    "contents": [{
        "parts": [
            {"text": "Generate a cat image in watercolor style"}
        ]
    }]
}

نقاط الإصلاح: قم بدمج النص في جزء text واحد، أو تأكد من أن كل جزء يحتوي على حقول text أو inlineData صالحة.

السبب 2: بيانات base64 للصورة فارغة أو ذات تنسيق خاطئ

عند إرسال طلب تحويل صورة إلى صورة (image-to-image)، قد تكون بيانات base64 في inlineData فارغة أو تالفة أو ذات تنسيق غير صحيح.

كود خاطئ:

# ❌ بيانات base64 تحتوي على بادئة data URI
payload = {
    "contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/png",
                    "data": "data:image/png;base64,iVBORw0KGgo..."  # ← لا ينبغي أن تحتوي على البادئة
                }
            },
            {"text": "Change the background to blue"}
        ]
    }]
}

# ❌ بيانات base64 عبارة عن سلسلة نصية فارغة
"inlineData": {
    "mimeType": "image/jpeg",
    "data": ""          # ← بيانات فارغة، تؤدي مباشرة إلى خطأ
}

كود صحيح:

import base64
import pathlib

# ✅ قراءة الصورة بشكل صحيح وتحويلها إلى base64 خالص
image_bytes = pathlib.Path("input.png").read_bytes()
image_b64 = base64.b64encode(image_bytes).decode("utf-8")

payload = {
    "contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/png",
                    "data": image_b64       # ← سلسلة base64 خالصة، بدون بادئة
                }
            },
            {"text": "Change the background to blue"}
        ]
    }]
}

نقاط الإصلاح:

• حقل data يقبل فقط سلسلة base64 خالصة، ولا يجب أن يحتوي على البادئة data:image/png;base64,
• تأكد من وجود ملف الصورة فعليًا وتمت قراءته بنجاح، وتجنب تمرير سلسلة نصية فارغة
• يجب أن يتطابق mimeType مع تنسيق الصورة الفعلي (image/png، image/jpeg، image/webp)

السبب 3: لم يتم تحويل كائن File بشكل صحيح إلى مرجع محتوى

بعد تحميل ملف باستخدام Files API في Google GenAI SDK، قد يؤدي تمرير كائن File مباشرة إلى contents إلى فشل SDK في التحويل بشكل صحيح.

كود خاطئ:

from google import genai

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

# تحميل الملف
file = client.files.upload(file="photo.png")

# ❌ في بعض إصدارات SDK، قد يفشل تمرير كائن File مباشرة
response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Edit this image", file]    # ← قد لا يتم تحويل كائن File تلقائيًا
)

كود صحيح:

from google import genai
from google.genai import types

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

# تحميل الملف
file = client.files.upload(file="photo.png")

# ✅ الطريقة 1: إنشاء مرجع ملف يدويًا
response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=[
        types.Content(parts=[
            types.Part(file_data=types.FileData(file_uri=file.uri, mime_type=file.mime_type)),
            types.Part(text="Edit this image: change background to sunset")
        ])
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"]
    )
)

# ✅ الطريقة 2: استخدام inlineData لتمرير base64 مباشرة (أكثر موثوقية)
import base64, pathlib

image_b64 = base64.b64encode(pathlib.Path("photo.png").read_bytes()).decode()

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=[
        types.Content(parts=[
            types.Part(inline_data=types.Blob(mime_type="image/png", data=image_b64)),
            types.Part(text="Edit this image: change background to sunset")
        ])
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"]
    )
)

نقاط الإصلاح: يوصى باستخدام طريقة inlineData + base64 لتمرير بيانات الصورة مباشرة، فهي أكثر استقرارًا وموثوقية من Files API.

السبب 4: يحتوي سجل المحادثة متعدد الجولات على محتوى فارغ

عند تحرير الصور في محادثة متعددة الجولات، إذا لم تتم معالجة استجابة الجولة السابقة بشكل صحيح، فقد يحتوي سجل المحادثة على كتل محتوى فارغة.

كود خاطئ:

# ❌ يحتوي سجل المحادثة على أجزاء فارغة
history = [
    {"role": "user", "parts": [{"text": "Generate a logo"}]},
    {"role": "model", "parts": []},        # ← أجزاء فارغة، تؤدي إلى خطأ
    {"role": "user", "parts": [{"text": "Make it blue"}]}
]

payload = {"contents": history}

كود صحيح:

# ✅ تصفية كتل المحتوى الفارغة
history = [
    {"role": "user", "parts": [{"text": "Generate a logo"}]},
    {"role": "model", "parts": [{"text": "Here is the logo I generated."}]},
    {"role": "user", "parts": [{"text": "Make it blue"}]}
]

# تصفية آمنة: إزالة السجلات التي تكون أجزاؤها فارغة
clean_history = [msg for msg in history if msg.get("parts") and len(msg["parts"]) > 0]

payload = {"contents": clean_history}

نقاط الإصلاح: قبل إرسال الطلب، قم باجتياز مصفوفة contents وقم بتصفية جميع العناصر التي تكون parts عبارة عن قائمة فارغة أو تحتوي على كائنات فارغة.

السبب 5: خطأ في حالة أحرف أسماء حقول JSON في طلب REST API

تستخدم أسماء حقول JSON في Gemini API camelCase (تسمية الجمل)، وهي حساسة لحالة الأحرف. يؤدي الخطأ في كتابة اسم الحقل إلى تجاهل هذا الحقل، مما يعادل تمرير بيانات فارغة.

كود خاطئ:

# ❌ استخدام snake_case في REST API (أسلوب Python SDK)
payload = {
    "contents": [{
        "parts": [{
            "inline_data": {           # ← يجب أن يكون inlineData
                "mime_type": "image/png",   # ← يجب أن يكون mimeType
                "data": image_b64
            }
        }]
    }],
    "generation_config": {             # ← يجب أن يكون generationConfig
        "response_modalities": ["IMAGE"]   # ← يجب أن يكون responseModalities
    }
}

كود صحيح:

# ✅ REST API تستخدم camelCase
payload = {
    "contents": [{
        "parts": [{
            "inlineData": {
                "mimeType": "image/png",
                "data": image_b64
            }
        }]
    }],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {
            "aspectRatio": "1:1",
            "imageSize": "2K"
        }
    }
}

🎯 ملاحظة مهمة: Python SDK (google-genai) يستخدم snake_case (مثل inline_data)، بينما الاستدعاء المباشر لـ REST API يستخدم camelCase (مثل inlineData). عند الاستدعاء عبر منصات وسيطة مثل APIYI apiyi.com، يتم استخدام تنسيق REST API، ويجب استخدام camelCase.

السبب 6: تنسيق الصورة غير مدعوم أو الملف تالف

بيانات base64 للصورة موجودة، لكن تنسيق الصورة نفسه غير مدعوم أو أن الملف تالف.

تنسيقات الإدخال المدعومة في نموذج Gemini للصور:

طريقة التحقق:

import base64

# التحقق مما إذا كانت بيانات base64 صالحة
def validate_image_data(b64_string, mime_type):
    # 1. التحقق من عدم كونها فارغة
    if not b64_string:
        print("ERROR: base64 data is empty")
        return False

    # 2. التحقق مما إذا كانت تحتوي على بادئة data URI
    if b64_string.startswith("data:"):
        print("ERROR: Remove 'data:image/...;base64,' prefix")
        return False

    # 3. التحقق مما إذا كان يمكن فك تشفير base64
    try:
        decoded = base64.b64decode(b64_string)
        print(f"OK: Decoded size = {len(decoded)} bytes")
    except Exception as e:
        print(f"ERROR: Invalid base64 - {e}")
        return False

    # 4. التحقق مما إذا كان mimeType مدعومًا
    supported = ["image/png", "image/jpeg", "image/webp", "image/gif"]
    if mime_type not in supported:
        print(f"ERROR: Unsupported mimeType '{mime_type}'")
        return False

    print("PASS: Image data is valid")
    return True

💡 اقتراح: إضافة دالة التحقق من البيانات قبل إرسال الطلب يمكن أن تكتشف معظم مشاكل التنسيق مسبقًا. ينطبق هذا أيضًا عند الاستدعاء عبر منصة APIYI apiyi.com.

قائمة فحص كاملة لأخطاء نموذج الصور Gemini

عند مواجهتك خطأ required oneof field 'data'، اتبع هذه القائمة خطوة بخطوة للفحص:

إصلاح سريع: إذا واجهت هذا الخطأ بشكل متكرر أثناء مرحلة التطوير، ننصح بإضافة دالة validate_payload() قبل إرسال الطلب، للتحقق تلقائيًا من صحة كل عنصر في مصفوفة parts. عند استدعاء نموذج صور Gemini عبر منصة APIYI apiyi.com، يكون تنسيق الطلب مطابقًا تمامًا لواجهة REST API الرسمية، وتنطق طرق الفحص المذكورة أعلاه أيضًا.

أخطاء نموذج الصور Gemini: تنسيق الطلب الصحيح

التنسيق الصحيح لتحويل النص إلى صورة

import requests, base64

API_KEY = "your-apiyi-api-key"
ENDPOINT = "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent"

# ✅ التنسيق الصحيح الأبسط
payload = {
    "contents": [{
        "parts": [
            {"text": "A cute orange cat sitting on a windowsill, watercolor style, 4K"}
        ]
    }],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {
            "aspectRatio": "1:1",
            "imageSize": "2K"
        }
    }
}

response = requests.post(
    ENDPOINT,
    headers={"Content-Type": "application/json", "x-goog-api-key": API_KEY},
    json=payload,
    timeout=120
)

result = response.json()
image_data = result["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(image_data))

التنسيق الصحيح لتحويل صورة إلى صورة

import requests
import base64
import pathlib

API_KEY = "your-apiyi-api-key"
ENDPOINT = "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent"

# قراءة الصورة الأصلية وتحويلها إلى base64 خالص
image_path = pathlib.Path("input_photo.png")
if not image_path.exists():
    raise FileNotFoundError(f"Image not found: {image_path}")

image_bytes = image_path.read_bytes()
image_b64 = base64.b64encode(image_bytes).decode("utf-8")

# التحقق من البيانات
assert len(image_b64) > 0, "Base64 data is empty"
assert not image_b64.startswith("data:"), "Remove data URI prefix"

# ✅ تنسيق الطلب الصحيح لتحويل صورة إلى صورة
payload = {
    "contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/png",
                    "data": image_b64
                }
            },
            {
                "text": "Change the background to a sunset beach scene, keep the subject unchanged"
            }
        ]
    }],
    "generationConfig": {
        "responseModalities": ["IMAGE"],
        "imageConfig": {
            "aspectRatio": "1:1",
            "imageSize": "2K"
        }
    }
}

response = requests.post(
    ENDPOINT,
    headers={"Content-Type": "application/json", "x-goog-api-key": API_KEY},
    json=payload,
    timeout=120
)

if response.status_code == 200:
    result = response.json()
    output_data = result["candidates"][0]["content"]["parts"][0]["inlineData"]["data"]
    with open("output_edited.png", "wb") as f:
        f.write(base64.b64decode(output_data))
    print("Success! Image saved.")
else:
    print(f"Error {response.status_code}: {response.text}")

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

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

الخلاصة

النقاط الأساسية لخطأ required oneof field 'data' في نموذج صور Gemini:

1. السبب الجذري: وجود عناصر فارغة، أو بيانات فارغة، أو عناصر ذات تنسيق خاطئ في مصفوفة parts.
2. طريقة التحديد: تحديد الموقع في الكود مباشرةً باستخدام رقم الفهرس parts[N] الموجود في رسالة الخطأ.
3. السبب الأكثر شيوعاً: كائن فارغ {}، أو بيانات base64 تحتوي على بادئة data:، أو خطأ في حالة أحرف (Case) اسم حقل JSON.
4. واجهة REST API تستخدم camelCase إلزامياً: inlineData (وليس inline_data)، mimeType (وليس mime_type).
5. إجراءات الوقاية: إضافة دالة للتحقق من payload قبل الإرسال، للكشف التلقائي عن العناصر الفارغة ومشاكل التنسيق.

يوصى باستخدام منصة APIYI apiyi.com لاستدعاء نموذج صور Gemini لأغراض التطوير والتصحيح، حيث أن خدمة Nano Banana 2 تتكلف $0.045 لكل استدعاء، مما يجعل تكلفة التصحيح منخفضة جداً، كما أن تنسيق الواجهة متوافق تماماً مع REST API الرسمي.

📚 المراجع

1. الوثائق الرسمية لتوليد الصور في Gemini API: تنسيق الطلب الكامل وشرح المعاملات.

   • الرابط: ai.google.dev/gemini-api/docs/image-generation
   • الشرح: يتضمن تنسيق الطلب القياسي لتحويل النص إلى صورة وتحويل الصورة إلى صورة.

2. دليل استكشاف الأخطاء وإصلاحها في Gemini API: رموز الأخطاء الرسمية واقتراحات الإصلاح.

   • الرابط: ai.google.dev/gemini-api/docs/troubleshooting
   • الشرح: يغطي طرق استكشاف الأخطاء الشائعة مثل 400 و429 و500.

3. GitHub Issue: مناقشة خطأ required oneof field data: تقارير المجتمع وحلول الإصلاح.

   • الرابط: github.com/google-gemini/cookbook/issues/786
   • الشرح: يتضمن تحليلاً مفصلاً وحلاً بديلاً (workaround) لهذا الخطأ الناتج عن تمرير كائن File.

4. وثائق دمج APIYI Nano Banana 2: دليل كامل لاستدعاء نموذج صور Gemini عبر منصة APIYI.

   • الرابط: docs.apiyi.com/en/api-capabilities/nano-banana-2-image
   • الشرح: يتضمن أمثلة على تنسيق الطلب الصحيح وإجابات للأسئلة الشائعة.

المؤلف: فريق APIYI التقني
التواصل التقني: إذا واجهت مشكلة في استدعاء Gemini API، نرحب بك لزيارة مركز الوثائق APIYI docs.apiyi.com لمشاهدة المزيد من أدلة استكشاف الأخطاء.