Menyelesaikan 6 Penyebab Umum dan Metode Perbaikan untuk Kesalahan Model Gambar Gemini “required oneof field data

Catatan Penulis: Penjelasan mendalam tentang 6 penyebab umum dan solusi perbaikan terkait error 400 "required oneof field data must have one initialized field" saat memanggil model gambar Gemini seperti gemini-3.1-flash-image-preview.

Saat memanggil gemini-3.1-flash-image-preview (Nano Banana 2) atau gemini-3.0-pro-image (Nano Banana Pro) untuk membuat gambar, banyak pengembang mengalami error 400 yang membingungkan ini:

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

Inti dari error ini adalah: di dalam request body Anda, elemen parts tertentu memiliki field data yang kosong atau formatnya salah. Error 400 termasuk kesalahan parameter klien, tidak akan pulih otomatis, dan harus diperbaiki di kode.

Artikel ini merangkum 6 penyebab umum yang memicu error ini, masing-masing dilengkapi dengan perbandingan kode salah vs kode benar, untuk membantu Anda menemukan dan memperbaiki masalah dengan cepat.

Nilai inti: Setelah membaca artikel ini, Anda dapat menggunakan nomor indeks parts[N] dari pesan error untuk secara tepat menemukan lokasi masalah, lalu memeriksa satu per satu dari 6 penyebab, biasanya dapat diperbaiki dalam 5 menit.

Analisis Inti Error "required oneof field data" pada Model Gambar Gemini

Interpretasi Struktur Pesan Error Model Gambar Gemini

Mari kita uraikan struktur pesan error terlebih dahulu, ini adalah kunci untuk menemukan masalah:

GenerateContentRequest.contents[0].parts[2].data
                       ^^^^^^^^     ^^^^^^^^
                       │            │
                       │            └── Part ke-3 (indeks mulai dari 0)
                       └── Blok content ke-1

• contents[0]: Menunjuk ke objek content pertama di request body Anda
• parts[2]: Menunjuk ke elemen part ke-3 di dalam content tersebut
• data: Field data dari part tersebut kosong atau tidak diinisialisasi dengan benar

Cara pemeriksaan: Langsung periksa elemen ke-[2] dari array parts di elemen ke-[0] dari array contents di kode Anda, lihat apa yang dikirimkan.

6 Penyebab Umum dan Cara Perbaiki Error Model Gambar Gemini

Penyebab 1: Ada Objek Kosong atau String Kosong di parts

Ini adalah penyebab paling umum. Array parts dalam permintaan berisi elemen kosong seperti {}, null, atau string kosong "".

Kode yang Salah:

# ❌ Ada objek kosong di parts
payload = {
    "contents": [{
        "parts": [
            {"text": "Buat gambar kucing"},
            {},                              # ← Objek kosong, memicu error
            {"text": "dengan gaya cat air"}
        ]
    }]
}

Kode yang Benar:

# ✅ Setiap part memiliki konten yang valid
payload = {
    "contents": [{
        "parts": [
            {"text": "Buat gambar kucing dengan gaya cat air"}
        ]
    }]
}

Cara Perbaiki: Gabungkan teks ke dalam satu part text, atau pastikan setiap part berisi field text atau inlineData yang valid.

Penyebab 2: Data Base64 Gambar Kosong atau Formatnya Salah

Saat mengirim permintaan gambar-ke-gambar (image-to-image), data base64 di dalam inlineData mungkin kosong, rusak, atau formatnya tidak benar.

Kode yang Salah:

# ❌ Data base64 mengandung awalan data URI
payload = {
    "contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/png",
                    "data": "data:image/png;base64,iVBORw0KGgo..."  # ← Jangan sertakan awalan
                }
            },
            {"text": "Ubah latar belakang menjadi biru"}
        ]
    }]
}

# ❌ Data base64 adalah string kosong
"inlineData": {
    "mimeType": "image/jpeg",
    "data": ""          # ← Data kosong, langsung memicu error
}

Kode yang Benar:

import base64
import pathlib

# ✅ Baca gambar dengan benar dan ubah ke base64 murni
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       # ← String base64 murni, tanpa awalan
                }
            },
            {"text": "Ubah latar belakang menjadi biru"}
        ]
    }]
}

Cara Perbaiki:

• Field data hanya menerima string base64 murni, tidak boleh mengandung awalan data:image/png;base64,
• Pastikan file gambar benar-benar ada dan berhasil dibaca, hindari mengirim string kosong
• mimeType harus cocok dengan format gambar sebenarnya (image/png, image/jpeg, image/webp)

Penyebab 3: Objek File Tidak Dikonversi dengan Benar ke Referensi Konten

Setelah mengunggah file menggunakan Files API dari Google GenAI SDK, memasukkan objek File langsung ke contents dapat menyebabkan SDK gagal mengonversinya dengan benar.

Kode yang Salah:

from google import genai

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

# Unggah file
file = client.files.upload(file="foto.png")

