임시 토큰

임시 토큰

임시 토큰은 WebSockets를 통해 Gemini API에 접속하기 위한 단기 인증 토큰이에요. 사용자 기기에서 API로 직접 연결할 때(클라이언트-서버 구현) 보안을 강화하도록 설계되었어요. 일반 API 키와 마찬가지로 임시 토큰은 웹 브라우저나 모바일 앱 같은 클라이언트 측 애플리케이션에서 추출될 수 있어요. 하지만 임시 토큰은 빠르게 만료되고 제한할 수 있어 프로덕션 환경에서 보안 위험을 크게 줄여줘요. 클라이언트 측 애플리케이션에서 Live API에 직접 접근할 때 임시 토큰을 사용해서 API 키 보안을 강화해야 해요.

출처: 원문

본문

임시 토큰의 작동 방식

임시 토큰이 개괄적으로 어떻게 작동하는지는 다음과 같아요.

1. 클라이언트(예: 웹 앱)가 백엔드에서 인증해요.
2. 백엔드가 Gemini API의 프로비저닝 서비스에 임시 토큰을 요청해요.
3. Gemini API가 짧은 수명의 토큰을 발급해요.
4. 백엔드가 Live API WebSocket 연결을 위해 토큰을 클라이언트로 보내요. API 키를 임시 토큰으로 교체하면 돼요.
5. 클라이언트는 그 토큰을 API 키처럼 사용해요.

이렇게 하면 추출되어도 토큰이 짧은 수명이라서, 클라이언트에 배포된 장수명 API 키와 달리 보안이 강화돼요. 클라이언트가 Gemini로 데이터를 직접 보내므로 지연 시간도 개선되고 백엔드가 실시간 데이터를 프록시할 필요도 없어져요.

임시 토큰 만들기

다음은 Gemini에서 임시 토큰을 가져오는 간단한 예시예요. 기본적으로 이 요청(newSessionExpireTime)으로 토큰을 사용해 새 Live API 세션을 시작할 시간은 1분, 해당 연결로 메시지를 보낼 시간은 30분(expireTime)이에요.

import datetime
from google import genai

now = datetime.datetime.now(tz=datetime.timezone.utc)

client = genai.Client()

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
  }
)

# 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, // Default is 30 mins
      newSessionExpireTime: new Date(Date.now() + (1 * 60 * 1000)), // Default 1 minute in the future
    },
  });

curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: ${GEMI...EY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uses": 1,
    "expireTime": "YYYY-MM-DDTHH:MM:SSZ",
    "newSessionExpireTime": "YYYY-MM-DDTHH:MM:SSZ"
  }'

expireTime 값의 제약, 기본값, 기타 필드 사양은 API 참조를 참조하세요. expireTime 시간 내에서 10분마다 호출을 다시 연결하려면 sessionResumption이 필요해요(uses: 1이어도 같은 토큰으로 가능해요).

또한 임시 토큰을 일련의 구성으로 고정(lock)할 수도 있어요. 이는 애플리케이션의 보안을 더 강화하고 시스템 지침을 서버 측에 유지하는 데 유용할 수 있어요.

from google import genai

client = genai.Client()

token = client.auth_tokens.create(
    config = {
    'uses': 1,
    'live_connect_constraints': {
        'model': 'gemini-3.8-live',
        'config': {
            'session_resumption':{},
            'response_modalities':['AUDIO']
        }
    },
    }
)

# 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-3.8-live',
            config: {
                sessionResumption: {},
                responseModalities: ['AUDIO']
            }
        },
    }
});

// You'll need to pass the value under token.name back to your client to use it

curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
  -H "x-goog-api-key: ${GEMI...EY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uses": 1,
    "expireTime": "YYYY-MM-DDTHH:MM:SSZ",
    "liveConnectConstraints": {
      "model": "models/gemini-3.8-live",
      "config": {
        "sessionResumption": {},
        "responseModalities": ["AUDIO"]
      }
    }
  }'

필드의 일부만 고정할 수도 있는데, 자세한 내용은 SDK 문서를 참조하세요.

임시 토큰으로 Live API에 연결

임시 토큰이 있으면 API 키처럼 사용해요(단, Live API에서만, 그리고 v1beta 버전의 API에서만 동작한다는 점을 기억하세요).

임시 토큰은 클라이언트-서버 구현 방식을 따르는 애플리케이션을 배포할 때만 가치가 있어요.

import { GoogleGenAI, Modality } from '@google/genai';

// Use the token generated in the "Create an ephemeral token" section here
const ai = new GoogleGenAI({
  apiKey: ***
});
const model = 'gemini-3.8-live';
const config = { responseModalities: [Modality.AUDIO] };

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 참조 문서를 읽어보세요.

더 알아보기 (Learn more)

• Live API
• Live API 시작하기
• 임시 인증 토큰 참조