"API key not valid. Please pass a valid API key." — câu ít hữu ích nhất của Gemini. Khóa thường THỰC SỰ hợp lệ; vấn đề nằm ở thứ xung quanh nó: hạn chế referrer, Generative Language API chưa được bật, hoặc khóa AI Studio được gửi đến endpoint Vertex. Hãy xử lý danh sách dưới đây theo thứ tự.
Lỗi
{
"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 |
|---|---|
| Hạn chế khóa (HTTP referrer / IP) chặn các cuộc gọi từ máy chủ | Trong Google Cloud Console → Credentials, khóa bị hạn chế theo referrer sẽ từ chối request phía máy chủ. Dùng khóa không hạn chế hoặc hạn chế theo API. |
| Generative Language API chưa được bật trong project | Bật "Generative Language API" cho các khóa kiểu AI Studio. |
| Khóa AI Studio và endpoint Vertex AI không khớp | Khóa AIza… gọi generativelanguage.googleapis.com; Vertex sử dụng OAuth/service account trên host khác. Không dùng lẫn hai loại. |
| Khu vực không được hỗ trợ | Khóa AI Studio không hoạt động ở mọi quốc gia; hãy kiểm tra tính khả dụng hoặc định tuyến qua gateway. |
| Truyền biến môi trường (dấu ngoặc kép/khoảng trắng/sai tên biến) | In print(repr(key)) bên trong tiến trình bị lỗi; export lại một cách sạch sẽ. |
Kiểm tra khóa riêng biệt
Một lệnh curl đến REST endpoint cho biết khóa tự thân có hoạt động hay không:
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 400Kiểm tra hạn chế và API đã bật
Cloud Console → APIs & Services → Credentials: mở khóa. Nếu Application restrictions hiển thị "HTTP referrers", các cuộc gọi từ máy chủ sẽ trả về 400 — chuyển sang None hoặc IP-based. Sau đó xác nhận Generative Language API được bật trong cùng project.
Nếu dù sao bạn vẫn cần một khóa cho nhiều mô hình
Nếu đang xoay xở với các khóa Gemini + Claude + GPT, gateway tương thích OpenAI sẽ gộp chúng thành một credential — cùng code, một base_url, không cần Google Cloud project.
Nếu bạn gọi qua Kunavo
Kunavo cung cấp Gemini 2.5 Flash và Pro phía sau cùng endpoint tương thích OpenAI và khóa sk-kn như Claude và GPT — không cần Google Cloud project, không cần debug hạn chế khóa và hoạt động ở các khu vực không cung cấp khóa AI Studio. Mức giá thấp hơn nhiều so với bảng giá của Google, và thiết lập chỉ gồm ba trường trong bất kỳ OpenAI SDK nào.
Câu hỏi thường gặp
Tại sao khóa Gemini của tôi hoạt động cục bộ nhưng thất bại trong production?
Thường là do hạn chế referrer/IP (không cho phép IP production), dùng tệp môi trường khác trong production hoặc dự án production chưa bật Generative Language API. Hãy đối chiếu biểu diễn repr của khóa và ID dự án giữa các môi trường.
Gemini API có miễn phí không?
AI Studio có gói miễn phí với hạn mức nghiêm ngặt theo phút; lưu lượng production cần bật thanh toán (hoặc dùng gateway). Nếu bạn gặp lỗi hạn mức thay vì lỗi khóa, hãy xem hướng dẫn RESOURCE_EXHAUSTED của chúng tôi.
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.