Mã thông báo tạm thời là mã thông báo xác thực có thời gian tồn tại ngắn để truy cập vào API Gemini thông qua WebSockets. Các API này được thiết kế để tăng cường bảo mật khi bạn kết nối trực tiếp từ thiết bị của người dùng với API (triển khai ứng dụng đến máy chủ). Giống như khoá API tiêu chuẩn, mã thông báo tạm thời có thể được trích xuất từ các ứng dụng phía máy khách như trình duyệt web hoặc ứng dụng di động. Tuy nhiên, vì mã thông báo tạm thời hết hạn nhanh chóng và có thể bị hạn chế, nên chúng làm giảm đáng kể rủi ro bảo mật trong môi trường sản xuất.
Cách hoạt động của mã thông báo tạm thời
Dưới đây là cách hoạt động của mã thông báo tạm thời ở cấp độ tổng quát:
- Ứng dụng khách (ví dụ: ứng dụng web) xác thực bằng phần phụ trợ.
- Phần phụ trợ của bạn yêu cầu mã thông báo tạm thời từ dịch vụ cấp phép của Gemini API.
- Gemini API phát hành một mã thông báo ngắn hạn.
- Phần phụ trợ sẽ gửi mã thông báo đến ứng dụng cho các kết nối WebSocket đến Live API. Bạn có thể thực hiện việc này bằng cách hoán đổi khoá API với mã thông báo tạm thời.
- Sau đó, ứng dụng sẽ sử dụng mã thông báo như thể đó là khoá API.
Điều này giúp tăng cường bảo mật vì ngay cả khi được trích xuất, mã thông báo vẫn có thời gian tồn tại ngắn, khác với khoá API có thời gian tồn tại dài được triển khai phía máy khách. Vì ứng dụng gửi dữ liệu trực tiếp đến Gemini, nên điều này cũng cải thiện độ trễ và tránh việc phần phụ trợ của bạn cần phải proxy dữ liệu theo thời gian thực.
Tạo mã thông báo tạm thời
Sau đây là ví dụ đơn giản về cách lấy mã thông báo tạm thời từ Gemini.
Theo mặc định, bạn sẽ có 1 phút để bắt đầu phiên API trực tiếp mới bằng mã thông báo từ yêu cầu này (newSessionExpireTime) và 30 phút để gửi thông báo qua kết nối đó (expireTime).
Python
import datetime
now = datetime.datetime.now(tz=datetime.timezone.utc)
client = genai.Client(
http_options={'api_version': 'v1alpha',}
)
token = client.auth_tokens.create(
config = {
'uses': 1, # The ephemeral token can only be used to start a single session
'expire_time': now + datetime.timedelta(minutes=30), # Default is 30 minutes in the future
# 'expire_time': '2025-05-17T00:00:00Z', # Accepts isoformat.
'new_session_expire_time': now + datetime.timedelta(minutes=1), # Default 1 minute in the future
'http_options': {'api_version': 'v1alpha'},
}
)
# You'll need to pass the value under token.name back to your client to use it
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();
const token: AuthToken = await client.authTokens.create({
config: {
uses: 1, // The default
expireTime: expireTime // Default is 30 mins
newSessionExpireTime: new Date(Date.now() + (1 * 60 * 1000)), // Default 1 minute in the future
httpOptions: {apiVersion: 'v1alpha'},
},
});
Để biết các quy tắc ràng buộc, giá trị mặc định và thông số kỹ thuật khác của trường expireTime, hãy xem tài liệu tham khảo API.
Trong khung thời gian expireTime, bạn sẽ cần sessionResumption để kết nối lại cuộc gọi mỗi 10 phút (bạn có thể thực hiện việc này bằng cùng một mã thông báo ngay cả khi uses: 1).
Bạn cũng có thể khoá mã thông báo tạm thời vào một tập hợp cấu hình. Điều này có thể hữu ích để cải thiện thêm tính bảo mật của ứng dụng và giữ các hướng dẫn hệ thống ở phía máy chủ.
Python
client = genai.Client(
http_options={'api_version': 'v1alpha',}
)
token = client.auth_tokens.create(
config = {
'uses': 1,
'live_connect_constraints': {
'model': 'gemini-2.0-flash-live-001',
'config': {
'session_resumption':{},
'temperature':0.7,
'response_modalities':['TEXT']
}
},
'http_options': {'api_version': 'v1alpha'},
}
)
# You'll need to pass the value under token.name back to your client to use it
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();
const token = await client.authTokens.create({
config: {
uses: 1, // The default
expireTime: expireTime,
liveConnectConstraints: {
model: 'gemini-2.0-flash-live-001',
config: {
sessionResumption: {},
temperature: 0.7,
responseModalities: ['TEXT']
}
},
httpOptions: {
apiVersion: 'v1alpha'
}
}
});
// You'll need to pass the value under token.name back to your client to use it
Bạn cũng có thể khoá một nhóm nhỏ các trường, hãy xem tài liệu về SDK để biết thêm thông tin.
Kết nối với Live API bằng mã thông báo tạm thời
Dưới đây là ví dụ về cách kết nối với Live API thông qua mã thông báo tạm thời. Xin lưu ý rằng việc sử dụng mã thông báo tạm thời chỉ làm tăng giá trị khi triển khai các ứng dụng tuân theo phương pháp triển khai từ máy khách đến máy chủ.
JavaScript
import { GoogleGenAI, Modality } from '@google/genai';
// Use the token generated in the "Create an ephemeral token" section here
const ai = new GoogleGenAI({});
const model = 'gemini-2.0-flash-live-001';
const config = { responseModalities: [Modality.TEXT] };
async function main() {
const session = await ai.live.connect({
model: model,
config: config,
callbacks: { ... },
});
// Send content...
session.close();
}
main();
Hãy xem bài viết Bắt đầu sử dụng Live API để biết thêm ví dụ.
Các phương pháp hay nhất
- Đặt thời gian hết hạn ngắn bằng tham số
expire_time. - Mã thông báo hết hạn, yêu cầu bắt đầu lại quy trình cấp phép.
- Xác minh quy trình xác thực an toàn cho phần phụ trợ của riêng bạn. Mã thông báo tạm thời sẽ chỉ an toàn như phương thức xác thực phụ trợ của bạn.
- Nhìn chung, hãy tránh sử dụng mã thông báo tạm thời cho các kết nối từ phần phụ trợ đến Gemini, vì đường dẫn này thường được coi là an toàn.
Các điểm hạn chế
Hiện tại, mã thông báo tạm thời chỉ tương thích với Live API.
Bước tiếp theo
- Đọc tài liệu tham khảo về mã thông báo tạm thời của API Trực tiếp để biết thêm thông tin.