Con đường ngắn nhất để tích hợp Gemini API là: mở AI Studio bằng tài khoản Google, tạo một API Key, cài SDK và gửi yêu cầu generateContent đầu tiên. Nếu thuận lợi, toàn bộ quá trình không quá hai mươi phút. Chỗ dễ bị kẹt thật sự không nằm ở "gọi được hay không", mà ở việc chọn sai điểm vào, viết sai ID mô hình, nhầm giữa hạn mức miễn phí và gói trả phí, cũng như đặt khóa vào nơi không nên đặt.

Bài viết đi theo đúng thứ tự tích hợp: phân biệt AI Studio và Vertex AI trước, rồi tạo khóa, cài SDK, gửi yêu cầu curl và Python, sau đó xử lý cách đặt tên mô hình, chỉ dẫn hệ thống, truyền phát và thiết lập an toàn, cuối cùng liệt kê nguyên nhân thường gặp của lỗi 400, 403, 429 và danh sách kiểm tra an toàn khóa.

Lưu ý: Google và Gemini là nhãn hiệu của Google LLC. Tên mô hình, hạn mức miễn phí và quy tắc tính phí có thể điều chỉnh; bài viết lấy quy trình phổ biến tính đến tháng 10 năm 2026 làm ví dụ, chi tiết căn cứ tài liệu chính thức của Google và trang bảng giá mô hình trên site.

1. Phân biệt AI Studio và Vertex AI trước

Gemini API có hai điểm vào phổ biến, hệ thống tài khoản và cách quản lý khác nhau; chọn sai sẽ phải làm lại về quyền hoặc thanh toán.

Hạng mục so sánh Google AI Studio Vertex AI
Điểm vào Bảng điều khiển trên trình duyệt, hướng tới nhà phát triển dùng thử nhanh Bảng điều khiển Google Cloud, hướng tới sử dụng theo dự án
Yêu cầu tài khoản Tài khoản Google là bắt đầu được Dự án Cloud, tài khoản thanh toán và quyền IAM
Thông tin xác thực API Key do AI Studio tạo Tài khoản dịch vụ hoặc khóa được kiểm soát, kèm IAM
Tính phí Gói miễn phí và gói trả phí song song Thanh toán theo dự án Cloud
Khu vực và dữ liệu Theo điều khoản AI Studio Có thể chọn khu vực, ràng buộc bởi điều khoản Cloud và cấu hình dự án
Phù hợp Nguyên mẫu, học tập, kiểm chứng quy mô nhỏ Hệ thống sản xuất, đội có yêu cầu cao về kiểm toán và quyền hạn

Nhà phát triển cá nhân và đội nhỏ thường dùng AI Studio để chạy thông quy trình trước; khi liên quan đến hợp đồng, khu vực dữ liệu, kiểm toán thống nhất mới cân nhắc Vertex AI. Không trộn khóa, hạn mức và hóa đơn của hai bên, cũng đừng dùng khóa AI Studio để gọi giao diện Vertex AI.

2. Tạo API Key đầu tiên

  1. Đăng nhập Google AI Studio bằng tài khoản Google.
  2. Vào trang quản lý API Key, chọn tạo API Key.
  3. Chọn một dự án Google Cloud; nếu chưa có, tạo mới theo hướng dẫn trên trang.
  4. Sao chép khóa được tạo, lưu ngay vào biến môi trường máy chủ hoặc trình quản lý mật khẩu.
  5. Gửi một tin nhắn thử trong Playground để xác nhận khóa và mô hình dùng được.
  6. Đặt tên khóa thể hiện mục đích, thuận tiện luân chuyển và thu hồi sau này.

AI Studio cung cấp gói miễn phí để dùng thử; mô hình khả dụng, tốc độ yêu cầu và hạn mức thay đổi theo tài khoản và thời điểm. Sau khi bật thanh toán cho dự án Cloud liên kết, có thể chuyển sang gói trả phí. Đừng coi con số hạn mức trong bài cũ là cam kết hiện tại; mọi thứ căn cứ hiển thị thực tế trên bảng điều khiển và mô tả chính thức.

Sau khi tạo khóa, xác nhận trước khóa thuộc dự án Cloud nào. Hạn mức thường tính theo dự án; trộn kiểm thử với sản xuất có thể khiến người khác dùng hết hạn mức. Khi cần hạn mức cao hơn, hãy bật thanh toán trong dự án Cloud, đặt cảnh báo ngân sách, rồi quan sát mức dùng thực tế một tuần.

3. Cài SDK và gửi yêu cầu đầu tiên

Môi trường Python nên dùng phiên bản 3.10 trở lên và cài SDK chính thức trong môi trường ảo.

python3 -m venv .venv
source .venv/bin/activate
pip install -U google-genai
export GEMINI_API_KEY="khoa-cua-ban"

