Sử dụng khoá API Gemini

Sau khi có khoá API, bạn có thể kết nối với Gemini API theo những cách sau:

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

Đối với kiểm thử ban đầu, bạn có thể mã hoá cứng một khoá API, nhưng đây chỉ là giải pháp tạm thời vì không an toàn. Bạn có thể tìm thấy các ví dụ về việc 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 Google Cloud là yếu tố 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ý việc 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 của bạ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 để xem hướng dẫn.

Nhập dự án

Mỗi khoá API Gemini đều được liên kết với một dự án trên Google Cloud. Theo mặc định, AI Studio của Google sẽ không hiển thị tất cả Dự án trên đám mây của bạn. Bạn phải nhập các dự án mình muốn bằng cách tì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. 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.
3. Chọn Dự án.
4. Chọn nút Nhập dự án trên trang Dự án.
5. Tìm và chọn dự á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 API Keys (Khoá API) trong trình đơn Dashboard (Trang tổng quan) rồi tạo một khoá API trong dự án mà bạn vừa nhập.

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

Sau đây là những 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 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á.
• Trang Khoá API và Dự án hiển thị tối đa 100 khoá và 100 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 xuất hiện.

Để có thêm quyền quản lý đối với các dự án của bạn, hãy truy cập vào Google Cloud Console.

Đặ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, 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 chỉ nên đặ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 dùng REST API 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 bằng 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à muốn mã hoá khoá API.
• Bạn muốn kiểm soát rõ ràng mà không cần dựa vào tính năng tự động phát hiện các biến môi trường của thư viện Gemini API
• 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à 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-2.5-flash", 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-2.5-flash",
    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-2.5-flash",
        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-2.5-flash",
            "Explain how AI works in a few words",
            null);

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash: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

Hãy coi khoá Gemini API như một mật khẩu. Nếu bị xâm nhập, những người khác có thể sử dụng hạn mức của dự án, phát sinh phí (nếu bạn 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

• Tuyệt đối không chuyển khoá API vào tính năng kiểm soát nguồn. Đừng kiểm tra khoá API của bạn trong các hệ thống quản lý phiên bản như Git.

• Tuyệt đối không để 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 di động trong quá trình sản 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) có thể được trích xuất.

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

• Sử dụng các 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ủ, trong đó khoá có thể được giữ bí mật.

• Sử dụng mã thông báo tạm thời để truy cập phía máy khách (chỉ Live API): Để truy cập trực tiếp vào Live API phía máy khách, bạn có thể sử dụng mã thông báo tạm thời. Chúng có rủi ro bảo mật thấp hơn và có thể phù hợp để sử dụng trong bản phát hành chính thức. 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 việc thêm các quy tắc hạn chế đối với khoá: Bạn có thể giới hạn các 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 hỗ trợ này.