Ephemeral tokens

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

임시 토큰의 작동 방식

일회용 토큰의 대략적인 작동 방식은 다음과 같습니다.

  1. 클라이언트 (예: 웹 앱)가 백엔드와 인증합니다.
  2. 백엔드가 Gemini API의 프로비저닝 서비스에서 임시 토큰을 요청합니다.
  3. Gemini API는 단기 토큰을 발급합니다.
  4. 백엔드는 Live API에 대한 WebSocket 연결을 위해 클라이언트로 토큰을 전송합니다. API 키를 임시 토큰으로 전환하면 됩니다.
  5. 그러면 클라이언트는 토큰을 API 키처럼 사용합니다.

임시 토큰 개요

이렇게 하면 추출되더라도 클라이언트 측에 배포된 장기 API 키와 달리 토큰이 단기적이므로 보안이 강화됩니다. 클라이언트가 데이터를 Gemini로 직접 전송하므로 지연 시간도 개선되고 백엔드에서 실시간 데이터를 프록시할 필요가 없습니다.

임시 토큰 만들기

다음은 Gemini에서 일회용 토큰을 가져오는 방법을 보여주는 간단한 예입니다. 기본적으로 이 요청의 토큰 (newSessionExpireTime)을 사용하여 새 실시간 API 세션을 시작하는 데 1분, 해당 연결 (expireTime)을 통해 메시지를 전송하는 데 30분이 소요됩니다.

Python

import datetime

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

client = genai.Client(
    api_key="GEMINI_API_KEY",
    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({ apiKey: "GEMINI_API_KEY" });
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분마다 통화를 다시 연결하려면 sessionResumption를 사용해야 합니다 (uses: 1인 경우에도 동일한 토큰으로 실행할 수 있음).

일시적인 토큰을 구성 집합에 잠글 수도 있습니다. 이는 애플리케이션의 보안을 더욱 강화하고 시스템 안내를 서버 측에 유지하는 데 유용할 수 있습니다.

Python

client = genai.Client(
    api_key="GEMINI_API_KEY",
    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({ apiKey: "GEMINI_API_KEY" });
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에 연결하는 예입니다. 일시적인 토큰을 사용하면 클라이언트-서버 구현 접근 방식을 따르는 애플리케이션을 배포할 때만 가치가 추가됩니다.

자바스크립트

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 연결에는 임시 토큰을 사용하지 않는 것이 좋습니다. 이 경로는 일반적으로 안전하다고 간주되기 때문입니다.

제한사항

임시 토큰은 현재 실시간 API와만 호환됩니다.

다음 단계

  • 자세한 내용은 일회용 토큰에 관한 Live API 참조를 참고하세요.