"API key not valid. Please pass a valid API key." — Gemini'nin bununla kastettiği beş şey

Bu mesaj Google'ın genel hata mesajıdır: gönderdiğiniz anahtar bu çağrı için kullanılamadı. Bu, anahtarın yanlış olmasıyla aynı şey değildir; beş nedenin dördünde anahtarın kendisi tamamen geçerlidir — bu yüzden anahtarı yeniden kopyalamak genellikle zaman kaybıdır.

Hata

yanıt (HTTP 400)

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

Nedenler ve çözümler özeti

Neden	Çözüm
Generative Language API, anahtarın projesinde etkin değil	Bu proje için etkinleştirin, ardından bir dakika bekleyin — yeni etkinleştirilen API'ler kısa bir süre boyunca reddedilir.
AI Studio uç noktasına gönderilen bir Vertex AI kimlik bilgisi	Vertex, bölgesel bir ana bilgisayara karşı OAuth kullanır; generativelanguage.googleapis.com ise bir AI Studio API anahtarı ister. Birbirlerinin yerine kullanılamazlar.
Anahtar HTTP-referrer veya IP kısıtlamaları taşıyor	Sunucu tarafı çağrıları referrer göndermez. IP ile kısıtlayın veya arka uç kullanımı için kısıtlamasız bir anahtar oluşturun.
Anahtar yanlış yerde gönderiliyor	Gemini `x-goog-api-key` veya `?key=` okur. `Authorization: Bearer` başlığı yok sayılır; bu nedenle istek anahtarsız ulaşır.
Anahtar silinmiş veya düşündüğünüzden farklı bir Google hesabından alınmış	Yeniden oluşturmanın işe yaradığı tek neden budur. AI Studio'da hangi hesapla oturum açıldığını kontrol edin.

Önce anahtarı tek başına doğrulayın

Uygulamanıza dokunmadan önce anahtarı yalın bir istekte kullanın. Bu çalışıyor ve uygulamanız çalışmıyorsa anahtar sağlamdır; hata, uygulamanızın anahtarı nasıl ilettiğindedir — böylece en yaygın üç nedeni aynı anda elemiş olursunuz.

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

İstemcinizin gerçekte hangi başlığı gönderdiğini okuyun

OpenAI biçimli SDK'ların çoğu kimlik bilgilerini `Authorization: Bearer` içine koyar. Gemini'nin kendi API'si bu başlığı okumaz; bu nedenle bir OpenAI istemcisini doğrudan generativelanguage.googleapis.com adresine yönlendirmek, tamamen geçerli bir anahtarla bu hatayı üretir. Ya Google'ın SDK'sını kullanın ya da bearer biçimini bekleyen OpenAI uyumlu bir uç noktayı çağırın.

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 ile 403'ü ayırın

Anahtar doğru iletildikten sonra neden PERMISSION_DENIED olarak değişirse anahtar artık okunuyor ve kapsam nedeniyle reddediliyordur — bu, farklı bir çözümü olan farklı bir sorundur (anahtar biçimi değil, proje izinleri). 400'den 403'e geçmek gerileme değil, ilerlemedir.

Kunavo üzerinden çağrı yapıyorsanız

Kunavo'da Gemini rafı, diğer her şeyle aynı OpenAI biçimli uç noktanın ve aynı `sk-kn-` anahtarının arkasındadır ve normal bir bearer token olarak gönderilir — bu nedenle yukarıdaki başlık uyuşmazlığı ve Vertex ile AI Studio arasındaki fark nedenleri burada ortaya çıkamaz. Etkinleştirilecek bir Google projesi veya sorun çıkarabilecek anahtar başına referrer politikası yoktur. Sizin sorumluluğunuz, anahtarın etkin ve cüzdanın fonlanmış olmasıdır; reddedilen bir istek ücretlendirilmez. Token başına Gemini ücretleri şurada: Gemini fiyatlandırma kılavuzumuz.

Sık sorulan sorular

Anahtarı az önce oluşturdum ama hâlâ geçersiz diyor.

Yeni etkinleştirilen API'ler ve yepyeni anahtarlar bir veya iki dakikaya kadar reddedilebilir. Bu süreyi aşarsa sorun neredeyse kesinlikle anahtarın bozuk olması değil, projede Generative Language API'nin bulunmamasıdır.

Bu, kotamın bittiği anlamına mı geliyor?

Hayır. Kotaların tükenmesi 429 RESOURCE_EXHAUSTED, faturalandırma sorunları ise 403 olarak görünür. 400 API_KEY_INVALID hiçbir zaman kredinizin bittiği anlamına gelmez.

Aynı anahtar AI Studio'da çalışırken kodumda neden çalışmıyor?

AI Studio çağrıları Google'ın kendi origin'inden gelir. Referrer kısıtlamalı bir anahtar buna izin verir ve hiç referrer göndermeyen sunucunuzu reddeder.

İlgili kılavuzlar

Hata anlamlarına ilişkin daha fazla bilgi hata referansı bölümünde; anahtar almak kayıt ve kimlik doğrulama kılavuzu üzerinden bir dakika sürer.