임시 토큰은 WebSockets을 통해 Gemini API에 액세스하기 위한 단기 인증 토큰입니다. 사용자 기기에서 API로 직접 연결하는 경우 (클라이언트-서버 구현) 보안을 강화하도록 설계되었습니다. 표준 API 키와 마찬가지로 임시 토큰은 웹브라우저나 모바일 앱과 같은 클라이언트 측 애플리케이션에서 추출할 수 있습니다. 하지만 임시 토큰은 만료가 빠르고 제한될 수 있으므로 프로덕션 환경의 보안 위험을 크게 줄여줍니다.
임시 토큰의 작동 방식
일회성 토큰은 대략적으로 다음과 같이 작동합니다.
- 클라이언트 (예: 웹 앱)가 백엔드로 인증합니다.
- 백엔드가 Gemini API의 프로비저닝 서비스에서 임시 토큰을 요청합니다.
- Gemini API에서 단기 토큰을 발급합니다.
- 백엔드는 WebSocket 연결을 통해 Live API에 연결할 수 있도록 클라이언트에 토큰을 전송합니다. API 키를 일시적인 토큰으로 바꾸면 됩니다.
- 그러면 클라이언트가 토큰을 API 키인 것처럼 사용합니다.
이렇게 하면 클라이언트 측에 배포된 수명이 긴 API 키와 달리 토큰이 추출되더라도 수명이 짧아 보안이 강화됩니다. 클라이언트가 데이터를 Gemini에 직접 전송하므로 지연 시간도 개선되고 백엔드에서 실시간 데이터를 프록시할 필요가 없습니다.
임시 토큰 만들기
다음은 Gemini에서 임시 토큰을 가져오는 방법을 보여주는 간단한 예입니다.
기본적으로 이 요청 (newSessionExpireTime)의 토큰을 사용하여 새 Live API 세션을 시작하는 데 1분이 주어지며, 해당 연결 (expireTime)을 통해 메시지를 전송하는 데 30분이 주어집니다.
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
자바스크립트
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'},
},
});
expireTime 값 제약 조건, 기본값, 기타 필드 사양은 API 참조를 참고하세요.
expireTime 기간 내에 10분마다 통화를 다시 연결해야 합니다 (uses: 1인 경우에도 동일한 토큰으로 가능).sessionResumption
일련의 구성에 임시 토큰을 잠글 수도 있습니다. 이는 애플리케이션의 보안을 더욱 개선하고 시스템 명령어를 서버 측에 유지하는 데 유용할 수 있습니다.
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
자바스크립트
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
필드의 하위 집합을 잠글 수도 있습니다. 자세한 내용은 SDK 문서를 참고하세요.
임시 토큰으로 Live API에 연결
임시 토큰이 있으면 API 키인 것처럼 사용합니다. 단, 라이브 API에서만 작동하며 API의 v1alpha 버전에서만 작동합니다.
임시 토큰 사용은 클라이언트-서버 구현 접근 방식을 따르는 애플리케이션을 배포할 때만 유용합니다.
자바스크립트
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();
자세한 예는 Live API 시작하기를 참고하세요.
권장사항
expire_time매개변수를 사용하여 짧은 만료 기간을 설정합니다.- 토큰이 만료되어 프로비저닝 프로세스를 다시 시작해야 합니다.
- 자체 백엔드의 보안 인증을 확인합니다. 임시 토큰은 백엔드 인증 방법만큼만 안전합니다.
- 일반적으로 이 경로가 안전한 것으로 간주되므로 백엔드-Gemini 연결에는 임시 토큰을 사용하지 않는 것이 좋습니다.
제한사항
현재 임시 토큰은 Live API와만 호환됩니다.
다음 단계
- 자세한 내용은 임시 토큰에 관한 Live API 참조를 참고하세요.