Sử dụng khoá API Gemini

Để sử dụng Gemini API, bạn phải xác thực các yêu cầu của mình. Bạn có thể xác thực bằng khoá API tiêu chuẩn hoặc khoá API uỷ quyền.

Tạo hoặc xem khoá Gemini API

Các loại khoá API: khoá tiêu chuẩn và khoá uỷ quyền

Khoá API cung cấp quyền truy cập vào Gemini API, nhưng các đặc điểm bảo mật của khoá API khác nhau. Gemini API đang chuyển từ khoá API tiêu chuẩn sang khoá uỷ quyền để cải thiện tính bảo mật:

  • Khoá API tiêu chuẩn: Liên kết các yêu cầu với một dự án Google Cloud cho mục đích thanh toán và hạn mức. Khoá tiêu chuẩn không xác định được phương thức gọi, điều này giới hạn mức độ chi tiết của quyền và quyền kiểm soát truy cập mà khoá có thể hỗ trợ.
  • Khoá uỷ quyền (auth): Liên kết trực tiếp với một tài khoản dịch vụ Google Cloud. Khi bạn sử dụng khoá uỷ quyền, các yêu cầu của bạn sẽ được xử lý theo danh tính của tài khoản dịch vụ ràng buộc đó, cho phép kiểm soát quyền truy cập một cách chi tiết. Theo mặc định, khoá uỷ quyền chỉ được dùng cho Generative Language API (Gemini API) và có thể nhanh chóng thực thi biện pháp xử lý khoá bị rò rỉ để ngăn chặn việc sử dụng khoá bị rò rỉ mà hệ thống của chúng tôi phát hiện được.

Để đảm bảo việc sử dụng an toàn, Gemini API sẽ chuyển từ khoá tiêu chuẩn sang khoá xác thực:

  • Khoá xác thực mặc định: Kể từ ngày 28 tháng 5 năm 2026, tất cả khoá API mới được tạo trong Google AI Studio sẽ tự động được tạo dưới dạng khoá xác thực.
  • Từ chối khoá không bị hạn chế: Gemini API từ chối các yêu cầu từ khoá tiêu chuẩn không bị hạn chế. Các khoá API tiêu chuẩn có áp dụng quy định hạn chế rõ ràng vẫn tiếp tục hoạt động. Quy định hạn chế này ngăn chặn việc sử dụng trái phép các khoá có thể được chia sẻ công khai hoặc liên kết với các dịch vụ khác.

Quản lý khoá API trong Google AI Studio

Bạn có thể quản lý các dự án và khoá của mình ngay trong Google AI Studio.

Dự án trên Google Cloud

Mỗi khoá Gemini API đều được liên kết với một dự án trên Google Cloud. Các dự án trên Google Cloud quản lý thông tin thanh toán, cộng tác viên và quyền. Google AI Studio cung cấp một giao diện gọn nhẹ để truy cập vào các dự án này.

  • Dự án mặc định: Nếu bạn là người dùng mới, Google AI Studio sẽ tự động tạo một dự án trên đám mây Google Cloud mặc định và khoá API sau khi bạn chấp nhận Điều khoản dịch vụ. Bạn có thể đổi tên dự án này bằng cách chuyển đến chế độ xem Dự án trong trang tổng quan.
  • Dự án hiện có: Nếu bạn đã có tài khoản Google Cloud, AI Studio sẽ không tạo dự án mặc định. Thay vào đó, bạn phải nhập các dự án hiện có.

Đang nhập dự án

Theo mặc định, Google AI Studio không hiển thị tất cả dự án của bạn trên Google Cloud. Bạn phải nhập các dự án mà bạn muốn sử dụng:

  1. Truy cập vào Google AI Studio.
  2. Mở Trang tổng quan trong bảng điều khiển bên trái rồi chọn Dự án.
  3. Nhấp vào nút Import projects (Nhập dự án).
  4. Tìm và chọn dự án trên Google Cloud mà bạn muốn nhập, sau đó nhấp vào Nhập.
  5. Sau khi nhập, hãy chuyển đến trang Khoá API trong trang tổng quan để tạo khoá trong dự án đó.

