Sử dụng khoá API Gemini

Để sử dụng Gemini API, bạn cần có khoá API. Trang này trình bày cách tạo và quản lý khoá trong Google AI Studio, cũng như cách thiết lập môi trường để sử dụng các khoá đó trong mã.

Tạo hoặc xem Khoá Gemini API

Khoá API

Bạn có thể tạo và quản lý tất cả Khoá Gemini API trên trang Google AI Studio Khoá API.

Sau khi có khoá API, bạn có các lựa chọn sau để kết nối với Gemini API:

• Đặt khoá API làm biến môi trường
• Cung cấp khoá API một cách rõ ràng

Để kiểm thử ban đầu, bạn có thể mã hoá cứng khoá API, nhưng chỉ nên làm như vậy tạm thời vì không an toàn. Bạn có thể tìm thấy các ví dụ về cách mã hoá cứng khoá API trong phần Cung cấp khoá API một cách rõ ràng.

Dự án trên Google Cloud

Dự án trên Google Cloud là nền tảng cơ bản để sử dụng các dịch vụ của Google Cloud (chẳng hạn như Gemini API), quản lý hoạt động thanh toán và kiểm soát cộng tác viên cũng như quyền. Google AI Studio cung cấp một giao diện đơn giản cho các dự án trên Google Cloud.

Nếu chưa tạo dự án nào, bạn phải tạo một dự án mới hoặc nhập một dự án từ Google Cloud vào Google AI Studio. Trang Dự án trong Google AI Studio sẽ hiển thị tất cả các khoá có đủ quyền để sử dụng Gemini API. Hãy tham khảo phần nhập dự án để biết hướng dẫn.

Dự án mặc định

Đối với người dùng mới, sau khi chấp nhận Điều khoản dịch vụ, Google AI Studio sẽ tạo một Dự án trên Google Cloud và Khoá API mặc định để dễ sử dụng. Bạn có thể đổi tên dự án này trong Google AI Studio bằng cách chuyển đến khung hiển thị Dự án trong Trang tổng quan, nhấp vào nút cài đặt 3 dấu chấm bên cạnh một dự án rồi chọn Đổi tên dự án. Người dùng hiện tại hoặc người dùng đã có Tài khoản Google Cloud sẽ không có dự án mặc định được tạo.

Nhập dự án

Mỗi khoá Gemini API đều được liên kết với một dự án trên đám mây của Google. Theo mặc định, Google AI Studio không hiển thị tất cả Dự án trên đám mây. Bạn phải nhập các dự án mình muốn bằng cách tìm kiếm tên hoặc mã dự án trong hộp thoại Nhập dự án. Để xem danh sách đầy đủ các dự án mà bạn có quyền truy cập, hãy truy cập vào Cloud Console.

Nếu bạn chưa nhập dự án nào, hãy làm theo các bước sau để nhập một dự án trên Google Cloud và tạo khoá:

1. Chuyển đến Google AI Studio.
2. Mở Trang tổng quan từ bảng điều khiển bên trái.
3. Chọn Dự án.
4. Chọn nút Nhập dự án trên trang Dự án.
5. Tìm kiếm và chọn dự án trên Google Cloud mà bạn muốn nhập rồi chọn nút Nhập.

Sau khi nhập một dự án, hãy chuyển đến trang Khoá API trong trình đơn Trang tổng quan rồi tạo khoá API trong dự án mà bạn vừa nhập.

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

Sau đây là các điểm hạn chế khi quản lý khoá API và dự án trên Google Cloud trong Google AI Studio.

• 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.
• Bạn có thể đặt tên và đổi tên dự án cũng như khoá.
• Các 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 có quy tắc hạn chế hoặc bị hạn chế đối với Generative Language API mới được hiển thị.

Để có thêm quyền truy cập quản lý vào các dự án của bạn, bao gồm cả việc sửa đổi và hạn chế khoá API, hãy truy cập vào trang thông tin xác thực của Google Cloud Console. Trong Cloud Console, bạn có thể chọn dự án, nhấp vào một khoá API hiện có, sau đó hạn chế khoá đó đối với Generative Language API.

Đặt khoá API làm biến môi trường

Nếu bạn đặt biến môi trường GEMINI_API_KEY hoặc GOOGLE_API_KEY, thì khoá API sẽ tự động được ứng dụng chọn khi sử dụng một trong các thư viện Gemini API. Bạn nên chỉ đặt một trong các biến đó, nhưng nếu đặt cả hai, thì GOOGLE_API_KEY sẽ được ưu tiên.

Nếu đang sử dụng API REST hoặc JavaScript trên trình duyệt, bạn sẽ cần cung cấp khoá API một cách rõ ràng.

