Bỏ qua, tới nội dung chính
BaoPeak

Điều hướng chính

Dùng API key của Gemini API

Nguồn: https://ai.google.dev/gemini-api/docs/api-key Tiêu đề gốc: Using Gemini API keys - Interactions API | Google AI for Developers Ngôn ngữ gốc: tiếng Anh · Ngày tải: 2026-09-05 Phạm vi dịch: toàn văn trang kèm đủ 12 khối code của bản gốc; trang gốc không có hình; bỏ mục lục tự sinh "On this page", nút "Send feedback", "Was this helpful?" và băng quảng cáo phiên bản mới ở đầu trang

Tóm tắt 30 giây

Muốn dùng Gemini API, bạn phải xác thực yêu cầu của mình. Bạn xác thực bằng một standard API key hoặc một authorization API key.

Tạo hoặc xem API key của Gemini API

Hai loại API key: standard và authorization

Cả hai loại key đều mở cửa vào Gemini API, nhưng đặc tính bảo mật khác nhau. Gemini API đang chuyển dần từ standard API key sang authorization key để an toàn hơn:

Để bảo đảm an toàn khi dùng, Gemini API sẽ chuyển từ standard key sang auth key:

Quản lý API key trong Google AI Studio

Bạn quản lý dự án và key ngay trong Google AI Studio.

Dự án Google Cloud

Mỗi API key của Gemini API đều gắn với một dự án Google Cloud. Dự án Google Cloud quản lý phần thanh toán, danh sách người cùng làm và phân quyền. Google AI Studio cho bạn một giao diện đơn giản để truy cập các dự án đó.

Nhập dự án vào AI Studio

Mặc định Google AI Studio không hiện hết mọi dự án Google Cloud của bạn. Bạn phải nhập những dự án muốn dùng:

  1. Mở Google AI Studio.
  2. Mở Dashboard ở bảng bên trái rồi chọn Projects.
  3. Bấm nút Import projects.
  4. Tìm và chọn dự án Google Cloud muốn nhập, rồi bấm Import.
  5. Nhập xong thì vào trang API Keys trong dashboard để tạo key trong dự án đó.

Xử lý khi không có quyền tạo key

Nút Create API key có thể mờ đi. Nút này cũng có thể hiện dòng chữ sau:

"You do not have permission to create a key in this project" (Bạn không có quyền tạo key trong dự án này).

Khi đó, bạn thiếu quyền IAM cần thiết.

Hãy nhờ quản trị viên dự án hoặc tổ chức Google Cloud cấp vai trò có các quyền sau. Ví dụ: vai trò Project Editor.

Nếu không xin được quyền quản trị, bạn có thể tạo dự án Google Cloud mới không thuộc tổ chức nào để sinh key.

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

Có key rồi, bạn cấu hình môi trường để dùng key an toàn trong ứng dụng.

Cách 1: Dùng biến môi trường (khuyến nghị)

Đặt biến môi trường GEMINI_API_KEY hoặc GOOGLE_API_KEY. Các thư viện gọi Gemini API tự dò và dùng hai biến này. Nếu bạn đặt cả hai, GOOGLE_API_KEY được ưu tiên.

Bản gốc chia phần này thành ba tab theo hệ điều hành: Linux/macOS - Bash, macOS - Zsh và Windows. Dưới đây là cả ba.

Linux/macOS — Bash

Kiểm xem bạn đã có file cấu hình của bash chưa:

~/.bashrc

Chưa có thì tạo rồi mở nó ra:

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

Thêm lệnh export vào cuối file:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

Lưu file, rồi áp dụng thay đổi:

source ~/.bashrc

macOS — Zsh

Kiểm xem bạn đã có file cấu hình của zsh chưa:

~/.zshrc

Chưa có thì tạo rồi mở nó ra:

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

Thêm lệnh export:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

Lưu file, rồi áp dụng thay đổi:

source ~/.zshrc

Windows

  1. Gõ "Environment Variables" vào ô tìm kiếm của Windows.
  2. Bấm Environment Variables trong hộp thoại System Properties.
  3. Ở mục User variables hoặc System variables, bấm New....
  4. Đặt tên biến là GEMINI_API_KEY và giá trị là API key của bạn.
  5. Bấm OK để lưu. Mở một cửa sổ terminal mới để biến được nạp.

Cách 2: Đưa API key thẳng vào code

Bạn có thể truyền API key trực tiếp khi khởi tạo client. Chỉ làm cách này khi bạn không dùng được biến môi trường.

Bản gốc có bốn tab code: Python, JavaScript, Java và REST.

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(""));

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"
  }'

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

Hãy coi API key của Gemini như một mật khẩu. Nếu key lọt ra ngoài, người khác có thể xài hết hạn mức dự án. Họ có thể gây chi phí bất ngờ và truy cập tài nguyên riêng tư.

