"API key not valid. Please pass a valid API key." — lima hal yang dimaksud Gemini

Pesan ini adalah pesan umum Google: kunci yang Anda kirim tidak dapat digunakan untuk panggilan ini. Itu tidak sama dengan kunci yang salah, dan empat dari lima penyebabnya membuat kunci itu sendiri tetap valid — itulah sebabnya menyalin ulang kunci biasanya hanya membuang waktu.

Error

respons (HTTP 400)

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

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
Generative Language API belum diaktifkan pada project kunci tersebut	Aktifkan API untuk project tersebut, lalu tunggu satu menit — API yang baru diaktifkan akan menolak permintaan selama beberapa saat.
Kredensial Vertex AI dikirim ke endpoint AI Studio	Vertex menggunakan OAuth terhadap host regional; generativelanguage.googleapis.com menginginkan kunci API AI Studio. Keduanya tidak dapat saling menggantikan.
Kunci membawa pembatasan HTTP-referrer atau IP	Panggilan sisi server tidak mengirim referrer. Batasi berdasarkan IP, atau terbitkan kunci tanpa pembatasan untuk penggunaan backend.
Kunci dikirim di tempat yang salah	Gemini membaca `x-goog-api-key` atau `?key=`. Header `Authorization: Bearer` diabaikan, sehingga permintaan tiba tanpa kunci.
Kunci dihapus, atau berasal dari akun Google yang berbeda dari yang Anda kira	Ini satu-satunya penyebab yang dapat diperbaiki dengan menerbitkan ulang kunci. Periksa akun yang digunakan AI Studio untuk masuk.

Buktikan kunci secara terisolasi terlebih dahulu

Sebelum menyentuh aplikasi Anda, gunakan kunci tersebut dalam permintaan dasar. Jika ini berhasil tetapi aplikasi Anda tidak, berarti kuncinya baik dan masalahnya terletak pada cara aplikasi mengirimkannya — sehingga tiga penyebab paling umum dapat dieliminasi sekaligus.

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

Baca header yang sebenarnya dikirim klien Anda

Sebagian besar SDK berbentuk OpenAI menempatkan kredensial di `Authorization: Bearer`. API native Gemini tidak membaca header tersebut, jadi mengarahkan klien OpenAI langsung ke generativelanguage.googleapis.com menghasilkan kesalahan ini dengan kunci yang sebenarnya valid. Gunakan SDK Google, atau panggil endpoint yang kompatibel dengan OpenAI dan mengharapkan bentuk bearer.

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)

Bedakan 400 dari 403

Jika alasannya berubah menjadi PERMISSION_DENIED setelah kunci dikirim dengan benar, berarti kunci kini telah dibaca tetapi ditolak berdasarkan cakupan — masalah yang berbeda dengan perbaikan yang berbeda (izin project, bukan format kunci). Perubahan dari 400 menjadi 403 adalah kemajuan, bukan kemunduran.

Jika Anda melakukan panggilan melalui Kunavo

Di Kunavo, katalog Gemini berada di balik endpoint berbentuk OpenAI yang sama dan menggunakan kunci `sk-kn-` yang sama seperti yang lainnya, dikirim sebagai token bearer biasa — jadi penyebab ketidakcocokan header dan perbedaan Vertex-versus-AI-Studio di atas tidak memiliki bentuk untuk terjadi. Tidak ada Google project yang perlu diaktifkan dan tidak ada kebijakan referrer per kunci yang dapat memicu masalah. Tanggung jawab Anda adalah memastikan kunci aktif dan saldo dompet mencukupi; permintaan yang ditolak tidak ditagihkan. Tarif Gemini per token tersedia di panduan harga Gemini kami.

Pertanyaan umum

Saya baru saja membuat kunci, tetapi masih tertulis tidak valid.

API yang baru diaktifkan dan kunci yang baru dibuat dapat ditolak hingga satu atau dua menit. Jika masalah berlanjut setelah itu, project tersebut hampir pasti tidak memiliki Generative Language API, bukan karena kuncinya buruk.

Apakah ini berarti kuota saya habis?

Tidak. Kuota habis menghasilkan 429 RESOURCE_EXHAUSTED, dan masalah penagihan muncul sebagai 403. 400 API_KEY_INVALID tidak pernah berarti kredit Anda habis.

Mengapa kunci yang sama berfungsi di AI Studio tetapi tidak di kode saya?

AI Studio melakukan panggilan dari origin milik Google sendiri. Kunci yang dibatasi referrer mengizinkan origin tersebut dan menolak server Anda, yang sama sekali tidak mengirim referrer.

Panduan terkait

Detail semantik error lainnya tersedia di referensi error; mendapatkan kunci hanya perlu satu menit melalui pendaftaran dan panduan autentikasi.