Gemini API 400 INVALID_ARGUMENT —「請使用有效角色」與空內容系列錯誤

幾乎所有這類 INVALID_ARGUMENT 都是因為將 OpenAI 格式的訊息傳送至 Google 原生的 generateContent 端點。它使用不同的角色名稱，系統指示有獨立存放位置，也不容許空的回合。

錯誤

two members of the same family (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"}}

原因與解決方法一覽

原因	解決方法
傳送至原生端點的 OpenAI 格式訊息	assistant → model，system 移至 systemInstruction。除此之外沒有任何合法形式。
空的 contents 陣列	每則訊息都被篩除 — 通常是 content: null 的工具回合。
parts 陣列為空的回合	請替換成空文字 part，而不是送出沒有 part 的回合。
沒有 mimeType 的內嵌圖片資料	inline_data 同時需要 mime_type 與 base64 data。

確認您實際使用的是哪個 API

相同的 SDK 名稱背後有兩種不相容的結構：Google 原生的 generateContent 接受包含 user 與 model 角色的 contents；OpenAI 相容的 /v1/chat/completions 則接受包含 system、user 與 assistant 的 messages。此系列的每個錯誤，都是為其中一個 API 撰寫的 payload 被傳送到另一個 API。

如果使用原生 API，請對應角色

system 與 developer 訊息會合併至獨立的 systemInstruction 欄位。assistant 變成 model。user 維持 user。其他角色沒有對應形式，傳送前必須刪除或合併。

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

絕不要送出沒有 parts 的回合

content 為 null 或被篩除至空白的訊息會產生沒有 part 的回合，並遭到拒絕。替換成空文字 part 可維持回合有效，也能保留模型所期待的交替順序。

傳送前先驗證

確認 contents 不為空、每個角色都是 user 或 model，且每個回合至少有一個 part。在呼叫位置加入三行斷言，就能避免從網路收到 400。

如果你透過 Kunavo 呼叫

透過 Kunavo 的 OpenAI 相容 /v1/chat/completions 呼叫 Gemini，完全不需要自行建立 Google 的 contents 陣列：您傳送 OpenAI 格式的訊息，閘道會負責對應 — 將 system 與 developer 訊息合併至 systemInstruction、將 assistant 改寫為 model、刪除沒有對應形式的角色，並以空文字 part 取代無 part 的回合。因此，這整類 INVALID_ARGUMENT 不會因訊息結構而發生。但如果引數本身確實無效 — 例如不支援的 response_format 或格式錯誤的內嵌圖片 — 仍會依其內容遭到拒絕。 Gemini 系列的每權杖費率請見我們的 Gemini 價格指南.

常見問題

Gemini 有哪些有效角色？

在原生 API 中，恰好只有兩個：user 與 model。沒有 system 角色 — 系統指示要放在獨立的 systemInstruction 欄位。

可以傳送 system 訊息嗎？

不能作為回合傳送。請將它移至 systemInstruction，或使用會替您處理此事的 OpenAI 相容端點。

為什麼相同的 payload 對 OpenAI 有效？

因為 OpenAI 的結構定義了 system 與 assistant 角色，而 Gemini 的原生結構沒有。這個 payload 是有效的 — 但只對另一個 API 有效。