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ày đế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 tính 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 làm trung gian cho 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
importdatetimenow=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";constclient=newGoogleGenAI({});constexpireTime=newDate(Date.now()+30*60*1000).toISOString();consttoken:AuthToken=awaitclient.authTokens.create({config:{uses:1,// The defaultexpireTime:expireTime// Default is 30 minsnewSessionExpireTime:newDate(Date.now()+(1*60*1000)),// Default 1 minute in the futurehttpOptions:{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 thông số kỹ thuật khác của 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";constclient=newGoogleGenAI({});constexpireTime=newDate(Date.now()+30*60*1000).toISOString();consttoken=awaitclient.authTokens.create({config:{uses:1,// The defaultexpireTime: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 hereconstai=newGoogleGenAI({apiKey:token.name});constmodel='gemini-2.0-flash-live-001';constconfig={responseModalities:[Modality.TEXT]};asyncfunctionmain(){constsession=awaitai.live.connect({model:model,config:config,callbacks:{...},});// Send content...session.close();}main();
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-08-22 UTC."],[],[],null,["# Ephemeral tokens are short-lived authentication tokens for accessing the Gemini\nAPI through [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API). They are designed to enhance security when\nyou are connecting directly from a user's device to the API (a\n[client-to-server](/gemini-api/docs/live#implementation-approach)\nimplementation). Like standard API keys, ephemeral tokens can be extracted from\nclient-side applications such as web browsers or mobile apps. But because\nephemeral tokens expire quickly and can be restricted, they significantly reduce\nthe security risks in a production environment.\n| **Note:** Ephemeral tokens are only compatible with [Live API](/gemini-api/docs/live) at this time. You should use them when accessing the Live API directly from client-side applications to enhance API key security.\n\nHow ephemeral tokens work\n-------------------------\n\nHere's how ephemeral tokens work at a high level:\n\n1. Your client (e.g. web app) authenticates with your backend.\n2. Your backend requests an ephemeral token from Gemini API's provisioning service.\n3. Gemini API issues a short-lived token.\n4. Your backend sends the token to the client for WebSocket connections to Live API. You can do this by swapping your API key with an ephemeral token.\n5. The client then uses the token as if it were an API key.\n\nThis enhances security because even if extracted, the token is short-lived,\nunlike a long-lived API key deployed client-side. Since the client sends data\ndirectly to Gemini, this also improves latency and avoids your backends needing\nto proxy the real time data.\n\nCreate an ephemeral token\n-------------------------\n\nHere is a simplified example of how to get an ephemeral token from Gemini.\nBy default, you'll have 1 minute to start new Live API sessions using the token\nfrom this request (`newSessionExpireTime`), and 30 minutes to send messages over\nthat connection (`expireTime`). \n\n### Python\n\n import datetime\n\n now = datetime.datetime.now(tz=datetime.timezone.utc)\n\n client = genai.Client(\n http_options={'api_version': 'v1alpha',}\n )\n\n token = client.auth_tokens.create(\n config = {\n 'uses': 1, # The ephemeral token can only be used to start a single session\n 'expire_time': now + datetime.timedelta(minutes=30), # Default is 30 minutes in the future\n # 'expire_time': '2025-05-17T00:00:00Z', # Accepts isoformat.\n 'new_session_expire_time': now + datetime.timedelta(minutes=1), # Default 1 minute in the future\n 'http_options': {'api_version': 'v1alpha'},\n }\n )\n\n # You'll need to pass the value under token.name back to your client to use it\n\n### JavaScript\n\n import { GoogleGenAI } from \"@google/genai\";\n\n const client = new GoogleGenAI({});\n const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();\n\n const token: AuthToken = await client.authTokens.create({\n config: {\n uses: 1, // The default\n expireTime: expireTime // Default is 30 mins\n newSessionExpireTime: new Date(Date.now() + (1 * 60 * 1000)), // Default 1 minute in the future\n httpOptions: {apiVersion: 'v1alpha'},\n },\n });\n\nFor `expireTime` value constraints, defaults, and other field specs, see the\n[API reference](https://ai.google.dev/api/live#ephemeral-auth-tokens).\nWithin the `expireTime` timeframe, you'll need\n[`sessionResumption`](/gemini-api/docs/live-session#session-resumption) to\nreconnect the call every 10 minutes (this can be done with the same token even\nif `uses: 1`).\n\nIt's also possible to lock an ephemeral token to a set of configurations. This\nmight be useful to further improve security of your application and keep your\nsystem instructions on the server side. \n\n### Python\n\n client = genai.Client(\n http_options={'api_version': 'v1alpha',}\n )\n\n token = client.auth_tokens.create(\n config = {\n 'uses': 1,\n 'live_connect_constraints': {\n 'model': 'gemini-2.0-flash-live-001',\n 'config': {\n 'session_resumption':{},\n 'temperature':0.7,\n 'response_modalities':['TEXT']\n }\n },\n 'http_options': {'api_version': 'v1alpha'},\n }\n )\n\n # You'll need to pass the value under token.name back to your client to use it\n\n### JavaScript\n\n import { GoogleGenAI } from \"@google/genai\";\n\n const client = new GoogleGenAI({});\n const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();\n\n const token = await client.authTokens.create({\n config: {\n uses: 1, // The default\n expireTime: expireTime,\n liveConnectConstraints: {\n model: 'gemini-2.0-flash-live-001',\n config: {\n sessionResumption: {},\n temperature: 0.7,\n responseModalities: ['TEXT']\n }\n },\n httpOptions: {\n apiVersion: 'v1alpha'\n }\n }\n });\n\n // You'll need to pass the value under token.name back to your client to use it\n\nYou can also lock a subset of fields, see the [SDK documentation](https://googleapis.github.io/python-genai/genai.html#genai.types.CreateAuthTokenConfig.lock_additional_fields)\nfor more info.\n\nConnect to Live API with an ephemeral token\n-------------------------------------------\n\nOnce you have an ephemeral token, you use it as if it were an API key (but\nremember, it only works for the live API, and only with the `v1alpha` version of\nthe API).\n\nNote that use of ephemeral tokens only adds value when deploying applications\nthat follow [client-to-server implementation](/gemini-api/docs/live#implementation-approach) approach. \n\n### JavaScript\n\n import { GoogleGenAI, Modality } from '@google/genai';\n\n // Use the token generated in the \"Create an ephemeral token\" section here\n const ai = new GoogleGenAI({\n apiKey: token.name\n });\n const model = 'gemini-2.0-flash-live-001';\n const config = { responseModalities: [Modality.TEXT] };\n\n async function main() {\n\n const session = await ai.live.connect({\n model: model,\n config: config,\n callbacks: { ... },\n });\n\n // Send content...\n\n session.close();\n }\n\n main();\n\n| **Note:** If not using the SDK, note that ephemeral tokens must either be passed in an `access_token` query parameter, or in an HTTP `Authorization` prefixed by the [auth-scheme](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1) `Token`.\n\nSee [Get started with Live API](/gemini-api/docs/live) for more examples.\n\nBest practices\n--------------\n\n- Set a short expiration duration using the `expire_time` parameter.\n- Tokens expire, requiring re-initiation of the provisioning process.\n- Verify secure authentication for your own backend. Ephemeral tokens will only be as secure as your backend authentication method.\n- Generally, avoid using ephemeral tokens for backend-to-Gemini connections, as this path is typically considered secure.\n\nLimitations\n-----------\n\nEphemeral tokens are only compatible with [Live API](/gemini-api/docs/live) at this time.\n\nWhat's next\n-----------\n\n- Read the Live API [reference](https://ai.google.dev/api/live#ephemeral-auth-tokens) on ephemeral tokens for more information."]]