Khắc phục sự cố về quyền tạo khoá

Nếu nút Tạo khoá API không hoạt động và hiển thị thông báo: "Bạn không có quyền tạo khoá trong dự án này", tức là bạn không có các quyền cần thiết trong IAM.

Hãy yêu cầu quản trị viên dự án trên đám mây hoặc quản trị viên tổ chức của bạn trên Google Cloud cấp cho bạn một vai trò có các quyền sau (chẳng hạn như Người chỉnh sửa dự án):

  • resourcemanager.projects.get: Cho phép AI Studio xác minh dự án.
  • apikeys.keys.create: Cho phép tạo khoá.
  • serviceusage.services.enable: Đảm bảo Generative Language API được bật.
  • iam.serviceAccounts.create: Bắt buộc để tạo tài khoản dịch vụ được liên kết.
  • iam.serviceAccountApiKeyBindings.create: Liên kết tài khoản dịch vụ với khoá API.

Nếu không có quyền quản trị, bạn có thể tạo một dự án mới trên Google Cloud không liên kết với tổ chức nào để tạo khoá.

Khoá không xác định trên trang Mức sử dụng

Trang Mức sử dụng trong Google AI Studio nhóm các yêu cầu mà trang này không thể so khớp với một khoá API có tên trong dự án trong mục (khoá không xác định). Trong đó bao gồm cả những khoá đã bị xoá hơn 30 ngày trước, khoá không có tên hiển thị và yêu cầu được thực hiện bằng thông tin xác thực khác, chẳng hạn như OAuth.

Tạo khoá trong Google Cloud Console

Google AI Studio chỉ hiển thị những khoá không bị hạn chế hoặc bị hạn chế đối với Gemini API. Nếu bạn không thể sử dụng AI Studio hoặc muốn quản lý tất cả khoá API ở một nơi, hãy làm theo tài liệu của Cloud về cách tạo khoá API. Để tạo khoá API Gemini, bạn cần liên kết khoá đó với một tài khoản dịch vụ.

Thiết lập môi trường

Sau khi bạn có khoá, hãy định cấu hình môi trường để sử dụng khoá đó một cách an toàn trong ứng dụng của bạn.

Cách 1: Sử dụng biến môi trường (nên dùng)

Đặt biến môi trường GEMINI_API_KEY hoặc GOOGLE_API_KEY. Thư viện ứng dụng Gemini API sẽ tự động phát hiện và sử dụng các biến này. Nếu bạn đặt cả hai chính sách thì GOOGLE_API_KEY sẽ được ưu tiên áp dụng.

Chọn hệ điều hành để đặt biến:

Linux/macOS – Bash

Xác minh xem bạn có tệp cấu hình bash hay không:

~/.bashrc

Nếu chưa có, hãy tạo một tệp và mở tệp đó:

touch ~/.bashrc && open ~/.bashrc

Thêm lệnh xuất ở cuối tệp:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

Lưu tệp, sau đó áp dụng các thay đổi:

source ~/.bashrc

macOS – Zsh

Xác minh xem bạn có tệp cấu hình zsh hay không:

~/.zshrc

Nếu chưa có, hãy tạo một tệp và mở tệp đó:

touch ~/.zshrc && open ~/.zshrc

Thêm lệnh xuất:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

Lưu tệp, sau đó áp dụng các thay đổi:

source ~/.zshrc

Windows

  1. Tìm "Biến môi trường" trong thanh tìm kiếm của Windows.
  2. Nhấp vào Environment Variables (Biến môi trường) trong hộp thoại System Properties (Thuộc tính hệ thống).
  3. Trong User variables (Biến người dùng) hoặc System variables (Biến hệ thống), hãy nhấp vào New... (Mới...).
  4. Đặt tên biến thành GEMINI_API_KEY và đặt giá trị thành khoá API của bạn.
  5. Nhấp vào OK để lưu. Mở một phiên dòng lệnh mới để tải biến.

