Gemini API 400 INVALID_ARGUMENT — „please use a valid role“ und die Familie der leeren contents

Nahezu jedes INVALID_ARGUMENT dieser Art entsteht, wenn Nachrichten im OpenAI-Format an Googles nativen generateContent-Endpunkt gesendet werden. Er verwendet andere Rollennamen, hat einen separaten Platz für Systemanweisungen und toleriert keinen leeren Turn.

Der Fehler

zwei Mitglieder derselben Familie (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"}}

Ursachen und Lösungen im Überblick

Ursache	Lösung
Nachrichten im OpenAI-Format an den nativen Endpunkt gesendet	assistant → model, und system wird zu systemInstruction. Nichts anderes ist zulässig.
Leeres contents-Array	Jede Nachricht wurde herausgefiltert — häufig ein Tool-Turn mit content: null.
Ein Turn mit einem leeren parts-Array	Ersetzen Sie ihn durch einen leeren Textteil, statt einen Turn ohne parts auszugeben.
Inline-Bilddaten ohne mimeType	inline_data benötigt sowohl mime_type als auch Base64-Daten.

Ermitteln Sie, welche API Sie tatsächlich verwenden

Hinter demselben SDK-Namen stehen zwei inkompatible Schemas: Googles natives generateContent, das contents mit den Rollen user und model erwartet, und ein OpenAI-kompatibler /v1/chat/completions-Endpunkt, der messages mit system, user und assistant erwartet. Jeder Fehler dieser Familie entsteht durch eine Payload, die für eine API geschrieben und an die andere gesendet wurde.

Ordnen Sie die Rollen zu, wenn Sie die native API verwenden

system- und developer-Nachrichten werden in ein separates Feld systemInstruction übernommen. assistant wird zu model. user bleibt user. Jede andere Rolle hat kein Äquivalent und muss vor dem Senden entfernt oder zusammengeführt werden.

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

Geben Sie niemals einen Turn ohne parts aus

Eine Nachricht, deren content null war oder vollständig herausgefiltert wurde, erzeugt einen Turn ohne parts und wird abgelehnt. Durch das Einsetzen eines leeren Textteils bleibt der Turn gültig und die vom Modell erwartete Abfolge erhalten.

Vor dem Senden validieren

Stellen Sie sicher, dass contents nicht leer ist, jede Rolle user oder model lautet und jeder Turn mindestens einen Teil enthält. Drei Zeilen am Aufrufort statt eines 400-Fehlers aus dem Netzwerk.

Wenn Sie Kunavo verwenden

Wenn Sie Gemini über Kunavos OpenAI-kompatiblen /v1/chat/completions-Endpunkt aufrufen, müssen Sie Googles contents-Array nie selbst erstellen: Sie senden Nachrichten im OpenAI-Format, und das Gateway übernimmt die Zuordnung — system- und developer-Nachrichten werden in systemInstruction zusammengeführt, assistant wird in model umgeschrieben, Rollen ohne Äquivalent werden entfernt und statt eines Turns ohne parts wird ein leerer Textteil eingesetzt. Diese gesamte Klasse von INVALID_ARGUMENT entsteht daher nicht durch die Nachrichtenstruktur. Was dadurch nicht behoben werden kann, ist ein tatsächlich ungültiges Argument — etwa ein nicht unterstütztes response_format oder ein fehlerhaftes Inline-Bild —, das weiterhin aufgrund seines Inhalts abgelehnt wird. Die Preise pro Token für die Gemini-Modelle finden Sie in unserem Gemini-Preisleitfaden.

Häufig gestellte Fragen

Welche Rollen sind in Gemini gültig?

In der nativen API genau zwei: user und model. Es gibt keine system-Rolle — Systemanweisungen gehören in das separate Feld systemInstruction.

Kann ich eine Systemnachricht senden?

Nicht als Turn. Verschieben Sie sie nach systemInstruction oder verwenden Sie einen OpenAI-kompatiblen Endpunkt, der dies für Sie übernimmt.

Warum funktioniert dieselbe Payload mit OpenAI?

Weil OpenAIs Schema die Rollen system und assistant definiert, Geminis natives Schema jedoch nicht. Die Payload ist gültig — für die andere API.