Cách dùng Gemini tạo API
Bùi Tấn Lực - 105
- 10/10/2026
Gemini không chỉ là công cụ trò chuyện với trí tuệ nhân tạo mà còn cung cấp API để lập trình viên tích hợp khả năng xử lý ngôn ngữ, phân tích hình ảnh, đọc tài liệu và tạo nội dung vào website, ứng dụng hoặc hệ thống tự động hóa. Thông qua API, bạn có thể xây dựng chatbot riêng, công cụ hỗ trợ viết bài, ứng dụng hỏi đáp tài liệu hoặc tính năng AI phục vụ công việc mà không cần tự huấn luyện một mô hình ngôn ngữ từ đầu.
Để sử dụng được khả năng này, bạn cần tạo API key, lựa chọn mô hình phù hợp và gửi yêu cầu đến máy chủ Gemini bằng mã nguồn hoặc thư viện lập trình. Quá trình thiết lập tương đối đơn giản, nhưng để ứng dụng hoạt động ổn định, bạn cũng cần hiểu cách xác thực, giới hạn sử dụng, quản lý dữ liệu và bảo vệ thông tin truy cập.
Bài viết dưới đây hướng dẫn cách sử dụng Gemini tạo API theo hướng thực hành, từ bước chuẩn bị đến khi thực hiện được yêu cầu đầu tiên. Các ví dụ tập trung vào Python và JavaScript, hai ngôn ngữ phổ biến khi phát triển ứng dụng AI.
Gemini API là gì và có thể dùng để làm gì?
Gemini API là giao diện lập trình cho phép ứng dụng gửi dữ liệu đến các mô hình AI của Google và nhận kết quả trả về. Thay vì phải mở giao diện Gemini, nhập câu hỏi rồi sao chép câu trả lời thủ công, bạn có thể thực hiện toàn bộ quy trình bằng chương trình.
Ví dụ, khi người dùng nhập một câu hỏi trên website của bạn, máy chủ có thể gửi nội dung đó đến Gemini API, nhận câu trả lời và hiển thị kết quả ngay trên trang. Tương tự, một hệ thống xử lý tài liệu có thể gửi nội dung văn bản cho mô hình để tóm tắt, phân loại hoặc trích xuất thông tin theo định dạng mong muốn.
Điểm quan trọng cần hiểu là Gemini API không đồng nghĩa với việc tự tạo ra một mô hình AI mới. Bạn đang sử dụng mô hình do Google cung cấp thông qua một giao diện lập trình để xây dựng chức năng riêng cho ứng dụng của mình.
Những ứng dụng thực tế của Gemini API
- Xây dựng chatbot: Tạo trợ lý ảo trả lời câu hỏi của khách hàng, hỗ trợ tư vấn sản phẩm hoặc giải đáp thông tin trên website.
- Tạo nội dung tự động: Phát triển công cụ viết mô tả sản phẩm, gợi ý tiêu đề, tóm tắt bài viết hoặc tạo bản nháp nội dung.
- Phân tích tài liệu: Đọc nội dung văn bản, tổng hợp báo cáo, trích xuất dữ liệu từ tài liệu được hỗ trợ và trả lời câu hỏi dựa trên thông tin đầu vào.
- Xử lý hình ảnh: Xây dựng chức năng nhận diện nội dung hình ảnh, mô tả ảnh hoặc kết hợp văn bản với hình ảnh để phân tích.
- Hỗ trợ lập trình: Tạo công cụ giải thích mã nguồn, gợi ý cách sửa lỗi, viết đoạn mã mẫu hoặc phân tích cấu trúc chương trình.
- Tự động hóa quy trình: Kết hợp AI với hệ thống quản lý công việc, cơ sở dữ liệu và các dịch vụ khác để giảm thao tác thủ công.
Khả năng cụ thể phụ thuộc vào mô hình được chọn, loại dữ liệu gửi lên, phương thức API và hạn mức của dự án. Vì vậy, trước khi xây dựng ứng dụng, bạn nên xác định rõ chức năng cần triển khai thay vì mặc định mọi mô hình Gemini đều hỗ trợ tất cả tính năng.
Cần chuẩn bị gì trước khi sử dụng Gemini API?
Trước khi viết mã, bạn cần có tài khoản Google, quyền truy cập Google AI Studio và môi trường lập trình phù hợp. Nếu chỉ muốn thử nghiệm một yêu cầu đơn giản, bạn chưa nhất thiết phải xây dựng website hoặc thiết lập một hệ thống máy chủ hoàn chỉnh.
1. Tài khoản Google và Google AI Studio
Google AI Studio là nơi bạn có thể thử nghiệm mô hình, kiểm tra khả năng xử lý yêu cầu và quản lý API key cho Gemini API. Bạn có thể truy cập Google AI Studio để bắt đầu.
Nếu đây là lần đầu sử dụng, hãy đăng nhập bằng tài khoản Google và làm theo hướng dẫn trên giao diện. Tùy trạng thái tài khoản, dự án và quyền truy cập hiện có, hệ thống có thể yêu cầu bạn chấp nhận điều khoản hoặc thiết lập dự án trước khi tạo khóa.
2. Một ngôn ngữ lập trình
Bạn có thể gọi Gemini API bằng nhiều phương thức khác nhau, trong đó Python và JavaScript là hai lựa chọn thuận tiện cho người mới.
- Python: Phù hợp với các công cụ AI, chương trình xử lý dữ liệu, tự động hóa và ứng dụng chạy trên máy chủ.
- JavaScript: Phù hợp với hệ thống Node.js, dịch vụ backend và các ứng dụng web cần tích hợp AI.
- REST API: Phù hợp khi bạn muốn tự xây dựng yêu cầu HTTP hoặc sử dụng ngôn ngữ lập trình không có thư viện hỗ trợ thuận tiện.
Nếu chưa biết lập trình, bạn vẫn có thể thử nghiệm mô hình trong Google AI Studio trước. Tuy nhiên, để tích hợp API vào một website hoặc ứng dụng hoàn chỉnh, bạn sẽ cần biết cách sử dụng mã nguồn, cấu hình môi trường và xử lý phản hồi từ máy chủ.
3. API key và dự án sử dụng API
API key là thông tin xác thực giúp ứng dụng gửi yêu cầu đến Gemini API. Khóa này gắn với một dự án và có vai trò quan trọng trong việc quản lý quyền truy cập, hạn mức cũng như hoạt động sử dụng dịch vụ.
Bạn cần xem API key như một thông tin bí mật. Nếu người khác lấy được khóa và sử dụng trái phép, họ có thể tiêu thụ hạn mức hoặc phát sinh chi phí trên dự án của bạn. Không nên đăng khóa lên website công khai, đưa vào mã nguồn frontend hoặc chia sẻ trong các bài hướng dẫn.
Cách tạo API key Gemini trên Google AI Studio
Đây là bước đầu tiên để ứng dụng của bạn có thể gửi yêu cầu đến mô hình Gemini. Bạn không cần tự xây dựng hệ thống xác thực riêng, nhưng phải tạo và quản lý API key đúng cách.
Bước 1: Truy cập trang quản lý API key
Mở Google AI Studio và đăng nhập tài khoản Google. Tìm mục quản lý API key hoặc truy cập trang API Keys nếu tài khoản của bạn có quyền sử dụng.
Giao diện có thể thay đổi theo thời gian, nhưng mục tiêu của bước này là mở trang cho phép tạo khóa mới và quản lý các khóa đã tồn tại.
Bước 2: Chọn hoặc tạo dự án
Gemini API sử dụng dự án để quản lý tài nguyên và các thông tin liên quan đến việc sử dụng dịch vụ. Nếu đã có dự án phù hợp, bạn có thể sử dụng dự án đó sau khi bảo đảm tài khoản có đủ quyền.
Nếu chưa có dự án, hãy làm theo hướng dẫn của Google AI Studio để tạo dự án mới. Trong một số trường hợp, bạn cần nhập dự án Google Cloud hiện có vào AI Studio trước khi có thể quản lý khóa tương ứng.
Nếu nút tạo API key không xuất hiện hoặc hệ thống thông báo thiếu quyền, hãy kiểm tra quyền truy cập dự án và các thiết lập liên quan đến API. Không nên tìm cách bỏ qua cơ chế phân quyền của tài khoản hoặc tổ chức.
Bước 3: Tạo API key
Chọn chức năng tạo API key và làm theo hướng dẫn trên màn hình. Hệ thống sẽ tạo khóa gắn với dự án được chọn nếu tài khoản đáp ứng các điều kiện cần thiết.
Chính sách xác thực của Gemini API có thể thay đổi. Theo tài liệu hiện hành, các khóa mới được tạo trong Google AI Studio mặc định là khóa xác thực gắn với tài khoản dịch vụ, trong khi một số khóa cũ có thể thuộc loại tiêu chuẩn. Bạn nên kiểm tra loại khóa và yêu cầu bảo mật hiển thị trong trang quản lý trước khi sử dụng.
Bước 4: Sao chép và lưu API key an toàn
Sau khi tạo thành công, hãy sao chép API key và lưu vào nơi an toàn. Không gửi khóa qua các kênh công khai, không chụp ảnh màn hình có chứa khóa để đăng lên mạng và không đưa giá trị thật của khóa vào ví dụ mã nguồn.
Nếu cần sử dụng API key trong chương trình, cách phù hợp là lưu khóa trong biến môi trường hoặc hệ thống quản lý bí mật của môi trường triển khai. Chương trình sẽ đọc giá trị đó khi chạy thay vì viết trực tiếp khóa vào mã nguồn.
Lưu ý: Tạo được API key không có nghĩa là bạn có quyền sử dụng không giới hạn mọi mô hình hoặc tính năng. Hạn mức, quyền truy cập và chi phí phụ thuộc vào dự án, mô hình, cấu hình thanh toán cùng chính sách hiện hành của Google.
Cách sử dụng Gemini API bằng Python
Python là lựa chọn phù hợp nếu bạn muốn tạo một công cụ AI độc lập, xử lý dữ liệu hoặc xây dựng backend cho website. Cách tiếp cận đơn giản nhất là cài đặt thư viện chính thức, cấu hình API key và gửi một yêu cầu thử nghiệm.
Bước 1: Cài đặt thư viện Gemini
Trước tiên, hãy cài đặt Python trên máy tính nếu chưa có. Sau đó, mở Terminal hoặc Command Prompt và chạy lệnh cài đặt thư viện Google Gen AI SDK:
python -m pip install -U google-genai
Thư viện này cung cấp các phương thức để làm việc với Gemini API mà không cần tự xây dựng toàn bộ yêu cầu HTTP. Bạn nên sử dụng môi trường ảo cho dự án thực tế để quản lý các gói phụ thuộc rõ ràng hơn.
Bước 2: Thiết lập API key trong biến môi trường
Trước khi chạy chương trình, hãy thiết lập biến môi trường có tên GEMINI_API_KEY và gán giá trị API key đã tạo.
Trên macOS hoặc Linux, bạn có thể thiết lập biến trong phiên Terminal hiện tại bằng lệnh sau. Hãy thay phần giá trị mẫu bằng khóa của bạn, đồng thời không chia sẻ lệnh chứa khóa thật:
export GEMINI_API_KEY="YOUR_API_KEY"
Trên Windows PowerShell, sử dụng lệnh tương ứng:
$env:GEMINI_API_KEY="YOUR_API_KEY"
Đây là cách thiết lập tạm thời cho phiên làm việc hiện tại. Nếu mở một cửa sổ Terminal mới, bạn có thể cần thiết lập lại biến môi trường. Trong môi trường triển khai thực tế, hãy sử dụng cơ chế cấu hình bí mật phù hợp với hệ điều hành hoặc nền tảng máy chủ.
Bước 3: Viết chương trình gọi Gemini API
Sau khi cài đặt thư viện và cấu hình khóa, bạn có thể tạo một tệp Python, chẳng hạn gemini_api.py, rồi nhập đoạn mã sau:
from google import genai
import os
api_key = os.getenv("GEMINI_API_KEY")
if not api_key:
raise RuntimeError("Chua cau hinh GEMINI_API_KEY")
client = genai.Client(api_key=api_key)
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Hay giai thich Gemini API bang tieng Viet ngan gon."
)
print(response.text)
Đây là ví dụ tối giản để kiểm tra khả năng gửi yêu cầu và nhận văn bản phản hồi. Tên mô hình trong ví dụ chỉ mang tính minh họa cho cách gọi SDK; trước khi sử dụng, hãy kiểm tra mô hình còn được hỗ trợ và phù hợp với dự án của bạn trong danh sách mô hình Gemini API.
Đoạn mã trên hoạt động theo các bước:
- Nhập thư viện cần thiết để sử dụng Gemini API và đọc biến môi trường.
- Lấy giá trị API key từ biến môi trường đã thiết lập.
- Khởi tạo đối tượng client để gửi yêu cầu đến dịch vụ.
- Gọi phương thức tạo nội dung với tên mô hình và câu lệnh đầu vào.
- In nội dung văn bản mà mô hình trả về.
Nếu chương trình chạy thành công, Terminal sẽ hiển thị câu trả lời do Gemini tạo ra. Nội dung thực tế có thể khác nhau giữa các lần chạy vì mô hình có thể tạo ra nhiều cách diễn đạt cho cùng một yêu cầu.
Bước 4: Chạy chương trình và kiểm tra kết quả
Lưu tệp mã nguồn, sau đó chạy lệnh sau trong thư mục chứa tệp:
python gemini_api.py
Nếu nhận được phản hồi, bạn đã hoàn thành bước thử nghiệm cơ bản: ứng dụng Python có thể xác thực và gửi yêu cầu đến Gemini API.
Nếu chương trình báo lỗi, hãy kiểm tra API key, biến môi trường, tên mô hình, kết nối mạng và quyền sử dụng dịch vụ. Không nên vội tạo nhiều khóa mới khi chưa xác định nguyên nhân, vì lỗi có thể đến từ cấu hình hoặc hạn mức chứ không phải từ bản thân API key.
Cách sử dụng Gemini API bằng JavaScript
Nếu bạn đang phát triển ứng dụng Node.js, JavaScript cũng là lựa chọn thuận tiện. Bạn có thể sử dụng SDK chính thức để gửi yêu cầu đến Gemini và xử lý nội dung phản hồi trong chương trình.
Bước 1: Chuẩn bị môi trường Node.js
Hãy cài đặt phiên bản Node.js phù hợp với thư viện bạn định sử dụng. Sau đó, tạo một thư mục mới cho dự án và mở Terminal tại thư mục đó.
Chạy các lệnh sau để khởi tạo dự án và cài đặt SDK:
npm init -y
npm install @google/genai
SDK @google/genai cung cấp giao diện JavaScript để làm việc với Gemini API. Khi phát triển dự án mới, bạn nên ưu tiên thư viện chính thức được Google duy trì và kiểm tra tài liệu để biết cách sử dụng tương thích với phiên bản đã cài đặt.
Bước 2: Cấu hình API key
Trên macOS hoặc Linux, thiết lập biến môi trường bằng lệnh:
export GEMINI_API_KEY="YOUR_API_KEY"
Trên Windows PowerShell, sử dụng:
$env:GEMINI_API_KEY="YOUR_API_KEY"
Hãy thay giá trị mẫu bằng API key thật trong môi trường của bạn. Không đưa khóa thật vào mã nguồn JavaScript được phát hành công khai hoặc gửi đến trình duyệt của người dùng.
Bước 3: Gửi yêu cầu bằng JavaScript
Tạo tệp gemini_api.mjs và thêm đoạn mã sau:
import { GoogleGenAI } from "@google/genai";
const apiKey = process.env.GEMINI_API_KEY;
if (!apiKey) {
throw new Error("Chua cau hinh GEMINI_API_KEY");
}
const ai = new GoogleGenAI({ apiKey });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: "Hay goi y 3 tinh nang AI cho mot website ban hang."
});
console.log(response.text);
}
main().catch((error) => {
console.error("Khong the goi Gemini API:", error.message);
process.exitCode = 1;
});
Đây là chương trình mẫu sử dụng SDK JavaScript để gửi yêu cầu tạo nội dung. Tương tự ví dụ Python, hãy kiểm tra danh sách mô hình hiện hành và thay tên mô hình nếu cần.
Trong chương trình này, hàm main() thực hiện yêu cầu theo cơ chế bất đồng bộ. Từ khóa await giúp chương trình chờ phản hồi từ API trước khi in kết quả. Phần xử lý lỗi giúp hiển thị thông báo khi yêu cầu thất bại thay vì để lỗi bị bỏ qua.
Bước 4: Chạy chương trình
Sau khi lưu tệp, chạy lệnh:
node gemini_api.mjs
Nếu API key hợp lệ, mô hình được phép truy cập và yêu cầu đáp ứng các điều kiện sử dụng, chương trình sẽ hiển thị gợi ý do Gemini tạo ra. Nếu có lỗi, hãy xem thông báo trả về để xác định cần điều chỉnh cấu hình, quyền truy cập hay nội dung yêu cầu.
Điểm cần nhớ: Các ví dụ trên phù hợp để thử nghiệm trong môi trường lập trình. Khi đưa tính năng lên website thật, bạn nên gọi Gemini API từ backend của mình thay vì đặt API key trong mã JavaScript chạy trực tiếp trên trình duyệt.
Cách chọn mô hình Gemini phù hợp với ứng dụng
Gemini API có nhiều mô hình và các phiên bản có thể khác nhau về tốc độ, chất lượng xử lý, khả năng đa phương thức, giới hạn sử dụng và chi phí. Việc chọn đúng mô hình giúp ứng dụng đáp ứng nhu cầu thực tế mà không tiêu tốn tài nguyên không cần thiết.
Không nên chỉ chọn mô hình mới nhất hoặc có khả năng cao nhất cho mọi tình huống. Một chatbot trả lời câu hỏi đơn giản có thể không cần cùng loại mô hình với hệ thống phân tích tài liệu phức tạp hoặc quy trình yêu cầu suy luận nhiều bước.
Chọn theo độ phức tạp của công việc
- Tác vụ đơn giản: Với việc phân loại văn bản, tạo câu trả lời ngắn hoặc viết lại nội dung cơ bản, hãy ưu tiên mô hình có tốc độ tốt và chi phí phù hợp.
- Tác vụ phức tạp: Với phân tích nhiều bước, xử lý yêu cầu khó hoặc các nhiệm vụ cần lập luận sâu, hãy thử nghiệm những mô hình được thiết kế cho công việc đó.
- Tác vụ đa phương thức: Nếu cần xử lý hình ảnh, âm thanh hoặc video, hãy kiểm tra mô hình có hỗ trợ đúng loại dữ liệu và phương thức đầu vào mà ứng dụng yêu cầu hay không.
- Ứng dụng quy mô lớn: Hãy đánh giá đồng thời chất lượng đầu ra, tốc độ phản hồi, hạn mức, độ ổn định và chi phí dự kiến.
Bạn có thể tham khảo tài liệu mô hình Gemini API để kiểm tra tên mô hình, khả năng hỗ trợ và trạng thái phát hành. Tránh cố định một tên mô hình trong toàn bộ hệ thống mà không có kế hoạch cập nhật khi mô hình thay đổi hoặc ngừng hỗ trợ.
Kiểm thử trước khi đưa vào sử dụng
Trước khi lựa chọn mô hình chính thức, hãy tạo một bộ câu hỏi đại diện cho nhu cầu thực tế. Chạy cùng bộ dữ liệu qua các mô hình cần so sánh, sau đó đánh giá độ chính xác, mức độ phù hợp của câu trả lời, thời gian phản hồi và chi phí.
Ví dụ, nếu xây dựng chatbot tư vấn sản phẩm, bạn nên kiểm tra khả năng trả lời câu hỏi về giá, phân biệt các phiên bản sản phẩm, từ chối cung cấp thông tin chưa được xác nhận và duy trì câu trả lời nhất quán. Những tiêu chí này có giá trị thực tế hơn việc chỉ đánh giá câu trả lời có trôi chảy hay không.
Ngoài ra, hãy xác định cách ứng dụng xử lý trường hợp mô hình không biết câu trả lời. Một hệ thống tốt không chỉ tạo nội dung nhanh mà còn cần hạn chế thông tin sai, xử lý đầu vào bất thường và thông báo rõ ràng khi không thể hoàn thành yêu cầu.
Đến đây, bạn đã biết cách tạo API key, thiết lập môi trường và thực hiện yêu cầu đầu tiên với Gemini bằng Python hoặc JavaScript. Tuy nhiên, để sử dụng API trong một sản phẩm thực tế, bạn còn cần xử lý dữ liệu đầu vào, kiểm soát chi phí, bảo vệ khóa truy cập và quản lý lỗi một cách bài bản.
Cách tích hợp Gemini API vào website
Sau khi gọi Gemini API thành công bằng Python hoặc JavaScript, bước tiếp theo là đưa khả năng AI vào một ứng dụng thực tế. Chẳng hạn, bạn có thể xây dựng chatbot trên website, công cụ tạo nội dung tự động, hệ thống hỏi đáp tài liệu hoặc tính năng hỗ trợ khách hàng.
Điều quan trọng nhất khi tích hợp Gemini API vào website là thiết kế đúng luồng xử lý. Trình duyệt tiếp nhận yêu cầu của người dùng, máy chủ của website kiểm tra dữ liệu rồi gọi Gemini API. Sau đó, máy chủ trả kết quả về trình duyệt để hiển thị cho người dùng.
Với ứng dụng thực tế, không nên gọi Gemini API trực tiếp từ trình duyệt bằng một API key bí mật. Mã JavaScript phía trình duyệt có thể được người dùng kiểm tra, khiến khóa truy cập bị lộ và có nguy cơ bị sử dụng trái phép.
Mô hình hoạt động của một ứng dụng sử dụng Gemini API
Một hệ thống tích hợp AI thông thường có thể được tổ chức theo luồng sau:
- Người dùng nhập câu hỏi hoặc nội dung vào giao diện website.
- Trình duyệt gửi dữ liệu đến API backend của website.
- Backend kiểm tra dữ liệu đầu vào, quyền truy cập và giới hạn số lần gọi.
- Backend gửi yêu cầu đến Gemini API bằng API key được lưu an toàn trên máy chủ.
- Gemini xử lý yêu cầu và trả kết quả về backend.
- Backend kiểm tra phản hồi rồi gửi dữ liệu phù hợp về trình duyệt.
- Giao diện hiển thị câu trả lời cho người dùng.
Cách tổ chức này giúp bạn kiểm soát tốt hơn việc xác thực người dùng, giới hạn lưu lượng truy cập, ghi nhận lỗi và bảo vệ thông tin bí mật. Khi ứng dụng phát triển, bạn cũng có thể bổ sung bộ nhớ hội thoại, cơ sở dữ liệu, bộ lọc nội dung hoặc hệ thống giám sát mà không cần thay đổi toàn bộ kiến trúc.
Ví dụ xây dựng API backend bằng Node.js và Gemini
Để hiểu rõ cách tích hợp, hãy giả sử bạn muốn tạo một API riêng cho website. Người dùng gửi câu hỏi đến endpoint của bạn, backend chuyển câu hỏi sang Gemini và trả lời dưới dạng JSON.
Ví dụ dưới đây sử dụng Node.js, Express và thư viện chính thức @google/genai. Đây là mã minh họa cho môi trường phát triển, chưa bao gồm đầy đủ các lớp bảo vệ cần thiết khi triển khai công khai.
Bước 1: Cài đặt thư viện
Nếu đã có dự án Node.js, hãy cài đặt các gói cần thiết:
npm install express @google/genai
Trong ví dụ này, Express tiếp nhận yêu cầu HTTP, còn Google Gen AI SDK thực hiện việc gọi Gemini API. API key cần được thiết lập trong biến môi trường của máy chủ, không đưa vào mã frontend.
Bước 2: Tạo endpoint gửi câu hỏi đến Gemini
Tạo tệp server.mjs với nội dung sau:
import express from "express";
import { GoogleGenAI } from "@google/genai";
const app = express();
const port = Number(process.env.PORT || 3000);
const apiKey = process.env.GEMINI_API_KEY;
if (!apiKey) {
throw new Error("Chua cau hinh GEMINI_API_KEY");
}
const ai = new GoogleGenAI({ apiKey });
app.use(express.json({ limit: "20kb" }));
app.post("/api/ask", async (req, res) => {
const question = req.body?.question;
if (typeof question !== "string" || !question.trim()) {
return res.status(400).json({
error: "Vui long nhap cau hoi hop le"
});
}
if (question.length > 4000) {
return res.status(400).json({
error: "Cau hoi qua dai"
});
}
try {
const result = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: question.trim()
});
return res.json({
answer: result.text ?? ""
});
} catch (error) {
console.error("Gemini API request failed");
return res.status(502).json({
error: "Khong the xu ly yeu cau luc nay"
});
}
});
app.listen(port, () => {
console.log(`Server running on port ${port}`);
});
Đoạn mã sử dụng một endpoint có tên /api/ask. Khi nhận yêu cầu POST chứa trường question, máy chủ kiểm tra kiểu dữ liệu, loại bỏ khoảng trắng thừa và giới hạn độ dài câu hỏi trước khi gọi Gemini.
Nếu yêu cầu thành công, backend trả về JSON có trường answer. Nếu dữ liệu không hợp lệ, máy chủ trả mã HTTP 400. Khi Gemini API gặp sự cố, máy chủ trả mã 502 cùng thông báo chung, thay vì gửi nguyên thông tin lỗi nội bộ hoặc thông tin nhạy cảm về trình duyệt.
Tên mô hình trong đoạn mã chỉ là ví dụ. Trước khi triển khai, hãy kiểm tra trạng thái hỗ trợ của mô hình trong tài liệu Gemini API và điều chỉnh cho phù hợp.
Bước 3: Khởi chạy máy chủ
Thiết lập biến môi trường GEMINI_API_KEY trong môi trường chạy ứng dụng, sau đó thực thi:
node server.mjs
Nếu máy chủ khởi động thành công, bạn có thể gửi yêu cầu POST đến endpoint đã tạo. Trong môi trường phát triển, dùng lệnh sau để kiểm tra:
curl -X POST http://localhost:3000/api/ask
-H "Content-Type: application/json"
-d "{"question":"Gemini API co the dung de lam gi?"}"
Nếu mọi cấu hình đều đúng, máy chủ sẽ trả về một đối tượng JSON chứa câu trả lời do Gemini tạo ra. Kết quả cụ thể có thể khác nhau giữa các lần gọi.
Bước 4: Kết nối giao diện website với backend
Ở phía frontend, bạn chỉ cần gửi câu hỏi đến endpoint của chính website và đọc dữ liệu JSON phản hồi. Ví dụ:
async function askGemini(question) {
const response = await fetch("/api/ask", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({ question })
});
const data = await response.json();
if (!response.ok) {
throw new Error(data.error || "Yeu cau that bai");
}
return data.answer;
}
Hàm trên không chứa API key Gemini. Trình duyệt chỉ giao tiếp với backend của website, còn backend chịu trách nhiệm xác thực và gọi dịch vụ AI.
Trong ứng dụng hoàn chỉnh, bạn cần bổ sung trạng thái đang xử lý, hiển thị thông báo khi có lỗi, ngăn gửi yêu cầu liên tục và xử lý nội dung trả về an toàn. Nếu hiển thị câu trả lời dưới dạng văn bản thuần, hãy sử dụng cơ chế cập nhật nội dung phù hợp như textContent thay vì chèn trực tiếp chuỗi không đáng tin cậy vào HTML.
Cách sử dụng Gemini API để tạo nội dung theo định dạng JSON
Trong nhiều ứng dụng, chỉ nhận được một đoạn văn bản tự do là chưa đủ. Bạn có thể cần dữ liệu có cấu trúc để hiển thị thành bảng, lưu vào cơ sở dữ liệu hoặc chuyển tiếp cho một chức năng khác.
Ví dụ, công cụ tạo mô tả sản phẩm có thể cần ba trường gồm tên sản phẩm, mô tả ngắn và danh sách ưu điểm. Nếu yêu cầu mô hình trả về văn bản tùy ý, chương trình sẽ phải tự phân tích và có thể gặp lỗi khi nội dung không đúng định dạng.
Gemini API hỗ trợ các tùy chọn tạo đầu ra có cấu trúc đối với những mô hình và phương thức phù hợp. Khi sử dụng, bạn nên cung cấp schema rõ ràng để mô hình hiểu các trường dữ liệu cần trả về.
Ví dụ yêu cầu dữ liệu có cấu trúc
Với SDK Python, bạn có thể sử dụng Pydantic để mô tả cấu trúc dữ liệu mong muốn. Ví dụ sau minh họa cách yêu cầu Gemini tạo thông tin sản phẩm dưới dạng JSON:
from google import genai
from pydantic import BaseModel
import os
class ProductDescription(BaseModel):
name: str
short_description: str
benefits: list[str]
client = genai.Client(
api_key=os.environ["GEMINI_API_KEY"]
)
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=(
"Tao mo ta mau cho mot binh nuoc giu nhiet. "
"Khong tu suy dien thong so ky thuat."
),
config={
"response_mime_type": "application/json",
"response_schema": ProductDescription,
},
)
product = ProductDescription.model_validate_json(
response.text
)
print(product.model_dump_json(indent=2))
Trong ví dụ này, ProductDescription xác định ba trường dữ liệu. SDK sử dụng schema để hướng dẫn định dạng đầu ra, sau đó Pydantic kiểm tra nội dung JSON trả về theo cấu trúc đã khai báo.
Để sử dụng ví dụ, bạn cần cài thêm Pydantic:
python -m pip install -U pydantic google-genai
Đầu ra có thể bao gồm tên sản phẩm, phần mô tả và danh sách ưu điểm. Tuy nhiên, cấu trúc JSON hợp lệ không đồng nghĩa với việc mọi thông tin bên trong đều chính xác. Bạn vẫn cần kiểm tra dữ liệu, đặc biệt khi kết quả được sử dụng cho hoạt động thương mại, tài chính hoặc những quy trình quan trọng.
Cách quản lý API key Gemini an toàn
API key là một trong những thành phần quan trọng nhất khi triển khai ứng dụng Gemini. Nếu khóa bị lộ, người khác có thể lợi dụng quyền truy cập của dự án để gửi yêu cầu trái phép, tiêu thụ hạn mức hoặc làm phát sinh chi phí ngoài dự kiến.
Bảo vệ API key không chỉ là việc giữ bí mật một chuỗi ký tự. Bạn cần xây dựng quy trình quản lý khóa từ lúc phát triển, thử nghiệm cho đến khi đưa ứng dụng vào hoạt động.
Không đặt API key trong mã nguồn frontend
Đây là nguyên tắc quan trọng nhất đối với website công khai. Nếu viết API key trực tiếp trong JavaScript chạy trên trình duyệt, khóa có thể xuất hiện trong mã nguồn được tải xuống thiết bị người dùng.
Việc đổi tên biến, mã hóa chuỗi hoặc làm rối mã JavaScript không phải là biện pháp bảo mật đáng tin cậy. Nếu trình duyệt cần sử dụng một thông tin bí mật để gọi API, người dùng có khả năng tìm ra thông tin đó.
Giải pháp phù hợp là lưu khóa ở backend, sau đó để frontend gọi API của chính website. Backend có thể kiểm tra người dùng, giới hạn số yêu cầu và quyết định khi nào được phép gọi Gemini.
Sử dụng biến môi trường hoặc hệ thống quản lý bí mật
Trong giai đoạn phát triển, biến môi trường là phương thức đơn giản để tách API key khỏi mã nguồn. Khi triển khai trên máy chủ, bạn nên sử dụng hệ thống quản lý bí mật hoặc chức năng cấu hình biến môi trường do nền tảng lưu trữ cung cấp.
Nếu sử dụng tệp .env để thuận tiện cho việc phát triển cục bộ, hãy thêm tệp này vào .gitignore và không đưa nó vào kho mã nguồn công khai. Chỉ lưu một tệp ví dụ không chứa thông tin bí mật nếu cần hướng dẫn người khác thiết lập dự án.
Không nên ghi API key vào log, thông báo lỗi, hệ thống phân tích hành vi hoặc dữ liệu gửi đến các dịch vụ bên thứ ba không cần thiết.
Giới hạn quyền truy cập và thay khóa khi cần thiết
Hãy sử dụng dự án và khóa phù hợp với từng môi trường, chẳng hạn phát triển, thử nghiệm và sản xuất. Cách phân tách này giúp bạn quản lý quyền truy cập và xác định nguồn phát sinh yêu cầu dễ dàng hơn.
Nếu nền tảng hỗ trợ các biện pháp giới hạn khóa, hãy cấu hình theo hướng dẫn hiện hành và chỉ cấp những quyền thực sự cần thiết. Đồng thời, theo dõi hoạt động sử dụng để phát hiện những dấu hiệu bất thường.
Khi nghi ngờ khóa bị lộ, hãy thu hồi hoặc xoay vòng khóa theo quy trình quản lý của dự án, cập nhật cấu hình trên các môi trường liên quan và kiểm tra nhật ký hoạt động. Không nên chỉ xóa khóa khỏi mã nguồn rồi cho rằng rủi ro đã được xử lý, bởi khóa đó có thể vẫn tồn tại trong lịch sử Git hoặc các bản sao đã phát hành.
Cách kiểm soát chi phí khi sử dụng Gemini API
Chi phí sử dụng Gemini API phụ thuộc vào mô hình, lượng dữ liệu gửi vào, lượng nội dung tạo ra, các tính năng được sử dụng và chính sách giá tại thời điểm gọi API. Một ứng dụng có nhiều người dùng hoặc gửi yêu cầu thường xuyên có thể tiêu thụ tài nguyên nhanh hơn dự kiến nếu không được kiểm soát.
Vì vậy, trước khi triển khai công khai, bạn nên ước tính mức sử dụng dự kiến và xây dựng cơ chế giới hạn phù hợp.
Hiểu cách tính mức sử dụng
Với nhiều mô hình, lượng token đầu vào và đầu ra là các yếu tố quan trọng trong việc xác định chi phí. Token là đơn vị mà mô hình sử dụng để xử lý nội dung, không tương đương chính xác với một từ hoặc một ký tự.
Một yêu cầu gửi kèm lịch sử hội thoại dài, tài liệu lớn hoặc nhiều nội dung đầu vào có thể tiêu thụ nhiều token hơn một câu hỏi ngắn. Tương tự, yêu cầu tạo câu trả lời dài có thể làm tăng lượng token đầu ra.
Một số tính năng hoặc loại dữ liệu có cách tính mức sử dụng riêng. Do đó, không nên áp dụng một công thức giá duy nhất cho mọi mô hình và phương thức API.
Giảm chi phí mà không làm giảm chất lượng quá mức
- Chọn mô hình phù hợp: Không cần sử dụng mô hình đắt hơn cho những nhiệm vụ đơn giản nếu một mô hình khác đáp ứng đủ yêu cầu.
- Giới hạn đầu vào: Không gửi toàn bộ dữ liệu khi ứng dụng chỉ cần một phần thông tin để trả lời.
- Kiểm soát độ dài đầu ra: Đưa ra yêu cầu rõ ràng về độ dài câu trả lời và cấu hình giới hạn đầu ra phù hợp nếu API hỗ trợ.
- Tái sử dụng kết quả: Với những yêu cầu giống nhau và dữ liệu không thay đổi, có thể cân nhắc bộ nhớ đệm để tránh gọi API lặp lại không cần thiết.
- Theo dõi mức sử dụng: Kiểm tra lượng yêu cầu, token và chi phí để phát hiện các đợt tăng bất thường.
- Đặt giới hạn cho người dùng: Giới hạn số yêu cầu theo tài khoản hoặc khoảng thời gian, tùy mục đích ứng dụng.
Nếu website cho phép người dùng tự do gửi câu hỏi đến Gemini, hãy đặc biệt chú ý đến việc giới hạn tốc độ truy cập. Một endpoint công khai không có biện pháp kiểm soát có thể bị lạm dụng để gửi số lượng lớn yêu cầu, làm tăng chi phí và khiến những người dùng khác không thể sử dụng dịch vụ.
Cách xử lý các lỗi thường gặp khi gọi Gemini API
Trong quá trình phát triển, Gemini API có thể trả về lỗi do thông tin xác thực, quyền truy cập, hạn mức, dữ liệu đầu vào hoặc sự cố tạm thời. Thay vì thay đổi mã nguồn một cách ngẫu nhiên, bạn nên dựa vào mã trạng thái HTTP, thông báo lỗi và cấu hình hiện tại để xác định nguyên nhân.
| Lỗi hoặc dấu hiệu | Nguyên nhân có thể xảy ra | Cách xử lý |
|---|---|---|
| 401 Unauthorized | Thông tin xác thực không hợp lệ hoặc thiếu thông tin xác thực cần thiết. | Kiểm tra API key, biến môi trường và cấu hình xác thực theo tài liệu hiện hành. |
| 403 Forbidden | Tài khoản hoặc dự án không có quyền thực hiện yêu cầu. | Kiểm tra quyền truy cập, trạng thái dự án, chính sách tổ chức và quyền sử dụng tính năng. |
| 404 Not Found | Tên mô hình hoặc tài nguyên được gọi không tồn tại trong ngữ cảnh yêu cầu. | Kiểm tra tên mô hình, phương thức API và trạng thái hỗ trợ của mô hình. |
| 429 Too Many Requests | Yêu cầu vượt giới hạn tốc độ, hạn mức sử dụng hoặc một giới hạn liên quan. | Kiểm tra hạn mức, giảm tần suất gọi, áp dụng hàng đợi và thử lại có kiểm soát. |
| 400 Bad Request | Dữ liệu đầu vào hoặc tham số gửi lên không hợp lệ. | Kiểm tra cấu trúc yêu cầu, loại dữ liệu, tham số và định dạng nội dung. |
| 500 hoặc 503 | Dịch vụ gặp lỗi nội bộ hoặc tạm thời không thể đáp ứng. | Kiểm tra trạng thái dịch vụ và thử lại theo cơ chế có giới hạn nếu phù hợp. |
Bảng trên là hướng dẫn chẩn đoán phổ biến, không phải danh sách đầy đủ cho mọi phương thức API. Một số lỗi có thể có nguyên nhân khác nhau tùy dịch vụ, cấu hình và thông tin chi tiết trong phản hồi.
Lỗi API key không hợp lệ
Nếu nhận được thông báo liên quan đến xác thực, hãy kiểm tra xem biến GEMINI_API_KEY có tồn tại trong đúng môi trường chạy chương trình hay không. Bạn cũng cần chắc chắn rằng khóa không có khoảng trắng thừa, không bị cắt khi sao chép và thuộc dự án phù hợp.
Đối với chương trình chạy trong Docker, máy chủ đám mây hoặc môi trường triển khai tự động, hãy kiểm tra cấu hình biến môi trường ở chính môi trường đó. Việc thiết lập biến trong Terminal cá nhân không có nghĩa máy chủ đang chạy ứng dụng cũng tự động nhận được giá trị tương tự.
Lỗi vượt hạn mức hoặc gửi quá nhiều yêu cầu
Khi nhận lỗi 429, không nên gửi lại yêu cầu liên tục ngay lập tức. Cách xử lý phù hợp là kiểm tra loại giới hạn đã bị vượt, giảm tần suất yêu cầu và thực hiện thử lại theo thời gian được chỉ dẫn nếu có.
Nếu lỗi do nhiều người dùng gọi API cùng lúc, bạn có thể cần triển khai hàng đợi, giới hạn số yêu cầu đồng thời hoặc giới hạn số lần sử dụng theo tài khoản. Những biện pháp này giúp tránh việc một lượng truy cập tăng đột biến làm ảnh hưởng toàn bộ ứng dụng.
Không phải mọi lỗi 429 đều có thể giải quyết bằng cách chờ vài giây. Nếu dự án đã chạm hạn mức sử dụng hoặc có điều kiện thanh toán chưa đáp ứng, bạn cần điều chỉnh cấu hình tương ứng thay vì chỉ thử lại.
Lỗi mô hình không được hỗ trợ
Nếu API thông báo không tìm thấy mô hình hoặc không hỗ trợ phương thức được gọi, hãy kiểm tra tên mô hình và phương thức đang sử dụng. Tên mô hình có thể thay đổi theo vòng đời sản phẩm, trong khi một số mô hình chỉ hỗ trợ các chức năng hoặc loại đầu vào nhất định.
Hãy tham khảo danh sách mô hình hiện hành và kiểm tra xem mô hình có hỗ trợ phương thức tạo nội dung mà chương trình đang gọi hay không. Khi thay đổi mô hình, bạn cũng nên chạy lại bộ kiểm thử để bảo đảm chất lượng đầu ra và chi phí vẫn đáp ứng yêu cầu.
Cách sử dụng Gemini API hiệu quả trong dự án thực tế
Việc gọi được API mới chỉ là bước khởi đầu. Để ứng dụng có thể hoạt động ổn định trong thời gian dài, bạn cần quan tâm đến chất lượng câu lệnh, cách quản lý hội thoại, khả năng kiểm soát dữ liệu và quy trình kiểm thử.
Viết câu lệnh rõ ràng và có mục tiêu
Một yêu cầu tốt nên xác định nhiệm vụ, bối cảnh, thông tin đầu vào và định dạng kết quả mong muốn. Nếu chỉ gửi một câu lệnh chung chung, mô hình có thể trả lời quá rộng, thiếu thông tin cần thiết hoặc tạo ra nội dung không phù hợp với cấu trúc ứng dụng.
Ví dụ, thay vì chỉ yêu cầu viết mô tả sản phẩm, bạn có thể xác định độ dài, đối tượng khách hàng, giọng văn và những thông tin không được tự suy diễn. Nếu cần kết quả để lưu vào hệ thống, hãy yêu cầu định dạng dữ liệu rõ ràng và kiểm tra đầu ra trước khi sử dụng.
Quản lý lịch sử hội thoại
Với chatbot, mỗi yêu cầu riêng lẻ có thể không đủ thông tin để duy trì mạch hội thoại. Khi cần ghi nhớ những lượt trao đổi trước đó, ứng dụng phải quản lý lịch sử hội thoại và gửi phần ngữ cảnh cần thiết trong các yêu cầu tiếp theo hoặc sử dụng cơ chế quản lý hội thoại được API hỗ trợ.
Tuy nhiên, không nên gửi toàn bộ lịch sử vô thời hạn. Hội thoại quá dài làm tăng lượng dữ liệu phải xử lý, có thể tăng chi phí và khiến những thông tin cũ không còn liên quan ảnh hưởng đến câu trả lời hiện tại.
Một phương án phù hợp là giữ lại các lượt trao đổi gần nhất, tóm tắt thông tin quan trọng và loại bỏ dữ liệu không cần thiết. Đối với chatbot tư vấn sản phẩm, bạn có thể lưu riêng những thông tin cần thiết như loại sản phẩm khách đang tìm kiếm, thay vì giữ lại mọi câu nói trong toàn bộ phiên.
Không mặc định mọi câu trả lời đều chính xác
Gemini có thể tạo ra câu trả lời tự nhiên nhưng vẫn có khả năng cung cấp thông tin sai, thiếu nguồn hoặc không phù hợp với dữ liệu thực tế. Vì vậy, không nên xem nội dung do AI tạo ra là dữ liệu đã được xác minh.
Nếu ứng dụng cần trả lời dựa trên thông tin doanh nghiệp, sản phẩm hoặc tài liệu nội bộ, hãy thiết kế quy trình cung cấp dữ liệu đáng tin cậy cho mô hình. Bạn cũng nên kiểm tra kết quả trước khi thực hiện những hành động quan trọng, chẳng hạn cập nhật dữ liệu, gửi thông báo hoặc xử lý giao dịch.
Bảo vệ dữ liệu người dùng
Trước khi gửi dữ liệu đến Gemini API, hãy xác định thông tin nào thực sự cần thiết cho nhiệm vụ. Tránh gửi mật khẩu, khóa truy cập, dữ liệu cá nhân nhạy cảm hoặc tài liệu nội bộ không cần thiết vào câu lệnh.
Đối với ứng dụng phục vụ doanh nghiệp, hãy xem xét chính sách dữ liệu, điều khoản dịch vụ, yêu cầu tuân thủ và cấu hình bảo mật phù hợp với loại thông tin được xử lý. Nếu ứng dụng sử dụng dữ liệu do người dùng tải lên, cần có cơ chế kiểm soát quyền truy cập và thời gian lưu trữ hợp lý.
Ngoài ra, nội dung được gửi vào mô hình có thể chứa những chỉ dẫn không đáng tin cậy. Nếu ứng dụng dùng AI để đọc email, tài liệu hoặc trang web, bạn cần phân biệt dữ liệu cần phân tích với chỉ dẫn điều khiển chương trình. Không để nội dung do người dùng cung cấp tự ý kích hoạt các thao tác nhạy cảm hoặc vượt qua quyền kiểm soát của backend.
Những tài liệu chính thức nên tham khảo khi phát triển Gemini API
Do mô hình, SDK, hạn mức và chính sách sử dụng có thể thay đổi, bạn nên kiểm tra tài liệu chính thức trong quá trình xây dựng và bảo trì ứng dụng. Các nguồn sau cung cấp thông tin hữu ích để tiếp tục phát triển từ những ví dụ trong bài viết.
- Tài liệu Gemini API: Hướng dẫn tổng quan, phương thức gọi API và các tính năng được hỗ trợ.
- Trang quản lý API key: Tạo và quản lý khóa truy cập theo quyền của tài khoản và dự án.
- Hướng dẫn bắt đầu nhanh: Các bước thiết lập môi trường và gửi yêu cầu đầu tiên.
- Danh sách mô hình: Kiểm tra tên mô hình, khả năng hỗ trợ và trạng thái phát hành.
- Bảng giá dịch vụ: Tìm hiểu cách tính chi phí theo mô hình và loại sử dụng.
- Giới hạn sử dụng: Tìm hiểu hạn mức và các giới hạn áp dụng cho dự án.
- Structured Outputs: Hướng dẫn tạo kết quả theo cấu trúc dữ liệu xác định.
Kết luận
Cách dùng Gemini tạo API gồm các bước chính: truy cập Google AI Studio, tạo API key, thiết lập môi trường lập trình, sử dụng SDK hoặc REST API để gửi yêu cầu và xử lý kết quả trả về. Với Python hoặc JavaScript, bạn có thể nhanh chóng xây dựng chương trình thử nghiệm trước khi phát triển thành một chức năng hoàn chỉnh.
Nếu mục tiêu là tích hợp Gemini vào website, hãy xây dựng backend để bảo vệ API key, kiểm tra dữ liệu đầu vào và kiểm soát số lượng yêu cầu. Khi ứng dụng phát triển, việc lựa chọn mô hình phù hợp, theo dõi chi phí, xử lý lỗi và đánh giá chất lượng phản hồi sẽ quyết định mức độ ổn định của hệ thống.
Đối với người mới, cách tiếp cận hiệu quả là bắt đầu bằng một chức năng nhỏ, chẳng hạn API trả lời câu hỏi hoặc tạo mô tả sản phẩm. Sau khi kiểm tra được độ chính xác, tốc độ và chi phí, bạn có thể mở rộng sang chatbot, xử lý tài liệu hoặc những quy trình tự động hóa phức tạp hơn.
- 0 Bình luận
Email, Điện thoại của bạn sẽ không được hiển thị công khai. Các trường bắt buộc được đánh dấu *