Dùng curl trước để loại trừ yếu tố SDK. ID mô hình dùng ký tự giữ chỗ; tên thực tế lấy từ danh sách mô hình hoặc trang giá trên site.

curl "https://generativelanguage.googleapis.com/v1beta/models/<MODEL_ID>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Giải thích bằng một câu thế nào là cổng API"}]}
    ],
    "generationConfig": {"maxOutputTokens": 256, "temperature": 0.7}
  }'

Sau khi curl trả về 200, chuyển sang SDK Python:

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="<MODEL_ID>",
    contents="Giải thích bằng một câu thế nào là cổng API",
)
print(resp.text)

model phải ghi ID mô hình đầy đủ, đừng chỉ ghi tên dòng. Các mô hình khác nhau hỗ trợ loại đầu vào và tham số khác nhau; viết sai sẽ thể hiện ở lỗi 400 hoặc 404.

4. Đặt tên mô hình, chỉ dẫn hệ thống và tham số sinh

ID mô hình Gemini thường gồm tên dòng và phiên bản. Cách ổn nhất là truy vấn danh sách mô hình tài khoản hiện tại có thể dùng:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Đừng đoán những mẫu không có trong danh sách. Khi chọn, phân công theo tác vụ: tác vụ nhẹ dùng mức độ trễ thấp, suy luận phức tạp và tài liệu dài mới dùng mức cao; mức và giá cụ thể căn cứ trang bảng giá mô hình.

ID mô hình cập nhật theo phiên bản; ID cũ có thể bị đánh dấu ngừng dùng hoặc gỡ bỏ. Hãy đưa tên mô hình vào tệp cấu hình, đừng rải rác trong mã; khi nâng cấp chỉ sửa một chỗ và dùng mẫu hồi quy để xác nhận đầu ra không thay đổi rõ rệt.

Chỉ dẫn hệ thống dùng để cố định vai trò và quy tắc đầu ra, phù hợp với dịch thuật, trích xuất, chăm sóc khách hàng:

resp = client.models.generate_content(
    model="<MODEL_ID>",
    contents="Dịch câu này sang tiếng Anh: tích hợp hoàn tất",
    config={"system_instruction": "Bạn là người dịch tài liệu kỹ thuật, chỉ xuất bản dịch."},
)

Các tham số sinh thường dùng gồm temperature, maxOutputTokens và topP. Khi cần kết quả có cấu trúc, có thể để mô hình trả JSON và phân tích, kiểm tra trong mã; đừng giả định mô hình luôn tuân thủ định dạng, cần viết trước logic thử lại và dự phòng.

5. Truyền phát và thiết lập an toàn

Truyền phát phù hợp với giao diện trò chuyện và câu trả lời dài. Giao diện REST thêm :streamGenerateContent sau phương thức và kèm alt=sse; SDK Python dùng generate_content_stream:

for chunk in client.models.generate_content_stream(
    model="<MODEL_ID>",
    contents="Trình bày ba điểm về giới hạn tốc độ",
):
    print(chunk.text, end="")

Thiết lập an toàn có thể điều chỉnh ngưỡng chặn theo danh mục; các danh mục phổ biến gồm quấy rối, thù địch, nội dung khiêu dâm và nội dung nguy hiểm. Ngưỡng mặc định phù hợp với đa số nghiệp vụ; hạ ngưỡng sẽ nới rộng phạm vi nội dung, cần đánh giá cùng chính sách sản phẩm và quy định địa phương. Đừng tắt toàn bộ thiết lập an toàn chỉ để "qua bài kiểm tra", đặc biệt với sản phẩm hướng tới công chúng.

6. Xử lý lỗi 400, 403, 429

Mã trạng thái Nguyên nhân thường gặp Hướng xử lý
400 Cấu trúc JSON sai, tham số không hỗ trợ, ID mô hình không khớp giao diện Kiểm tra từng trường trong phần thân yêu cầu, dùng yêu cầu tối thiểu trước
403 Khóa không hợp lệ hoặc bị hạn chế, API chưa bật, dự án hoặc khu vực bị giới hạn Đổi khóa để kiểm chứng, kiểm tra quyền dự án và trạng thái tài khoản
404 ID mô hình viết sai, phiên bản hoặc đường dẫn giao diện không đúng Xem danh sách mô hình, xác nhận v1beta và tên phương thức
429 Gói miễn phí hết hạn mức, quá nhiều yêu cầu mỗi phút, đồng thời quá cao Lùi theo cấp số nhân, giảm đồng thời, đánh giá gói trả phí
500/503 Sự cố tạm thời phía máy chủ Thử lại có giới hạn; nếu tiếp tục thất bại thì hạ cấp hoặc đổi tuyến

