Gemini-API-Schlüssel funktioniert nicht — API_KEY_INVALID und seine fünf Ursachen

„API key not valid. Please pass a valid API key.“ — Geminis wenig hilfreicher Satz. Der Schlüssel IST normalerweise gültig; etwas in seiner Umgebung ist falsch: eine Referrer-Einschränkung, eine nicht aktivierte Generative Language API oder ein AI-Studio-Schlüssel, der an einen Vertex-Endpunkt gesendet wird. Arbeiten Sie die folgende Liste der Reihe nach ab.

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
Schlüsseleinschränkungen (HTTP-Referrer / IP) blockieren Serveraufrufe	In der Google Cloud Console → Credentials weist ein Schlüssel mit Referrer-Einschränkung serverseitige Anfragen zurück. Verwenden Sie einen uneingeschränkten Schlüssel oder schränken Sie ihn stattdessen nach API ein.
Generative Language API im Projekt nicht aktiviert	Aktivieren Sie die „Generative Language API“ für Schlüssel im AI-Studio-Stil.
AI-Studio-Schlüssel und Vertex-AI-Endpunkt passen nicht zusammen	AIza…-Schlüssel rufen generativelanguage.googleapis.com auf; Vertex verwendet OAuth/Dienstkonten auf einem anderen Host. Verwenden Sie sie nicht gegenseitig.
Nicht unterstützte Region	AI-Studio-Schlüssel funktionieren nicht aus jedem Land; prüfen Sie die Verfügbarkeit oder leiten Sie die Anfragen über ein Gateway.
Weitergabe der Umgebungsvariablen (Anführungszeichen/Leerzeichen/falscher Variablenname)	Führen Sie print(repr(key)) innerhalb des fehlschlagenden Prozesses aus; exportieren Sie den Wert sauber neu.

Testen Sie den Schlüssel isoliert

Ein einzelner curl-Aufruf an den REST-Endpunkt zeigt, ob der Schlüssel selbst in Ordnung ist:

test-gemini-key.sh

curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"parts":[{"text":"ping"}]}]}' | head -c 400

Einschränkungen und aktivierte APIs prüfen

Cloud Console → APIs & Services → Credentials: Öffnen Sie den Schlüssel. Wenn bei Application restrictions „HTTP referrers“ steht, führen Serveraufrufe zu 400 — wechseln Sie zu None oder einer IP-basierten Einschränkung. Bestätigen Sie anschließend, dass die Generative Language API im selben Projekt aktiviert ist.

Wenn Sie ohnehin einen Schlüssel für viele Modelle benötigen

Wenn Sie Gemini-, Claude- und GPT-Schlüssel verwalten, fasst ein OpenAI-kompatibles Gateway sie in einer Zugangsdaten zusammen — derselbe Code, eine base_url, kein Google-Cloud-Projekt erforderlich.

Wenn Sie Kunavo verwenden

Kunavo stellt Gemini 2.5 Flash und Pro hinter demselben OpenAI-kompatiblen Endpunkt und demselben sk-kn-Schlüssel bereit wie Claude und GPT — ohne Google-Cloud-Projekt, ohne zu debuggende Schlüsseleinschränkungen und in Regionen, in denen AI-Studio-Schlüssel nicht angeboten werden. Die Preise liegen deutlich unter Googles Listenpreis, und die Einrichtung besteht in jedem OpenAI SDK aus drei Feldern.

Häufig gestellte Fragen

Mein Gemini-Schlüssel funktioniert lokal, schlägt aber in der Produktion fehl — warum?

Meistens sind es Referrer-/IP-Einschränkungen (Produktions-IP-Adressen nicht zugelassen), eine andere Umgebungsdatei in der Produktion oder ein Produktionsprojekt, in dem die Generative Language API nicht aktiviert ist. Vergleichen Sie die repräsentierte Schlüsselzeichenfolge und die Projekt-ID zwischen den Umgebungen.

Ist die Gemini API kostenlos?

AI Studio bietet eine kostenlose Stufe mit strengen Kontingenten pro Minute; für Produktionsverkehr muss die Abrechnung aktiviert sein (oder ein Gateway verwendet werden). Wenn Sie Kontingentfehler statt Schlüsselfehler erhalten, lesen Sie unseren Leitfaden zu RESOURCE_EXHAUSTED.