"API key not valid. Please pass a valid API key." — năm điều Gemini muốn nói qua thông báo này

Đây là thông báo tổng quát của Google: key bạn gửi không thể được dùng cho lệnh gọi này. Điều đó không đồng nghĩa key bị sai, và bốn trong năm nguyên nhân vẫn để key hoàn toàn hợp lệ — vì vậy sao chép lại key thường chỉ tốn công vô ích.

Lỗi

phản hồi (HTTP 400)

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

Tổng quan nguyên nhân và cách khắc phục

Nguyên nhân	Cách khắc phục
Generative Language API chưa được bật cho project của key	Bật API cho project đó, rồi chờ một phút — các API vừa được bật có thể từ chối trong một khoảng thời gian ngắn.
Thông tin xác thực Vertex AI được gửi đến endpoint AI Studio	Vertex dùng OAuth với máy chủ theo khu vực; generativelanguage.googleapis.com yêu cầu AI Studio API key. Hai loại này không thể thay thế cho nhau.
Key có giới hạn HTTP-referrer hoặc IP	Lệnh gọi phía máy chủ không gửi referrer. Hãy giới hạn theo IP hoặc tạo key không giới hạn cho mục đích backend.
Key được gửi sai vị trí	Gemini đọc `x-goog-api-key` hoặc `?key=`. Header `Authorization: Bearer` bị bỏ qua, nên yêu cầu đến nơi mà không có key.
Key đã bị xóa hoặc đến từ tài khoản Google khác với bạn nghĩ	Đây là nguyên nhân duy nhất mà việc cấp lại key có thể giải quyết. Kiểm tra tài khoản mà AI Studio đang đăng nhập.

Trước tiên hãy chứng minh key hoạt động độc lập

Trước khi chạm vào ứng dụng, hãy đưa key vào một yêu cầu tối giản. Nếu cách này hoạt động còn ứng dụng không hoạt động, key không có vấn đề và lỗi nằm ở cách ứng dụng truyền key — qua đó loại trừ đồng thời ba nguyên nhân phổ biến nhất.

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

Đọc xem client thực sự gửi header nào

Phần lớn SDK có hình dạng OpenAI đặt thông tin xác thực trong `Authorization: Bearer`. API gốc của Gemini không đọc header đó, nên trỏ client OpenAI trực tiếp đến generativelanguage.googleapis.com sẽ tạo ra chính xác lỗi này dù key hoàn toàn hợp lệ. Hãy dùng SDK của Google hoặc gọi endpoint tương thích với OpenAI, nơi yêu cầu dạng bearer.

openai_shape.py

import os

from openai import OpenAI

# Bearer auth, OpenAI request shape, Gemini model names.
client = OpenAI(
    api_key=os.environ["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)

Phân biệt 400 với 403

Nếu lý do thay đổi thành PERMISSION_DENIED sau khi key được truyền đúng, key hiện đã được đọc nhưng bị từ chối do phạm vi quyền — đây là vấn đề khác với cách khắc phục khác (quyền project, không phải định dạng key). Chuyển từ 400 sang 403 là tiến triển, không phải thoái lui.

Nếu bạn gọi qua Kunavo

Trên Kunavo, Gemini nằm sau cùng một endpoint có dạng OpenAI và dùng cùng key `sk-kn-` như mọi dịch vụ khác, được gửi dưới dạng bearer token thông thường — vì vậy các nguyên nhân không khớp header và nhầm Vertex với AI Studio ở trên đơn giản là không có cách xuất hiện. Không có Google project cần bật và cũng không có chính sách referrer theo từng key để vướng phải. Trách nhiệm còn lại của bạn là đảm bảo key đang hoạt động và ví đã được nạp; yêu cầu bị từ chối sẽ không bị tính phí. Mức giá Gemini theo token nằm trong hướng dẫn giá Gemini của chúng tôi.

Câu hỏi thường gặp

Tôi vừa tạo key nhưng vẫn nhận được thông báo không hợp lệ.

Các API vừa được bật và key mới tạo có thể bị từ chối trong tối đa một hoặc hai phút. Nếu vẫn tiếp diễn sau thời gian đó, gần như chắc chắn project chưa có Generative Language API thay vì key bị hỏng.

Điều này có nghĩa là tôi đã hết hạn mức phải không?

Không. Hết hạn mức là 429 RESOURCE_EXHAUSTED, còn vấn đề thanh toán hiển thị dưới dạng 403. 400 API_KEY_INVALID không bao giờ có nghĩa là bạn hết tín dụng.

Tại sao cùng một key hoạt động trong AI Studio nhưng không hoạt động trong mã của tôi?

AI Studio gọi từ origin riêng của Google. Key bị giới hạn theo referrer cho phép origin đó nhưng từ chối máy chủ của bạn, nơi hoàn toàn không gửi referrer.

Hướng dẫn liên quan

Thông tin chi tiết hơn về ý nghĩa lỗi có trong tài liệu tham chiếu lỗi; bạn chỉ mất một phút để lấy khóa qua đăng ký và hướng dẫn xác thực.