Quy tắc bảo mật bắt buộc

Cách quản lý bí mật tốt nhất

Việc cần làm khi key bị lộ

Nếu bạn nghi API key của mình đã lộ:

  1. Sinh key mới: tạo một key thay thế trong Google AI Studio hoặc trong Cloud Console.
  2. Cập nhật ứng dụng: triển khai lại code với key mới.
  3. Tắt hoặc xóa key đã lộ: tắt key bị lộ trong Cloud Console sau khi đã xác nhận key mới chạy được. Đừng xóa key cũ trước khi key mới hoạt động đầy đủ, để ứng dụng không bị gián đoạn.
  4. Soi lại mức dùng: kiểm nhật ký thanh toán và mức dùng API trong Google Cloud Console để tìm hoạt động trái phép.

Đặt giới hạn và bảo vệ key

Đặt thêm giới hạn cho API key giúp giảm thiệt hại nếu key lọt ra ngoài.

Giới hạn theo nguồn gửi yêu cầu

Giới hạn theo nguồn gửi quy định địa chỉ IP, website hoặc ứng dụng nào được phép dùng key của bạn.

  1. Mở trang Credentials của Google Cloud Console.
  2. Chọn dự án của bạn, rồi bấm vào tên của API key muốn giới hạn.
  3. Ở mục Application restrictions, chọn IP addresses (hoặc kiểu giới hạn phù hợp với môi trường của bạn).
  4. Khai các địa chỉ IP hoặc dải IP được phép, rồi bấm Save.

Bảo vệ standard API key chưa đặt giới hạn

Muốn tiếp tục dùng Gemini API, bạn phải bảo vệ mọi key chưa đặt giới hạn.

Cách A: chỉ cho key dùng Gemini API (làm trong AI Studio)

Nếu bạn chỉ dùng key cho Gemini API, hãy bảo vệ nó ngay trong AI Studio:

  1. Ở trang API Keys trong Google AI Studio, tìm những key gắn nhãn Unrestricted.
  2. Rê chuột lên nhãn đó rồi bấm Add restrictions trong hộp thoại.
  3. Chọn Restrict to Gemini API only.
  4. Bấm Restrict key để xác nhận.

Cách B: giới hạn key cho các dịch vụ khác (làm trong Google Cloud Console)

Nếu key dùng chung với API khác của Google, hãy đặt giới hạn trong Cloud Console. Cách dùng chung này không được khuyến nghị. Lưu ý: sau khi áp các giới hạn này, yêu cầu gửi tới Gemini API bằng key đó sẽ thất bại.

  1. Vào trang Credentials của Google Cloud Console.
  2. Chọn dự án và chọn API key.
  3. Ở mục API restrictions, mở danh sách Select API restrictions rồi chọn những API mà key này được phép chạm tới. Đừng chọn Generative Language API.
  4. Bấm Save. Sau đó tạo một key riêng, có giới hạn, trong AI Studio để tiếp tục dùng Gemini API.

Key nằm im lâu ngày bị chặn

Từ ngày 7 tháng 5 năm 2026, Gemini API chặn những API key chưa đặt giới hạn mà đã nằm im trong thời gian dài. Các key này hiện thẻ Blocked trong AI Studio. Bạn phải sinh key mới hoặc dùng một key đã có giới hạn để chạy tiếp.

Chuyển sang auth key

Làm theo các bước sau để tạo auth API key mới và cập nhật ứng dụng của bạn:

  1. Mở trang API Keys của AI Studio.
  2. Xem cột Key Type để tìm những key đang ghi là Standard.
  3. Bấm Create API key để sinh key mới. Mọi key mới tạo trong AI Studio đều tự động là auth key.
  4. Chép auth API key mới.
  5. Cập nhật code ứng dụng, biến môi trường và mọi cấu hình triển khai để dùng auth API key mới.
  6. Chạy thử ứng dụng để chắc chắn nó hoạt động đúng với key mới.
  7. Xác nhận xong thì xóa hoặc thu hồi key cũ để tránh bị lạm dụng.

Những giới hạn cần biết

Google AI Studio đặt các giới hạn sau cho việc quản lý dự án và key:

Để quản lý dự án sâu hơn hoặc sửa key có kiểu giới hạn khác, hãy dùng trang Credentials của Google Cloud Console.

Bản quyền của trang gốc: trừ khi có ghi chú khác, nội dung trang này phát hành theo Creative Commons Attribution 4.0 License, còn các đoạn code mẫu phát hành theo Apache 2.0 License. Chi tiết xem Google Developers Site Policies. Java là thương hiệu đã đăng ký của Oracle và/hoặc các công ty liên kết.

Trang gốc cập nhật lần cuối ngày 2026-09-02 theo giờ UTC.