Gemini API 400 INVALID_ARGUMENT——“please use a valid role”以及空内容类错误

几乎所有这类 INVALID_ARGUMENT 都是因为将 OpenAI 风格的消息发送到 Google 原生的 generateContent 端点。它使用不同的角色名称，系统指令有独立的存放位置，而且不接受空的回合。

错误

同一类错误中的两种（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 数据。

确认你实际使用的是哪种 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

切勿发送没有 part 的回合

content 为 null 或被过滤成空内容的消息，会产生没有 part 的回合，并遭到拒绝。替换成空文本 part 可使回合保持有效，并保留模型预期的交替顺序。

发送前验证

断言 contents 非空、每个角色都是 user 或 model，并且每个回合至少包含一个 part。在调用处只需三行，就能避免网络返回 400 错误。

如果你通过 Kunavo 调用

通过 Kunavo 的 OpenAI 兼容端点 /v1/chat/completions 调用 Gemini，意味着你完全不需要手动构建 Google 的 contents 数组：你发送 OpenAI 格式的 messages，由网关负责映射——system 和 developer 消息合并到 systemInstruction，assistant 改写为 model，没有对应项的角色被删除，并用空文本 part 替代，而不是生成没有 part 的回合。因此，这整类 INVALID_ARGUMENT 不会由消息结构引起。但它无法帮你避免真正无效的参数——例如不支持的 response_format 或格式错误的内嵌图片，这些仍会因其本身无效而被拒绝。 Gemini 系列模型的每 token 费率见我们的 Gemini 价格指南.

常见问题

Gemini 有哪些有效角色？

在原生 API 中，角色只有两个：user 和 model。没有 system 角色——系统指令应放在单独的 systemInstruction 字段中。

可以发送 system 消息吗？

不能作为回合发送。请将它移到 systemInstruction，或使用会替你处理这件事的 OpenAI 兼容端点。

为什么完全相同的请求载荷在 OpenAI 上可以正常使用？

因为 OpenAI 的结构定义了 system 和 assistant 角色，而 Gemini 的原生结构没有。这个请求载荷是有效的——但只对另一个 API 有效。