# ❌ Di beberapa versi SDK, mengirim objek File langsung bisa gagal
response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Edit gambar ini", file]    # ← Objek File mungkin tidak bisa dikonversi otomatis
)

Kode yang Benar:

from google import genai
from google.genai import types

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

# Unggah file
file = client.files.upload(file="foto.png")

# ✅ Metode 1: Bangun referensi file secara manual
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 gambar ini: ubah latar belakang menjadi sunset")
        ])
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"]
    )
)

# ✅ Metode 2: Gunakan inlineData untuk mengirim base64 langsung (lebih andal)
import base64, pathlib

image_b64 = base64.b64encode(pathlib.Path("foto.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 gambar ini: ubah latar belakang menjadi sunset")
        ])
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"]
    )
)

Cara Perbaiki: Disarankan untuk menggunakan metode inlineData + base64 untuk mengirim data gambar langsung, karena lebih stabil dan andal dibandingkan Files API.

Penyebab 4: Riwayat Percakapan Multi-Turn Mengandung Konten Kosong

Saat mengedit gambar dalam percakapan multi-turn, jika respons dari putaran sebelumnya tidak ditangani dengan benar, riwayat percakapan mungkin tercampur dengan blok konten yang kosong.

Kode yang Salah:

# ❌ Riwayat percakapan tercampur parts kosong
history = [
    {"role": "user", "parts": [{"text": "Buat sebuah logo"}]},
    {"role": "model", "parts": []},        # ← Parts kosong, memicu error
    {"role": "user", "parts": [{"text": "Buat warnanya biru"}]}
]

payload = {"contents": history}

Kode yang Benar:

# ✅ Saring blok konten yang kosong
history = [
    {"role": "user", "parts": [{"text": "Buat sebuah logo"}]},
    {"role": "model", "parts": [{"text": "Ini logo yang saya buat."}]},
    {"role": "user", "parts": [{"text": "Buat warnanya biru"}]}
]

# Filter aman: Hapus catatan yang parts-nya kosong
clean_history = [msg for msg in history if msg.get("parts") and len(msg["parts"]) > 0]

payload = {"contents": clean_history}

Cara Perbaiki: Sebelum mengirim permintaan, telusuri array contents dan saring semua elemen yang parts-nya berupa daftar kosong atau mengandung objek kosong.

Penyebab 5: Kesalahan Kapitalisasi Nama Field JSON di REST API

Nama field JSON untuk Gemini API menggunakan camelCase (penulisan kapital unta), dan bersifat case-sensitive. Salah mengeja nama field akan menyebabkan field tersebut diabaikan, sama seperti mengirim data kosong.

Kode yang Salah:

# ❌ Menggunakan snake_case di REST API (gaya Python SDK)
payload = {
    "contents": [{
        "parts": [{
            "inline_data": {           # ← Seharusnya inlineData
                "mime_type": "image/png",   # ← Seharusnya mimeType
                "data": image_b64
            }
        }]
    }],
    "generation_config": {             # ← Seharusnya generationConfig
        "response_modalities": ["IMAGE"]   # ← Seharusnya responseModalities
    }
}

Kode yang Benar:

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

🎯 Pengingat yang Sering Membingungkan: Python SDK (google-genai) menggunakan snake_case (seperti inline_data), sedangkan pemanggilan langsung REST API menggunakan camelCase (seperti inlineData). Saat memanggil melalui platform proksi seperti APIYI apiyi.com, format yang digunakan adalah REST API, jadi harus menggunakan camelCase.

Penyebab 6: Format Gambar Tidak Didukung atau File Rusak

Gambar yang dikirim memiliki data base64, tetapi format gambar itu sendiri tidak didukung atau file sudah rusak.

Format Input yang Didukung Model Gambar Gemini:

Metode Pemeriksaan:

import base64

# Periksa apakah data base64 valid
def validate_image_data(b64_string, mime_type):
    # 1. Periksa apakah kosong
    if not b64_string:
        print("ERROR: Data base64 kosong")
        return False

    # 2. Periksa apakah mengandung awalan data URI
    if b64_string.startswith("data:"):
        print("ERROR: Hapus awalan 'data:image/...;base64,'")
        return False

    # 3. Periksa apakah base64 bisa didekode
    try:
        decoded = base64.b64decode(b64_string)
        print(f"OK: Ukuran hasil dekode = {len(decoded)} bytes")
    except Exception as e:
        print(f"ERROR: Base64 tidak valid - {e}")
        return False

    # 4. Periksa apakah mimeType didukung
    supported = ["image/png", "image/jpeg", "image/webp", "image/gif"]
    if mime_type not in supported:
        print(f"ERROR: mimeType '{mime_type}' tidak didukung")
        return False

    print("LULUS: Data gambar valid")
    return True

💡 Saran: Tambahkan fungsi validasi data sebelum mengirim permintaan, ini dapat menangkap sebagian besar masalah format lebih awal. Metode ini juga berlaku saat memanggil melalui platform APIYI apiyi.com.

