Cấu hình và sử dụng API Key AI

Các chức năng AI của hệ thống (soạn đề, ngân hàng câu hỏi, trích xuất PDF, soạn giáo án, trò chơi…) cần một API Key để kết nối tới nhà cung cấp AI. Bài này hướng dẫn cách lấy, nhập và sử dụng API Key, cũng như dùng key miễn phí dùng chung.

Tổng quan: API Key dùng để làm gì?

API Key là "chìa khóa" để hệ thống gọi tới dịch vụ AI (Google Gemini, OpenAI, Claude, DeepSeek…). Bạn có hai cách dùng AI:

• Dùng API Key riêng của bạn: tự đăng ký key ở nhà cung cấp (ví dụ Google AI Studio) rồi dán vào hệ thống. Key được lưu trên trình duyệt của bạn, không lưu lên máy chủ và không giới hạn số lượt.
• Dùng Key miễn phí dùng chung: chọn một model miễn phí có sẵn, không cần key riêng nhưng bị giới hạn số lượt mỗi ngày.

Chỉ cần cấu hình một lần — cấu hình này áp dụng cho tất cả các chức năng AI.

Cấu hình API Key

Sau khi đăng nhập, khu vực cấu hình nằm ở thanh trên cùng, phía bên phải:

• Nút  — hiện khi bạn chưa cấu hình. Bấm để mở hộp thoại cấu hình.
• Huy hiệu "Lượt API miễn phí: X/Y" — số lượt miễn phí còn lại trong ngày (xanh khi còn, đỏ khi hết).
• Sau khi đã cấu hình, chỗ nút "Nhập Key" hiển thị tên model đang dùng kèm liên kết "Đổi Key" .

Trên điện thoại, khu vực này nằm trong menu trượt khi mở menu ở góc phải. Hộp thoại cấu hình có hai tab: "API Key của tôi" và "Key miễn phí".

Lấy API Key (ví dụ Google Gemini)

Google Gemini được khuyến nghị vì miễn phí và đọc ảnh tốt:

1. Truy cập Google AI Studio tại https://aistudio.google.com.
2. Đăng nhập tài khoản Google.
3. Vào mục Get API key → Create API key để tạo key mới.
4. Sao chép chuỗi key.

Hệ thống cũng hỗ trợ OpenAI, Anthropic Claude, DeepSeek và Custom (gateway tương thích OpenAI). Mỗi nhà cung cấp có trang tạo key riêng.

Nhập API Key vào hệ thống

Trong tab "API Key của tôi":

1. Chọn Provider (mặc định Google Gemini). Nếu chọn Custom, nhập thêm API Base URL và tên model.
2. Dán key vào ô nhập (bên dưới).
3. Bấm Kiểm tra Key — hệ thống thử các model để xác nhận key hợp lệ.
4. Nếu hợp lệ, hệ thống báo tìm thấy các model khả dụng và hiển thị danh sách để chọn.
5. Chọn một model rồi bấm Lưu cấu hình.

Key riêng chỉ được lưu trên trình duyệt của bạn, không gửi lên máy chủ. Vì vậy không nên nhập key riêng trên máy tính công cộng.

Chọn model và kiểm tra đọc ảnh (Vision)

Sau khi kiểm tra key thành công, danh sách model hiện ra:

• Model có dấu ✓ xanh là dùng được; model mờ là không khả dụng với key của bạn.
• Với Gemini, các model như gemini-2.0-flash, gemini-2.5-flash nhanh và phổ biến.

Hệ thống tự kiểm tra khả năng đọc ảnh (Vision) của model và hiển thị:

• Không có cảnh báo: model đọc được ảnh — dùng OCR/PDF bình thường.
• ⚠️ "Model này chỉ hỗ trợ Text": model không đọc ảnh — chức năng trích xuất PDF/ảnh sẽ không hoạt động.
• "?": chưa xác định được, vẫn có thể thử nhưng không đảm bảo.

Nếu bạn cần Trích xuất PDF/Ảnh hoặc import đề từ ảnh, hãy chọn model hỗ trợ đọc ảnh (Gemini Flash/Pro thường hỗ trợ tốt).

Key miễn phí dùng chung

Nếu chưa có key riêng, bạn có thể dùng key miễn phí ở tab "Key miễn phí":

1. Hệ thống tải danh sách model miễn phí có sẵn, nhóm theo nhà cung cấp. Model có thể kèm nhãn "⚠️ Text" (chỉ đọc văn bản) hoặc "?" (chưa kiểm tra ảnh).
2. (Tùy chọn) Bấm Kiểm tra kết nối để xác nhận model còn hoạt động — thao tác này không tốn lượt.
3. Chọn một model rồi bấm Sử dụng model này.

Khi dùng key miễn phí, hệ thống chỉ lưu tên nhà cung cấp và model; key thật do máy chủ quản lý, bạn không cần và không nhìn thấy.

Giới hạn lượt mỗi ngày

• Huy hiệu "Lượt API miễn phí: X/Y" trên thanh trên cùng cho biết số lượt còn lại hôm nay.
• Mỗi lần gọi AI thành công trừ 1 lượt; nếu gọi thất bại, hệ thống hoàn lại lượt.
• Số lượt tự đặt lại mỗi ngày.
• Khi hết lượt, hãy chờ sang ngày mới hoặc chuyển sang dùng API Key riêng (không giới hạn lượt).

API Key dùng cho chức năng nào?

Một cấu hình key duy nhất áp dụng cho tất cả chức năng AI, gồm: Kiểm tra online, Ngân hàng câu hỏi, Trích xuất PDF/Ảnh, Soạn giáo án, Dạy học bài tập, Bài tập về nhà, Trộn đề, và các trò chơi có sinh nội dung bằng AI. Đổi model/key ở thanh trên cùng sẽ áp dụng ngay cho mọi chức năng, không cần tải lại trang.

Nếu chưa cấu hình gì mà bấm chức năng AI, hệ thống sẽ nhắc bạn cấu hình API Key hoặc chọn key miễn phí trước.

Lưu ý và khắc phục sự cố

• Key sai / bị từ chối (401/403): kiểm tra lại chuỗi key và nhà cung cấp đã chọn đúng chưa.
• Hết hạn mức / quota (429): dùng quá nhiều — chờ một lúc hoặc đổi key khác.
• Kiểm tra Key báo không hợp lệ: dán lại key đầy đủ, đúng nhà cung cấp, rồi thử lại.
• Chức năng OCR/PDF không chạy: khả năng model đang chọn chỉ đọc văn bản — hãy chọn model hỗ trợ đọc ảnh.
• Key miễn phí báo lỗi (huy hiệu đỏ): model miễn phí đang dùng có thể đã bị tắt — bấm "Đổi Key" và chọn model miễn phí khác.
• Custom Provider: bắt buộc nhập API Base URL; có thể để trống ô model để hệ thống tự dò.
• Bạn có thể chuyển qua lại giữa key riêng và key miễn phí bất cứ lúc nào qua nút Đổi Key.