Sau đây là cách bạn có thể đặt khoá API cục bộ làm biến môi trường GEMINI_API_KEY với các hệ điều hành khác nhau.

~/.bashrc

touch ~/.bashrc
open ~/.bashrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.bashrc

~/.zshrc

touch ~/.zshrc
open ~/.zshrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.zshrc

Cung cấp khoá API một cách rõ ràng

Trong một số trường hợp, bạn có thể muốn cung cấp khoá API một cách rõ ràng. Ví dụ:

• Bạn đang thực hiện một lệnh gọi API đơn giản và thích mã hoá cứng khoá API.
• Bạn muốn kiểm soát rõ ràng mà không phải dựa vào việc thư viện Gemini API tự động phát hiện các biến môi trường
• Bạn đang sử dụng một môi trường không hỗ trợ các biến môi trường (ví dụ: web) hoặc bạn đang thực hiện các lệnh gọi REST.

Dưới đây là các ví dụ về cách bạn có thể cung cấp khoá API một cách rõ ràng:

from google import genai

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

response = client.models.generate_content(
    model="gemini-3-flash-preview", contents="Explain how AI works in a few words"
)
print(response.text)

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

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

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

main();

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
)

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

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-3-flash-preview",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

package com.example;

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().apiKey("YOUR_API_KEY").build();

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-3-flash-preview",
            "Explain how AI works in a few words",
            null);

    System.out.println(response.text());
  }
}

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Bảo mật khoá API của bạn

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

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

• Giữ bí mật khoá: Khoá API cho Gemini có thể truy cập vào dữ liệu nhạy cảm mà ứng dụng của bạn phụ thuộc vào.

  • Tuyệt đối không chuyển khoá API vào hệ thống kiểm soát nguồn. Không kiểm tra khoá API vào các hệ thống kiểm soát phiên bản như Git.

  • Tuyệt đối không tiết lộ khoá API ở phía máy khách. Không sử dụng trực tiếp khoá API trong các ứng dụng web hoặc ứng dụng di động trong quá trình sản xuất. Có thể trích xuất các khoá trong mã phía máy khách (bao gồm cả thư viện JavaScript/TypeScript và lệnh gọi REST).

• Hạn chế quyền truy cập: Hạn chế việc sử dụng khoá API đối với các địa chỉ IP, HTTP referrer hoặc ứng dụng Android/iOS cụ thể nếu có thể.

• Hạn chế mức sử dụng: Chỉ bật các API cần thiết cho mỗi khoá.

• Thực hiện kiểm tra thường xuyên: Thường xuyên kiểm tra khoá API và định kỳ xoay vòng các khoá đó.

Các phương pháp hay nhất

• Sử dụng lệnh gọi phía máy chủ bằng khoá API Cách an toàn nhất để sử dụng khoá API là gọi Gemini API từ một ứng dụng phía máy chủ, nơi có thể giữ bí mật khoá.

• Sử dụng mã thông báo tạm thời để truy cập phía máy khách (Chỉ API trực tiếp): Để truy cập trực tiếp vào API trực tiếp ở phía máy khách, bạn có thể sử dụng mã thông báo tạm thời. Các mã thông báo này có rủi ro bảo mật thấp hơn và có thể phù hợp để sử dụng trong quá trình sản xuất. Hãy xem hướng dẫn về mã thông báo tạm thời để biết thêm thông tin.

• Cân nhắc thêm các quy tắc hạn chế vào khoá: Bạn có thể giới hạn quyền của khoá bằng cách thêm các quy tắc hạn chế đối với khoá API. Điều này giúp giảm thiểu thiệt hại tiềm ẩn nếu khoá bị rò rỉ.

Để biết một số phương pháp hay nhất chung, bạn cũng có thể xem bài viết trợ giúp này .

Khắc phục sự cố khi tạo khoá API

Trong Google AI Studio, nút Tạo khoá API có thể xuất hiện dưới dạng không dùng được, kèm theo thông báo: "Bạn không có quyền tạo khoá trong dự án này".

Điều này xảy ra khi bạn thiếu các quyền cần thiết trong dự án để tạo khoá mới:

• resourcemanager.projects.get: Cho phép AI Studio xác minh sự tồn tại của dự án.
• apikeys.keys.create: Cho phép tạo chính khoá API.
• serviceusage.services.enable: Bắt buộc để đảm bảo Gemini API đang hoạt động trên dự án.

Để khắc phục quyền của bạn, hãy yêu cầu quản trị viên dự án hoặc quản trị viên của tổ chức (nếu dự án thuộc về một tổ chức) cấp cho bạn một vai trò có các quyền được liệt kê ở trên (chẳng hạn như vai trò Người chỉnh sửa dự án hoặc vai trò tùy chỉnh).

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