Daftar Periksa Lengkap untuk Error Model Gambar Gemini

Saat Anda menemukan error required oneof field 'data', periksa daftar berikut satu per satu:

Perbaikan Cepat: Jika Anda sering mengalami error ini selama pengembangan, disarankan untuk menambahkan fungsi validate_payload() sebelum mengirim permintaan, yang secara otomatis memeriksa apakah setiap elemen dalam array parts valid. Saat memanggil model gambar Gemini melalui platform APIYI apiyi.com, format permintaannya sama persis dengan REST API resmi, sehingga metode pemeriksaan di atas juga berlaku.

Format Permintaan yang Benar untuk Model Gambar Gemini

Format Benar untuk Teks ke Gambar (Text-to-Image)

import requests, base64

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

# ✅ Format paling sederhana yang benar
payload = {
    "contents": [{
        "parts": [
            {"text": "Kucing oranye yang lucu duduk di ambang jendela, gaya cat air, 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))

Format Benar untuk Gambar ke Gambar (Image-to-Image)

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"

# Baca gambar asli dan ubah menjadi base64 murni
image_path = pathlib.Path("input_photo.png")
if not image_path.exists():
    raise FileNotFoundError(f"Gambar tidak ditemukan: {image_path}")

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

# Verifikasi data
assert len(image_b64) > 0, "Data Base64 kosong"
assert not image_b64.startswith("data:"), "Hapus awalan data URI"

# ✅ Format permintaan gambar ke gambar yang benar
payload = {
    "contents": [{
        "parts": [
            {
                "inlineData": {
                    "mimeType": "image/png",
                    "data": image_b64
                }
            },
            {
                "text": "Ubah latar belakang menjadi pemandangan pantai saat matahari terbenam, pertahankan subjek tetap sama"
            }
        ]
    }],
    "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("Sukses! Gambar disimpan.")
else:
    print(f"Error {response.status_code}: {response.text}")

Saran: Untuk skenario teks ke gambar, disarankan untuk memulai dari format paling sederhana, pastikan berjalan dengan baik sebelum menambahkan parameter secara bertahap. Melalui platform APIYI apiyi.com untuk memanggil Nano Banana 2, biaya per pemanggilan adalah $0.045, biaya pada tahap debugging sangat rendah.

Pertanyaan Umum

Ringkasan

Poin inti dari error required oneof field 'data' pada model gambar Gemini:

1. Penyebab Utama: Terdapat elemen kosong, data kosong, atau elemen dengan format salah dalam array parts.
2. Metode Pelacakan: Langsung lacak ke posisi yang sesuai dalam kode berdasarkan nomor indeks parts[N] dalam pesan error.
3. Penyebab Paling Umum: Objek kosong {}, base64 yang mengandung awalan data:, kesalahan huruf besar/kecil pada nama field JSON.
4. REST API HARUS menggunakan camelCase: inlineData (bukan inline_data), mimeType (bukan mime_type).
5. Tindakan Pencegahan: Tambahkan fungsi validasi payload sebelum dikirim, untuk mendeteksi elemen kosong dan masalah format secara otomatis.

Direkomendasikan untuk melakukan pengembangan dan debugging melalui platform APIYI apiyi.com untuk memanggil model gambar Gemini. Nano Banana 2 dengan pembayaran per penggunaan $0.045/kali, biaya debugging sangat rendah, dan format antarmuka sepenuhnya kompatibel dengan REST API resmi.

📚 Referensi

1. Dokumentasi Resmi Pembuatan Gambar Gemini API: Format permintaan dan penjelasan parameter lengkap.

   • Tautan: ai.google.dev/gemini-api/docs/image-generation
   • Penjelasan: Berisi format permintaan standar untuk Text-to-Image dan Image-to-Image.

2. Panduan Pemecahan Masalah Gemini API: Kode error dan saran perbaikan yang disediakan secara resmi.

   • Tautan: ai.google.dev/gemini-api/docs/troubleshooting
   • Penjelasan: Mencakup metode pemecahan masalah untuk error umum seperti 400, 429, 500.

3. GitHub Issue: Diskusi Error required oneof field data: Laporan komunitas dan solusi perbaikan.

   • Tautan: github.com/google-gemini/cookbook/issues/786
   • Penjelasan: Berisi analisis mendetail dan workaround untuk error yang disebabkan oleh penerusan objek File.

4. Dokumentasi Integrasi APIYI Nano Banana 2: Panduan lengkap untuk memanggil model gambar Gemini di platform APIYI.

   • Tautan: docs.apiyi.com/en/api-capabilities/nano-banana-2-image
   • Penjelasan: Berisi contoh format permintaan yang benar dan tanya jawab umum.

Penulis: Tim Teknis APIYI
Diskusi Teknis: Jika mengalami masalah dalam pemanggilan Gemini API, silakan kunjungi pusat dokumentasi APIYI di docs.apiyi.com untuk melihat lebih banyak panduan pemecahan masalah.