Lösung für Gemini-Bildmodellfehler „required oneof field data“: 6 häufige Ursachen und Reparaturmethoden

Autorenhinweis: Detaillierte Erklärung der 6 häufigsten Ursachen und entsprechenden Lösungen für den Fehler "required oneof field data must have one initialized field 400" beim Aufruf von Gemini-Bildmodellen wie gemini-3.1-flash-image-preview.

Beim Aufruf von gemini-3.1-flash-image-preview (Nano Banana 2) oder gemini-3.0-pro-image (Nano Banana Pro) zur Bilderzeugung stoßen viele Entwickler auf diesen verwirrenden 400-Fehler:

{
  "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
  }
}

Die Kernbedeutung dieser Fehlermeldung ist: In Ihrem Anfrage-Body ist das data-Feld eines parts-Elements leer oder falsch formatiert. Der 400-Fehler ist ein Client-seitiger Anfrageparameterfehler, der sich nicht von selbst behebt – Sie müssen Ihren Code korrigieren.

Dieser Artikel fasst die 6 häufigsten Ursachen für diesen Fehler zusammen, jeweils mit einem Vergleich von fehlerhaftem und korrigiertem Code, um Ihnen bei der schnellen Identifizierung und Behebung des Problems zu helfen.

Kernnutzen: Nach dem Lesen dieses Artikels können Sie anhand des Index parts[N] in der Fehlermeldung die Problemstelle genau lokalisieren und die 6 Ursachen nacheinander überprüfen. In der Regel ist das Problem innerhalb von 5 Minuten behoben.

Kernanalyse des Fehlers "required oneof field data" bei Gemini-Bildmodellen

Strukturanalyse der Gemini-Bildmodell-Fehlermeldung

Zuerst die Struktur der Fehlermeldung entschlüsseln – das ist der Schlüssel zur Problemidentifikation:

GenerateContentRequest.contents[0].parts[2].data
                       ^^^^^^^^     ^^^^^^^^
                       │            │
                       │            └── Dritter Part (Index beginnt bei 0)
                       └── Erster Content-Block

• contents[0]: Verweist auf das erste Content-Objekt in deinem Request-Body
• parts[2]: Verweist auf das dritte Part-Element innerhalb dieses Contents
• data: Das Datenfeld dieses Parts ist leer oder nicht korrekt initialisiert

Vorgehensweise: Überprüfe direkt das Element parts[2] im contents[0]-Array deines Codes, um zu sehen, was tatsächlich übergeben wird.

6 Häufige Ursachen und Lösungen für den Gemini-Bildmodell-Fehler

Ursache 1: Leere Objekte oder Zeichenketten in parts

Das ist die häufigste Ursache. Das parts-Array der Anfrage enthält leere Werte wie {}, null oder leere Zeichenketten "".

Fehlerhafter Code:

# ❌ parts enthält leeres Objekt
payload = {
    "contents": [{
        "parts": [
            {"text": "Erzeuge ein Katzenbild"},
            {},                              # ← Leeres Objekt, löst Fehler aus
            {"text": "im Aquarellstil"}
        ]
    }]
}

Korrekter Code:

# ✅ Jedes Part enthält gültigen Inhalt
payload = {
    "contents": [{
        "parts": [
            {"text": "Erzeuge ein Katzenbild im Aquarellstil"}
        ]
    }]
}

Lösungshinweis: Fasse Texte in einem text-Part zusammen oder stelle sicher, dass jedes Part ein gültiges text– oder inlineData-Feld enthält.

Ursache 2: Base64-Bilddaten sind leer oder fehlerhaft

Bei Bild-zu-Bild-Anfragen (image-to-image) können die Base64-Daten in inlineData leer, beschädigt oder falsch formatiert sein.

Fehlerhafter Code:

# ❌ base64-Daten enthalten data URI-Präfix
payload = {
    "contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/png",
                    "data": "data:image/png;base64,iVBORw0KGgo..."  # ← Sollte kein Präfix enthalten
                }
            },
            {"text": "Ändere den Hintergrund zu blau"}
        ]
    }]
}

