Mã thông báo tạm thời là mã thông báo xác thực có thời hạn ngắn để truy cập vào Gemini API thông qua WebSockets. Chúng đượ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 đến API (một cách triển khai từ ứng dụng đến máy chủ). Giống như khoá API tiêu chuẩn, bạn có thể trích xuất mã thông báo tạm thời từ các ứng dụng phía máy khách, chẳng hạn 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 giúp giảm đáng kể các rủi ro bảo mật trong môi trường phát hành chính thức.
Cách hoạt động của mã thông báo tạm thời
Sau đâ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 của bạn (ví dụ: ứng dụng web) xác thực bằng phụ trợ.
- Phần phụ trợ của bạn yêu cầu một mã thông báo tạm thời từ dịch vụ cung cấp của Gemini API.
- Gemini API phát hành một mã thông báo ngắn hạn.
- Phụ trợ của bạn sẽ gửi mã thông báo đến ứng dụng để kết nối WebSocket với Live API. Bạn có thể thực hiện việc này bằng cách thay thế khoá API bằng một mã thông báo tạm thời.
- Sau đó, ứng dụng sẽ sử dụng mã thông báo này như thể đó là một 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 cũng chỉ tồn tại trong thời gian ngắn, không giống như khoá API tồn tại trong thời gian 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 giúp cải thiện độ trễ và tránh việc các máy chủ phụ trợ của bạn cần phải uỷ quyền dữ liệu theo thời gian thực.
Tạo mã thông báo tạm thời
Sau đây là một 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 các phiên Live API mới bằng mã thông báo từ yêu cầu này (newSessionExpireTime) và 30 phút để gửi tin nhắn 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 về giá trị expireTime, giá trị mặc định và các quy cách khác về trường, hãy xem tài liệu tham khảo về API.
Trong khung thời gian expireTime, bạn sẽ cần sessionResumption kết nối lại cuộc gọi sau 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 đối với một nhóm cấu hình. Điều này có thể hữu ích để cải thiện hơn nữa tính bảo mật của ứng dụng và giữ các chỉ 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
Sau khi có mã thông báo tạm thời, bạn có thể sử dụng mã này như thể đó là một khoá API (nhưng hãy nhớ rằng mã này chỉ hoạt động với API trực tiếp và chỉ với phiên bản v1alpha của API).
Xin lưu ý rằng việc sử dụng mã thông báo tạm thời chỉ có 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({
apiKey: token.name
});
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 hạn hết hạn ngắn bằng cách sử dụng tham số
expire_time. - Mã thông báo hết hạn, yêu cầu khởi động lại quy trình cấp phép.
- Xác minh quy trình xác thực an toàn cho 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ụ 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
- Hãy đọc phần tài liệu tham khảo về Live API đối với mã thông báo tạm thời để biết thêm thông tin.