Cách 2: Cung cấp khoá API một cách rõ ràng trong mã

Bạn có thể truyền khoá API một cách rõ ràng khi khởi chạy ứng dụng. Chỉ làm việc này nếu bạn không thể sử dụng biến môi trường.

Python

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Explain how AI works in a few words",
  });
  console.log(interaction.output_text);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = Client.builder().apiKey("YOUR_API_KEY").build();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Explain how AI works in a few sentences."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey: "YOUR_API_KEY",
    })
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Explain how AI works in a few sentences."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -X POST \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain how AI works in a few words"
  }'

Quản lý bảo mật và bí mật

Hãy bảo mật khoá Gemini API như mật khẩu. Nếu bị xâm phạm, những người khác có thể sử dụng hạn mức của dự án, phát sinh phí thanh toán ngoài dự kiến và truy cập vào tài nguyên riêng tư.

Quy tắc bảo mật quan trọng

  • Giữ bí mật khoá: Tuyệt đối không đưa khoá API vào hệ thống kiểm soát nguồn như Git.
  • Không bao giờ hiển thị khoá phía máy khách trong phiên bản chính thức: Không cố định giá trị khoá API trực tiếp trong ứng dụng web hoặc ứng dụng di động. Người dùng có thể trích xuất các khoá được biên dịch trong mã phía máy khách. Để bảo mật các ứng dụng phía máy khách, hãy chạy một máy chủ proxy phụ trợ để thực hiện các lệnh gọi API thực tế.

Các phương pháp hay nhất để quản lý thông tin bí mật

  • Biến môi trường: Đọc khoá từ biến môi trường thay vì tệp cấu hình.
  • Secret Manager: Đối với môi trường thực tế, hãy lưu trữ khoá của bạn trong một kho lưu trữ bí mật an toàn, chẳng hạn như Google Cloud Secret Manager.
  • Cảnh báo thanh toán: Thiết lập cảnh báo thanh toán trong Google Cloud Console để thông báo cho bạn nếu mức sử dụng hoặc chi phí tăng đột biến.

Danh sách kiểm tra để ứng phó với sự cố rò rỉ

Nếu bạn nghi ngờ khoá API của mình bị rò rỉ, hãy làm như sau:

  1. Tạo khoá mới: Tạo khoá thay thế trong Google AI Studio hoặc Cloud Console.
  2. Cập nhật ứng dụng: Triển khai mã bằng khoá mới.
  3. Vô hiệu hoá hoặc xoá khoá bị xâm phạm: Vô hiệu hoá khoá bị rò rỉ trong Cloud Console sau khi xác minh khoá mới. Đừng xoá khoá cũ cho đến khi khoá mới hoạt động hoàn toàn để tránh thời gian ngừng hoạt động của ứng dụng.
  4. Kiểm tra mức sử dụng: Kiểm tra nhật ký thanh toán và mức sử dụng API trong Google Cloud Console để xác định hoạt động trái phép.

Hạn chế và bảo mật khoá

Việc thêm các quy tắc hạn chế vào khoá API sẽ giảm thiểu thiệt hại tiềm ẩn nếu khoá bị xâm phạm.

Áp dụng quy định hạn chế về nguồn gốc yêu cầu

Các quy định hạn chế về nguồn gốc sẽ giới hạn những địa chỉ IP, trang web hoặc ứng dụng có thể sử dụng khoá của bạn.

  1. Chuyển đến trang thông tin xác thực của Google Cloud Console.
  2. Chọn dự án của bạn rồi nhấp vào tên của khoá API mà bạn muốn hạn chế.
  3. Trong mục Application restrictions (Hạn chế cho ứng dụng), chọn IP addresses (Địa chỉ IP) (hoặc loại hạn chế phù hợp với môi trường của bạn).
  4. Chỉ định dải hoặc địa chỉ IP được phép, sau đó nhấp vào Lưu.