Đừng gửi lại ngay khi gặp 429. Cách đúng là lùi kèm nhiễu ngẫu nhiên, đặt số lần thử lại tối đa và ghi yêu cầu thất bại vào nhật ký. Giới hạn tốc độ của gói miễn phí thường chặt hơn; kiểm thử tải và tác vụ hàng loạt cần bố trí riêng.

7. Danh sách kiểm tra an toàn khóa

  • Khóa chỉ đặt trong biến môi trường máy chủ hoặc dịch vụ quản lý bí mật, không vào giao diện, không vào kho mã, không vào lịch sử trò chuyện.
  • Sản xuất, kiểm thử, phát triển mỗi môi trường một khóa, tách hạn mức và quyền theo môi trường.
  • Luân chuyển định kỳ, thu hồi ngay khi nhân sự nghỉ việc hoặc dự án kết thúc.
  • Giới hạn API mà khóa được gọi trong bảng điều khiển đám mây, thu hẹp ảnh hưởng khi rò rỉ.
  • Bật cảnh báo mức dùng; khi phát hiện gọi bất thường, dừng khóa trước rồi điều tra.
  • Không để lộ khóa đầy đủ trong ảnh chụp, ghi màn hình và phiếu hỗ trợ.

8. Tích hợp Gemini qua điểm vào tương thích OpenAI

Nếu đội đã có SDK OpenAI và toàn bộ mã gọi, có thể dùng điểm vào tương thích OpenAI của ZSQH AI Gateway với Base URL https://ai.zhongshangqihang.com/v1; chỉ cần đổi ba chỗ base_url, api_key và model:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="<ten-mo-hinh-Gemini-tren-trang-gia>",
    messages=[{"role": "user", "content": "Chỉ trả lời OK"}],
)
print(resp.choices[0].message.content)

Cách này phù hợp với đội cần hóa đơn đa mô hình thống nhất, thanh toán bằng nhân dân tệ và môi trường mạng trong nước. Tham số gốc của Gemini và các trường đa phương tiện không được tương thích hoàn toàn; hãy kiểm chứng từng mục bằng yêu cầu thật trước khi chuyển. Trang đăng ký ở đây; mô hình và giá căn cứ trang bảng giá mô hình.

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

Gemini API có hạn mức miễn phí không?

AI Studio có gói miễn phí, nhưng mô hình khả dụng, tốc độ và hạn mức có thể thay đổi, đồng thời điều khoản dữ liệu có thể khác gói trả phí. Nguyên mẫu có thể dùng gói miễn phí; nghiệp vụ chính thức nên đánh giá lại hạn mức và chi phí theo gói trả phí.

API Key bị lộ thì làm gì?

Trước hết thu hồi hoặc luân chuyển khóa trong bảng điều khiển, sau đó xem nhật ký sử dụng để xác định phạm vi gọi bất thường, cuối cùng điều tra kênh rò rỉ. Chỉ xóa khóa trong mã là chưa đủ; thông tin xác thực đã lộ phải coi như mất hiệu lực.

Mạng trong nước gọi thẳng Gemini API được không?

Chất lượng tuyến tùy khu vực và nhà mạng, có thể gặp quá thời gian hoặc kết nối thất bại. Cách phổ biến là đặt yêu cầu trên máy chủ truy cập ổn định, hoặc dùng cổng hỗ trợ giao diện tương thích OpenAI; giới hạn cụ thể căn cứ tuyến thực tế và mô tả chính thức.

Vì sao curl thông mà SDK Python báo lỗi?

Trước hết xem phiên bản SDK và phụ thuộc có mới nhất không, sau đó xác nhận cách viết model, thiết lập proxy và biến môi trường có nhất quán. Khi SDK báo 404, tập trung kiểm tra ID mô hình và đường dẫn giao diện, đừng đổi nhiều biến cùng lúc.

Có thể gọi Gemini API trực tiếp bằng SDK OpenAI không?

Google cung cấp điểm vào tương thích OpenAI, các cổng trong nước cũng thường có lớp tương thích, nhưng phạm vi hỗ trợ tham số khác nhau. Đa phương tiện, gọi công cụ và đầu ra có cấu trúc phải kiểm chứng bằng yêu cầu thật, không thể giả định hoàn toàn tương đương.

Bước tiếp theo

Hãy chạy thông yêu cầu tối thiểu theo quy trình trong bài trước, rồi mới tích hợp nhật ký nghiệp vụ, thử lại và giám sát mức dùng. Nếu cần quản lý mức gọi Gemini và các mô hình khác, hóa đơn nhân dân tệ và quyền khóa trong một bảng điều khiển, có thể đăng ký ZSQH AI Gateway; giá xem tại bảng giá mô hình.

Đọc thêm: