Gemini API 400 INVALID_ARGUMENT—“please use a valid role” dan kelompok empty-contents

Hampir setiap INVALID_ARGUMENT dalam bentuk ini berasal dari pengiriman pesan bergaya OpenAI ke endpoint native generateContent milik Google. Endpoint ini memiliki nama role yang berbeda, tempat terpisah untuk instruksi sistem, dan tidak menoleransi giliran kosong.

Error

dua anggota dari keluarga yang sama (HTTP 400)

{"error":{"code":400,
  "message":"Please use a valid role: user, model.",
  "status":"INVALID_ARGUMENT"}}

{"error":{"code":400,
  "message":"* GenerateContentRequest.contents: contents is not specified\n",
  "status":"INVALID_ARGUMENT"}}

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
Pesan berbentuk OpenAI yang dikirim ke endpoint native	assistant → model, dan system berpindah ke systemInstruction. Selain itu tidak ada yang legal.
Array contents kosong	Semua pesan tersaring—sering kali giliran alat dengan content: null.
Giliran dengan array parts kosong	Gantikan dengan bagian teks kosong, bukan menghasilkan giliran tanpa parts.
Data gambar inline tanpa mimeType	inline_data memerlukan mime_type dan data base64.

Tentukan API yang sebenarnya Anda gunakan

Nama SDK yang sama berada di depan dua skema yang tidak kompatibel: generateContent native Google, yang menerima contents dengan role user dan model, serta /v1/chat/completions yang kompatibel dengan OpenAI, yang menerima messages dengan system, user, dan assistant. Setiap error dalam kelompok ini adalah payload yang ditulis untuk satu API tetapi dikirim ke API yang lain.

Petakan peran jika Anda menggunakan API native

Pesan system dan developer digabungkan ke dalam field systemInstruction terpisah. assistant menjadi model. user tetap user. Peran lain tidak memiliki padanan dan harus dihapus atau digabungkan sebelum dikirim.

to_gemini.py

def to_gemini(messages):
    system, contents = [], []
    for m in messages:
        if m["role"] in ("system", "developer"):
            system.append(m["content"])
            continue
        if m["role"] not in ("user", "assistant"):
            continue  # no Gemini equivalent
        parts = [{"text": m["content"] or ""}]  # never emit empty parts
        contents.append({
            "role": "model" if m["role"] == "assistant" else "user",
            "parts": parts,
        })
    req = {"contents": contents}
    if system:
        req["systemInstruction"] = {"parts": [{"text": "\n\n".join(system)}]}
    return req

Jangan pernah mengirim turn tanpa parts

Pesan yang content-nya null atau tersaring hingga kosong menghasilkan turn tanpa part, yang akan ditolak. Mengganti dengan text part kosong membuat turn tetap valid dan mempertahankan pergantian peran yang diharapkan model.

Validasikan sebelum mengirim

Pastikan contents tidak kosong, setiap role adalah user atau model, dan setiap turn memiliki setidaknya satu part. Tiga baris di lokasi pemanggilan, dibandingkan error 400 dari jaringan.

Jika Anda melakukan panggilan melalui Kunavo

Memanggil Gemini melalui endpoint OpenAI-compatible /v1/chat/completions milik Kunavo berarti Anda tidak perlu lagi menyusun array contents Google secara manual: Anda mengirim pesan berbentuk OpenAI dan gateway melakukan pemetaan — pesan system dan developer digabungkan ke systemInstruction, assistant ditulis ulang menjadi model, peran tanpa padanan dihapus, dan text part kosong disubstitusikan alih-alih mengirim turn tanpa part. Jadi seluruh kelas INVALID_ARGUMENT yang berasal dari bentuk pesan ini tidak akan terjadi. Yang tidak dapat diselamatkan adalah argumen yang memang tidak valid — seperti response_format yang tidak didukung atau gambar inline yang malformasi — yang tetap akan ditolak berdasarkan isinya. Tarif per token untuk katalog Gemini tercantum di panduan harga Gemini kami.

Pertanyaan umum

Apa saja role Gemini yang valid?

Pada API native, tepat dua: user dan model. Tidak ada role system — instruksi sistem ditempatkan di field systemInstruction terpisah.

Bisakah saya mengirim pesan system?

Bukan sebagai turn. Pindahkan ke systemInstruction, atau gunakan endpoint OpenAI-compatible yang melakukannya untuk Anda.

Mengapa payload yang sama berfungsi pada OpenAI?

Karena skema OpenAI mendefinisikan role system dan assistant, sedangkan skema native Gemini tidak. Payload tersebut valid — untuk API yang lain.

Panduan terkait

Detail semantik error lainnya tersedia di referensi error; mendapatkan kunci hanya perlu satu menit melalui pendaftaran dan panduan autentikasi.