Bảo mật khoá API tiêu chuẩn không bị hạn chế

Để tiếp tục sử dụng Gemini API, bạn phải bảo mật mọi khoá không bị hạn chế.

Phương thức A: Chỉ hạn chế khoá cho Gemini API (AI Studio)

Nếu bạn chỉ sử dụng khoá cho Gemini API, hãy bảo mật khoá đó ngay trong AI Studio:

  1. Trên trang Khoá API trong Google AI Studio, hãy tìm các khoá được đánh dấu bằng nhãn Không bị hạn chế.
  2. Di chuột lên nhãn rồi nhấp vào Thêm quy định hạn chế trong hộp thoại.
  3. Chọn Chỉ hạn chế đối với Gemini API.
  4. Nhấp vào Giới hạn khoá để xác nhận.

Phương thức B: Hạn chế khoá cho các dịch vụ khác (Google Cloud Console)

Nếu khoá được chia sẻ với các API khác của Google (không nên), hãy hạn chế khoá đó trong Cloud Console. Lưu ý: Các yêu cầu Gemini API sử dụng khoá này sẽ không thành công sau khi áp dụng các quy định hạn chế này.

  1. Truy cập vào trang thông tin xác thực của Google Cloud Console.
  2. Chọn dự án và khoá API.
  3. Trong mục API restrictions (Hạn chế cho API), hãy sử dụng trình đơn thả xuống Select API restrictions (Chọn hạn chế cho API) để chọn những API mà bạn muốn khoá này truy cập. Đừng chọn Generative Language API.
  4. Nhấp vào Lưu. Hãy tạo một khoá riêng biệt, có giới hạn trong AI Studio để tiếp tục sử dụng Gemini API.

Đã chặn các khoá không hoạt động

Kể từ ngày 7 tháng 5 năm 2026, Gemini API sẽ chặn các khoá API không bị hạn chế đã không hoạt động trong một thời gian dài. Những khoá này có thẻ Bị chặn trong AI Studio. Bạn phải tạo một khoá mới hoặc sử dụng một khoá bị hạn chế hiện có để tiếp tục.

Di chuyển sang khoá xác thực

Hãy làm theo các bước sau để tạo khoá API xác thực mới và cập nhật ứng dụng:

  1. Truy cập vào trang Khoá API của AI Studio.
  2. Kiểm tra cột Loại khoá để xác định mọi khoá được liệt kê là Chuẩn.
  3. Nhấp vào Tạo khoá API để tạo khoá mới. Tất cả khoá mới được tạo trong AI Studio đều tự động được tạo dưới dạng khoá xác thực.
  4. Sao chép khoá API xác thực mới.
  5. Cập nhật mã xử lý ứng dụng, biến môi trường và mọi cấu hình triển khai để sử dụng khoá API xác thực mới.
  6. Kiểm thử ứng dụng để xác nhận rằng ứng dụng hoạt động đúng cách với khoá mới.
  7. Sau khi xác minh, hãy xoá hoặc thu hồi khoá lưu lượng truy cập cũ để tránh bị sử dụng sai mục đích.

Các điểm hạn chế

Google AI Studio áp dụng các giới hạn sau đây về việc quản lý dự án và khoá:

  • Bạn có thể tạo tối đa 10 dự án cùng một lúc trên trang Dự án của Google AI Studio.
  • Trang Khoá API và Dự án hiển thị tối đa 100 khoá và 50 dự án.
  • Chỉ những khoá API không bị hạn chế hoặc bị hạn chế cụ thể đối với Generative Language API (Gemini API) mới xuất hiện.

Để quản lý dự án nâng cao hoặc sửa đổi khoá có các quy định hạn chế khác, hãy sử dụng trang thông tin xác thực của Google Cloud Console.