Gemini API 400 INVALID_ARGUMENT — “please use a valid role” ve boş contents ailesi

Bu biçimdeki neredeyse tüm INVALID_ARGUMENT hataları, OpenAI tarzı mesajların Google'ın kendi generateContent uç noktasına gönderilmesinden kaynaklanır. Bu uç nokta farklı rol adları kullanır, sistem talimatları için ayrı bir alanı vardır ve boş bir mesaj turuna tolerans göstermez.

Hata

aynı ailenin iki üyesi (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"}}

Nedenler ve çözümler özeti

Neden	Çözüm
OpenAI biçimindeki mesajlar Google'ın kendi uç noktasına gönderildi	assistant → model; system ise systemInstruction'a taşınır. Başka hiçbir şey geçerli değildir.
Boş contents dizisi	Her mesaj filtrelendi — çoğunlukla content: null içeren bir araç dönüşü nedeniyle.
Boş parts dizisine sahip bir dönüş	Parçasız bir dönüş göndermek yerine boş bir metin parçası kullanın.
mimeType olmadan satır içi görsel verisi	inline_data hem mime_type hem de base64 verisi gerektirir.

Aslında hangi API'yi kullandığınızı belirleyin

Aynı SDK adı, birbiriyle uyumsuz iki şema sunar: user ve model rollerine sahip contents alanını kullanan Google'ın kendi generateContent'i ve system, user, assistant rollerine sahip messages alanını kullanan OpenAI uyumlu /v1/chat/completions. Bu hata ailesindeki her hata, biri için hazırlanmış bir yükün diğerine gönderilmesinden kaynaklanır.

Google'ın kendi API'sindeyseniz rolleri eşleyin

system ve developer mesajlarını ayrı systemInstruction alanına taşıyın. assistant'ı model yapın. user aynı kalır. Başka rollerin eşdeğeri yoktur; gönderilmeden önce silinmeli veya birleştirilmelidir.

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

Parçasız bir dönüşü asla göndermeyin

İçeriği null olan veya filtrelenerek tamamen boşalan bir mesaj parçasız dönüş üretir ve bu reddedilir. Boş bir metin parçası eklemek dönüşü geçerli tutar ve modelin beklediği sırayı korur.

Göndermeden önce doğrulayın

contents'in boş olmadığını, her role'ün user veya model olduğunu ve her dönüşün en az bir part içerdiğini doğrulayın. Çağrı noktasında üç satır, ağdan gelen bir 400'e tercih edilir.

Kunavo üzerinden çağrı yapıyorsanız

Gemini'yi Kunavo'nun OpenAI uyumlu /v1/chat/completions uç noktası üzerinden çağırırsanız Google'ın contents dizisini elle oluşturmanız gerekmez: OpenAI biçimli mesajları gönderirsiniz, ağ geçidi eşlemeyi yapar — system ve developer mesajlarını systemInstruction'a taşır, assistant'ı model olarak yeniden yazar, eşdeğeri olmayan rolleri atar ve parçasız dönüş göndermek yerine boş bir metin parçası ekler. Bu nedenle bu INVALID_ARGUMENT sınıfı mesaj biçiminden kaynaklanmaz. Ancak gerçekten geçersiz bir argümandan — desteklenmeyen bir response_format veya hatalı biçimlendirilmiş satır içi görsel gibi — sizi kurtaramaz; bunlar kendi gerekçeleriyle yine reddedilir. Gemini ürün ailesi için token başına fiyatlar burada bulunur Gemini fiyatlandırma kılavuzumuz.

Sık sorulan sorular

Gemini'de geçerli roller nelerdir?

Google'ın kendi API'sinde tam olarak iki rol vardır: user ve model. system rolü yoktur; sistem talimatları ayrı systemInstruction alanına gider.

system mesajı gönderebilir miyim?

Bir dönüş olarak gönderemezsiniz. systemInstruction alanına taşıyın veya bunu sizin için yapan OpenAI uyumlu bir uç nokta kullanın.

Aynı yük neden OpenAI'ye gönderildiğinde çalışıyor?

Çünkü OpenAI şeması system ve assistant rollerini tanımlar, Gemini'nin kendi şeması tanımlamaz. Yük geçerlidir — ancak diğer API için.

İlgili kılavuzlar

Hata anlamlarına ilişkin daha fazla bilgi hata referansı bölümünde; anahtar almak kayıt ve kimlik doğrulama kılavuzu üzerinden bir dakika sürer.