# ❌ base64-Daten sind leer
"inlineData": {
    "mimeType": "image/jpeg",
    "data": ""          # ← Leere Daten, löst direkt Fehler aus
}

Korrekter Code:

import base64
import pathlib

# ✅ Korrektes Einlesen des Bildes und Konvertierung in reinen base64-String
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       # ← Reiner base64-String, ohne Präfix
                }
            },
            {"text": "Ändere den Hintergrund zu blau"}
        ]
    }]
}

Lösungshinweis:

• Das data-Feld akzeptiert nur reinen base64-String, ohne data:image/png;base64,-Präfix
• Stelle sicher, dass die Bilddatei existiert und erfolgreich gelesen wird, um leere Strings zu vermeiden
• mimeType muss mit dem tatsächlichen Bildformat übereinstimmen (image/png, image/jpeg, image/webp)

Ursache 3: File-Objekt nicht korrekt in Inhaltsreferenz umgewandelt

Nach dem Hochladen einer Datei über die Google GenAI SDK Files API kann die direkte Übergabe des File-Objekts an contents dazu führen, dass das SDK es nicht korrekt konvertiert.

Fehlerhafter Code:

from google import genai

client = genai.Client(api_key="DEIN_SCHLÜSSEL")

# Datei hochladen
file = client.files.upload(file="photo.png")

# ❌ In manchen SDK-Versionen schlägt die direkte Übergabe des File-Objekts fehl
response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Bearbeite dieses Bild", file]    # ← File-Objekt wird möglicherweise nicht automatisch konvertiert
)

Korrekter Code:

from google import genai
from google.genai import types

client = genai.Client(api_key="DEIN_SCHLÜSSEL")

# Datei hochladen
file = client.files.upload(file="photo.png")

# ✅ Methode 1: Manuelle Erstellung der Dateireferenz
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="Bearbeite dieses Bild: Hintergrund zu Sonnenuntergang ändern")
        ])
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"]
    )
)

# ✅ Methode 2: Stattdessen inlineData mit base64 verwenden (zuverlässiger)
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="Bearbeite dieses Bild: Hintergrund zu Sonnenuntergang ändern")
        ])
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"]
    )
)

Lösungshinweis: Die Verwendung von inlineData + base64 zur direkten Übergabe von Bilddaten ist stabiler und zuverlässiger als die Files API.

Ursache 4: Leere Inhalte im Mehrrunden-Chatverlauf

Bei der Bildbearbeitung in Mehrrunden-Dialogen können leere Content-Blöcke in den Chatverlauf gelangen, wenn die Antwort der vorherigen Runde nicht korrekt verarbeitet wurde.

Fehlerhafter Code:

# ❌ Chatverlauf enthält leere parts
history = [
    {"role": "user", "parts": [{"text": "Erzeuge ein Logo"}]},
    {"role": "model", "parts": []},        # ← Leere parts, lösen Fehler aus
    {"role": "user", "parts": [{"text": "Mache es blau"}]}
]

payload = {"contents": history}

Korrekter Code:

# ✅ Leere Content-Blöcke herausfiltern
history = [
    {"role": "user", "parts": [{"text": "Erzeuge ein Logo"}]},
    {"role": "model", "parts": [{"text": "Hier ist das von mir erzeugte Logo."}]},
    {"role": "user", "parts": [{"text": "Mache es blau"}]}
]

# Sicherheitsfilter: Entferne Einträge mit leeren parts
clean_history = [msg for msg in history if msg.get("parts") and len(msg["parts"]) > 0]

payload = {"contents": clean_history}

Lösungshinweis: Vor dem Senden der Anfrage das contents-Array durchlaufen und alle Elemente herausfiltern, deren parts-Liste leer ist oder leere Objekte enthält.

Ursache 5: Falsche Groß-/Kleinschreibung von JSON-Feldnamen in REST API-Anfragen

Die JSON-Feldnamen der Gemini API verwenden camelCase (Binnenmajuskel) und sind case-sensitive. Falsch geschriebene Feldnamen werden ignoriert, was dem Übergeben leerer Daten entspricht.

Fehlerhafter Code:

# ❌ REST API verwendet snake_case (Python SDK-Stil)
payload = {
    "contents": [{
        "parts": [{
            "inline_data": {           # ← Sollte inlineData sein
                "mime_type": "image/png",   # ← Sollte mimeType sein
                "data": image_b64
            }
        }]
    }],
    "generation_config": {             # ← Sollte generationConfig sein
        "response_modalities": ["IMAGE"]   # ← Sollte responseModalities sein
    }
}

Korrekter Code:

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

🎯 Wichtiger Hinweis: Das Python SDK (google-genai) verwendet snake_case (z.B. inline_data), während direkte REST API-Aufrufe camelCase (z.B. inlineData) verwenden. Bei Aufrufen über API-Proxy-Dienste wie APIYI (apiyi.com) wird das REST API-Format verwendet, daher muss camelCase genutzt werden.

Ursache 6: Bildformat nicht unterstützt oder Datei beschädigt

Die übergebenen Bilddaten enthalten zwar Base64-Daten, aber das Bildformat selbst wird nicht unterstützt oder die Datei ist beschädigt.

Von Gemini-Bildmodellen unterstützte Eingabeformate:

Prüfungsmethode:

import base64

# Prüfen, ob base64-Daten gültig sind
def validate_image_data(b64_string, mime_type):
    # 1. Prüfen, ob leer
    if not b64_string:
        print("FEHLER: base64-Daten sind leer")
        return False

    # 2. Prüfen, ob data URI-Präfix enthalten ist
    if b64_string.startswith("data:"):
        print("FEHLER: Entferne 'data:image/...;base64,'-Präfix")
        return False

    # 3. Prüfen, ob base64 dekodierbar ist
    try:
        decoded = base64.b64decode(b64_string)
        print(f"OK: Dekodierte Größe = {len(decoded)} Bytes")
    except Exception as e:
        print(f"FEHLER: Ungültiges base64 - {e}")
        return False

    # 4. Prüfen, ob mimeType unterstützt wird
    supported = ["image/png", "image/jpeg", "image/webp", "image/gif"]
    if mime_type not in supported:
        print(f"FEHLER: Nicht unterstütztes mimeType '{mime_type}'")
        return False

    print("BESTANDEN: Bilddaten sind gültig")
    return True

💡 Empfehlung: Eine Datenvalidierungsfunktion vor dem Senden der Anfrage kann die meisten Formatprobleme frühzeitig erkennen. Dies gilt auch für Aufrufe über die APIYI-Plattform (apiyi.com).

Vollständige Checkliste zur Fehlerbehebung bei Gemini-Bildmodellen

Wenn Sie auf den Fehler required oneof field 'data' stoßen, gehen Sie diese Checkliste Punkt für Punkt durch:

Schnellkorrektur: Wenn Sie diesen Fehler während der Entwicklung häufig erhalten, empfehlen wir, vor dem Senden der Anfrage eine validate_payload()-Funktion hinzuzufügen, die automatisch jedes Element im parts-Array auf Gültigkeit prüft. Wenn Sie das Gemini-Bildmodell über die APIYI-Plattform apiyi.com aufrufen, ist das Anfrageformat mit der offiziellen REST API identisch, und die oben genannten Fehlerbehebungsmethoden gelten ebenfalls.

Gemini-Bildmodell-Fehler – Korrektes Anfrageformat als Referenz

Reine Text-zu-Bild-Erzeugung (Text-to-Image) – Korrektes Format

import requests, base64

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

