„API key not valid. Please pass a valid API key.“ — was Gemini damit in fünf Fällen meint

Diese Meldung ist Googles Sammelfehler: Der gesendete Schlüssel konnte für diesen Aufruf nicht verwendet werden. Das bedeutet nicht dasselbe wie ein falscher Schlüssel; bei vier der fünf Ursachen ist der Schlüssel selbst völlig gültig — deshalb ist erneutes Kopieren meist vergebliche Mühe.

Der Fehler

response (HTTP 400)

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [{ "reason": "API_KEY_INVALID" }]
  }
}

Ursachen und Lösungen im Überblick

Ursache	Lösung
Die Generative Language API ist für das Projekt des Schlüssels nicht aktiviert	Aktivieren Sie sie für dieses Projekt und warten Sie anschließend eine Minute — frisch aktivierte APIs lehnen Anfragen für kurze Zeit ab.
Ein Vertex-AI-Zugang wird am AI-Studio-Endpunkt gesendet	Vertex verwendet OAuth gegenüber einem regionalen Host; generativelanguage.googleapis.com erwartet einen AI-Studio-API-Schlüssel. Diese Zugangsdaten sind nicht austauschbar.
Der Schlüssel enthält Einschränkungen für HTTP-Referrer oder IP-Adresse	Serverseitige Aufrufe senden keinen Referrer. Schränken Sie nach IP ein oder erstellen Sie für das Backend einen uneingeschränkten Schlüssel.
Der Schlüssel wird an der falschen Stelle gesendet	Gemini liest `x-goog-api-key` oder `?key=`. Ein `Authorization: Bearer`-Header wird ignoriert, sodass die Anfrage ohne Schlüssel eintrifft.
Der Schlüssel wurde gelöscht oder stammt aus einem anderen Google-Konto als angenommen	Dies ist die einzige Ursache, bei der eine Neuausstellung hilft. Prüfen Sie, in welchem Konto AI Studio angemeldet ist.

Beweisen Sie zunächst isoliert, dass der Schlüssel funktioniert

Bevor Sie Ihre Anwendung anfassen, verwenden Sie den Schlüssel in einer einfachen Anfrage. Wenn diese funktioniert und Ihre Anwendung nicht, ist der Schlüssel in Ordnung und der Fehler liegt darin, wie Ihre Anwendung ihn überträgt — damit schließen Sie die drei häufigsten Ursachen auf einmal aus.

check-key.sh

curl -s -H "x-goog-api-key: $GEMINI_API_KEY" \
  "https://generativelanguage.googleapis.com/v1beta/models" \
  | head -20

# 200 + a model list  -> the key is valid; look at your client
# 400 API_KEY_INVALID -> the key really cannot call this API

Lesen Sie, welchen Header Ihr Client tatsächlich sendet

Die meisten OpenAI-förmigen SDKs legen Zugangsdaten in `Authorization: Bearer` ab. Geminis native API liest diesen Header nicht; wenn Sie einen OpenAI-Client direkt auf generativelanguage.googleapis.com richten, entsteht genau dieser Fehler mit einem völlig gültigen Schlüssel. Verwenden Sie entweder Googles SDK oder rufen Sie einen OpenAI-kompatiblen Endpunkt auf, der die Bearer-Form erwartet.

openai_shape.py

from openai import OpenAI

# Bearer auth, OpenAI request shape, Gemini model names.
client = OpenAI(
    api_key=KUNAVO_API_KEY,
    base_url="https://api.kunavo.com/v1",
)

print(client.chat.completions.create(
    model="gemini-2-5-flash",
    messages=[{"role": "user", "content": "ping"}],
).choices[0].message.content)

400 und 403 unterscheiden

Wenn sich der Grund nach korrekter Übertragung des Schlüssels in PERMISSION_DENIED ändert, wird der Schlüssel jetzt gelesen und wegen seines Geltungsbereichs abgelehnt — ein anderes Problem mit einer anderen Lösung (Projektberechtigungen statt Schlüsselformat). Der Übergang von 400 zu 403 ist ein Fortschritt, kein Rückschritt.

Wenn Sie Kunavo verwenden

Auf Kunavo liegt das Gemini-Angebot hinter demselben OpenAI-ähnlichen Endpunkt und demselben `sk-kn-`-Schlüssel wie alles andere; es wird als normaler Bearer-Token gesendet. Daher treten die oben beschriebenen Ursachen durch Header-Verwechslung oder Vertex-vs.-AI-Studio dort schlicht nicht auf. Es gibt kein Google-Projekt zu aktivieren und keine Referrer-Richtlinie pro Schlüssel, an der Sie scheitern könnten. Ihre Verantwortung bleibt, dass der Schlüssel aktiv und das Guthaben ausreichend ist; eine abgelehnte Anfrage wird nicht berechnet. Die Gemini-Tarife pro Token finden Sie unter unserem Gemini-Preisleitfaden.

Häufig gestellte Fragen

Ich habe den Schlüssel gerade erstellt, aber er wird weiterhin als ungültig angezeigt.

Frisch aktivierte APIs und ganz neue Schlüssel können bis zu ein oder zwei Minuten lang abgelehnt werden. Wenn der Fehler danach bestehen bleibt, fehlt dem Projekt mit großer Wahrscheinlichkeit die Generative Language API, nicht dass der Schlüssel fehlerhaft ist.

Bedeutet das, dass mein Kontingent aufgebraucht ist?

Nein. Erschöpftes Kontingent führt zu 429 RESOURCE_EXHAUSTED; Abrechnungsprobleme erscheinen als 403. 400 API_KEY_INVALID bedeutet niemals, dass Ihr Guthaben aufgebraucht ist.

Warum funktioniert derselbe Schlüssel in AI Studio, aber nicht in meinem Code?

AI Studio sendet Aufrufe vom eigenen Google-Ursprung. Ein durch Referrer eingeschränkter Schlüssel erlaubt diesen Zugriff, verweigert aber Ihren Server, der überhaupt keinen Referrer sendet.