# ✅ Minimales korrektes Format
payload = {
    "contents": [{
        "parts": [
            {"text": "Eine niedliche orange Katze sitzt auf einer Fensterbank, Aquarellstil, 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))

Bild-zu-Bild-Erzeugung (Image-to-Image) – Korrektes Format

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"

# Quellbild lesen und in reines base64 konvertieren
image_path = pathlib.Path("input_photo.png")
if not image_path.exists():
    raise FileNotFoundError(f"Bild nicht gefunden: {image_path}")

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

# Daten validieren
assert len(image_b64) > 0, "Base64-Daten sind leer"
assert not image_b64.startswith("data:"), "Data-URI-Präfix entfernen"

# ✅ Korrektes Anfrageformat für Bild-zu-Bild
payload = {
    "contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/png",
                    "data": image_b64
                }
            },
            {
                "text": "Ändere den Hintergrund zu einer Sonnenuntergangsstrandszene, behalte das Hauptmotiv unverändert"
            }
        ]
    }],
    "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("Erfolg! Bild gespeichert.")
else:
    print(f"Fehler {response.status_code}: {response.text}")

Empfehlung: Für Text-zu-Bild-Szenarien starte mit dem minimalen Format, bestätige, dass es funktioniert, und füge dann schrittweise Parameter hinzu. Der Aufruf von Nano Banana 2 über die APIYI-Plattform apiyi.com erfolgt nutzungsbasiert zu $0,045 pro Aufruf, die Kosten in der Debug-Phase sind sehr gering.

Häufig gestellte Fragen

Zusammenfassung

Die Kernpunkte des Gemini-Bildmodell-Fehlers required oneof field 'data':

1. Ursache: Das parts-Array enthält leere Objekte, leere Daten oder falsch formatierte Elemente.
2. Lokalisierung: Nutzen Sie die Indexnummer parts[N] aus der Fehlermeldung, um direkt die entsprechende Stelle im Code zu finden.
3. Häufigste Ursachen: Leeres Objekt {}, Base64-Daten mit data:-Präfix, falsche Groß-/Kleinschreibung bei JSON-Feldnamen.
4. REST API erfordert camelCase: inlineData (nicht inline_data), mimeType (nicht mime_type).
5. Vorbeugung: Vor dem Senden eine Payload-Validierungsfunktion hinzufügen, um leere Elemente und Formatprobleme automatisch zu erkennen.

Empfohlen wird die Nutzung der APIYI-Plattform apiyi.com für die Entwicklung und das Debugging mit dem Gemini-Bildmodell. Nano Banana 2 kostet nur $0,045 pro Aufruf, was die Debugging-Kosten extrem niedrig hält. Das Schnittstellenformat ist vollständig kompatibel mit der offiziellen REST API.

📚 Referenzen

1. Offizielle Gemini API Dokumentation zur Bilderzeugung: Vollständige Anfrageformate und Parameterbeschreibungen.

   • Link: ai.google.dev/gemini-api/docs/image-generation
   • Beschreibung: Enthält Standardanfrageformate für Text-zu-Bild und Bild-zu-Bild.

2. Gemini API Fehlerbehebungsleitfaden: Offizielle Fehlercodes und Lösungsvorschläge.

   • Link: ai.google.dev/gemini-api/docs/troubleshooting
   • Beschreibung: Deckt häufige Fehler wie 400, 429, 500 und deren Behebung ab.

3. GitHub Issue: Diskussion zum Fehler required oneof field data: Community-Berichte und Lösungsansätze.

   • Link: github.com/google-gemini/cookbook/issues/786
   • Beschreibung: Enthält eine detaillierte Analyse und Workarounds für diesen Fehler, der durch die Übergabe von File-Objekten verursacht wird.

4. APIYI Nano Banana 2 Integrationsdokumentation: Vollständige Anleitung zur Nutzung des Gemini-Bildmodells über die APIYI-Plattform.

   • Link: docs.apiyi.com/en/api-capabilities/nano-banana-2-image
   • Beschreibung: Enthält korrekte Anfrageformat-Beispiele und Antworten auf häufig gestellte Fragen.

Autor: APIYI Technikteam
Technischer Austausch: Bei Problemen mit Gemini API-Aufrufen besuchen Sie bitte das APIYI-Dokumentationszentrum unter docs.apiyi.com für weitere Fehlerbehebungsleitfäden.