라이브 API

Live API는 지연 시간이 짧은 Gemini와의 양방향 음성 및 동영상 상호작용을 지원합니다. Live API를 사용하여 최종 사용자에게 사람처럼 자연스러운 음성 대화 경험과 음성 명령을 사용하여 모델의 응답을 중단할 수 있는 기능을 제공합니다.

이 문서에서는 기능, 시작 예시, 기본 사용 사례 코드 예시를 비롯한 Live API 사용의 기본사항을 다룹니다. Live API를 사용하여 대화형 대화를 시작하는 방법에 관한 정보를 찾고 있다면 Live API를 사용한 대화형 대화를 참고하세요. Live API에서 사용할 수 있는 도구에 관한 정보를 찾고 있다면 내장 도구를 참고하세요.

지원되는 모델

Live API는 Google Gen AI SDK와 Vertex AI Studio에서 모두 사용할 수 있습니다. 일부 기능 (예: 텍스트 입력 및 출력)은 Gen AI SDK를 사용해야만 사용할 수 있습니다.

다음 모델에서 Live API를 사용할 수 있습니다.

모델 버전 가용성 수준
gemini-live-2.5-flash 비공개 GA*
gemini-live-2.5-flash-preview-native-audio 공개 미리보기

* 액세스 권한을 요청하려면 Google 계정팀 담당자에게 문의하세요.

기술 사양 및 제한사항을 비롯한 자세한 내용은 Live API 참조 가이드를 참고하세요.

시작 조건 예

다음 예시 중 하나를 사용하여 Live API를 시작할 수 있습니다.

Jupyter 노트북:

데모 애플리케이션 및 가이드:

Live API 기능

  • 실시간 멀티모달 이해: 스트리밍 오디오 및 동영상에 대한 기본 지원을 사용하여 동영상 피드 또는 화면 공유를 통해 Gemini가 보는 내용에 관해 대화하세요.
  • 내장 도구 사용: 함수 호출 및 Google 검색을 통한 그라운딩과 같은 도구를 대화에 원활하게 통합하여 더욱 실용적이고 역동적인 상호작용을 지원합니다.
  • 짧은 지연 시간의 상호작용: Gemini와 짧은 지연 시간으로 사람과 같은 상호작용을 할 수 있습니다.
  • 다국어 지원: 지원되는 24개 언어로 대화하세요.
  • (GA 버전만 해당) 프로비저닝된 처리량 지원: Live API를 비롯해 Vertex AI에서 지원되는 생성형 AI 모델의 처리량을 예약하는 여러 기간의 고정 비용, 고정 기간 구독을 사용합니다.

Live API가 적용된 Gemini 2.5 Flash에는 공개 프리뷰로 네이티브 오디오도 포함되어 있습니다. 네이티브 오디오는 다음을 도입합니다.

  • 정서적 대화: Live API는 사용자의 어조를 이해하고 이에 응답합니다. 같은 단어를 다른 방식으로 말하면 매우 다른 미묘한 대화가 이어질 수 있습니다.
  • 사전 대응 오디오 및 컨텍스트 인식: Live API는 주변 대화 및 기타 관련 없는 오디오를 지능적으로 무시하여 언제 들어야 하고 언제 조용히 있어야 하는지 이해합니다.

네이티브 오디오에 관한 자세한 내용은 내장 도구를 참고하세요.

지원되는 오디오 형식

Live API는 다음 오디오 형식을 지원합니다.

  • 입력 오디오: 16kHz의 원시 16비트 PCM 오디오, little-endian
  • 오디오 출력: 24kHz의 원시 16비트 PCM 오디오, little-endian

오디오 입력에서 텍스트 응답 가져오기

오디오를 16비트 PCM, 16kHz, 모노 형식으로 변환하여 오디오를 보내고 텍스트 응답을 받을 수 있습니다. 다음 예에서는 WAV 파일을 읽고 올바른 형식으로 전송합니다.

Python

# Test file: https://storage.googleapis.com/generativeai-downloads/data/16000.wav
# Install helpers for converting files: pip install librosa soundfile

import asyncio
import io
from pathlib import Path
from google import genai
from google.genai import types
import soundfile as sf
import librosa

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-live-2.5-flash"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:

        buffer = io.BytesIO()
        y, sr = librosa.load("sample.wav", sr=16000)
        sf.write(buffer, y, sr, format="RAW", subtype="PCM_16")
        buffer.seek(0)
        audio_bytes = buffer.read()

        # If already in correct format, you can use this:
        # audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        async for response in session.receive():
            if response.text is not None:
                print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

텍스트 입력에서 음성 응답 가져오기

이 예시를 사용하여 텍스트 입력을 전송하고 합성된 음성 응답을 수신하세요.

Python

import asyncio
import numpy as np
from IPython.display import Audio, Markdown, display
from google import genai
from google.genai.types import (
  Content,
  LiveConnectConfig,
  HttpOptions,
  Modality,
  Part,
  SpeechConfig,
  VoiceConfig,
  PrebuiltVoiceConfig,
)

client = genai.Client(
  vertexai=True,
  project=GOOGLE_CLOUD_PROJECT,
  location=GOOGLE_CLOUD_LOCATION,
)

voice_name = "Aoede"

config = LiveConnectConfig(
  response_modalities=["AUDIO"],
  speech_config=SpeechConfig(
      voice_config=VoiceConfig(
          prebuilt_voice_config=PrebuiltVoiceConfig(
              voice_name=voice_name,
          )
      ),
  ),
)

async with client.aio.live.connect(
  model="gemini-live-2.5-flash",
  config=config,
) as session:
  text_input = "Hello? Gemini are you there?"
  display(Markdown(f"**Input:** {text_input}"))

  await session.send_client_content(
      turns=Content(role="user", parts=[Part(text=text_input)]))

  audio_data = []
  async for message in session.receive():
      if (
          message.server_content.model_turn
          and message.server_content.model_turn.parts
      ):
          for part in message.server_content.model_turn.parts:
              if part.inline_data:
                  audio_data.append(
                      np.frombuffer(part.inline_data.data, dtype=np.int16)
                  )

  if audio_data:
      display(Audio(np.concatenate(audio_data), rate=24000, autoplay=True))

텍스트 전송의 더 많은 예는 시작 가이드를 참고하세요.

오디오 스크립트 작성

Live API는 입력 및 출력 오디오를 모두 텍스트로 변환할 수 있습니다. 다음 예시를 사용하여 스크립트를 사용 설정합니다.

Python

import asyncio
from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-live-2.5-flash"

config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {},
    "output_audio_transcription": {}
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.input_transcription:
                print("Input transcript:", response.server_content.input_transcription.text)
            if response.server_content.output_transcription:
                print("Output transcript:", response.server_content.output_transcription.text)

if __name__ == "__main__":
    asyncio.run(main())

WebSocket

# Set model generation_config
CONFIG = {
    'response_modalities': ['AUDIO'],
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {bearer_token[0]}",
}

# Connect to the server
async with connect(SERVICE_URL, additional_headers=headers) as ws:
    # Setup the session
    await ws.send(
        json.dumps(
            {
                "setup": {
                    "model": "gemini-2.0-flash-live-preview-04-09",
                    "generation_config": CONFIG,
                    'input_audio_transcription': {},
                    'output_audio_transcription': {}
                }
            }
        )
    )

    # Receive setup response
    raw_response = await ws.recv(decode=False)
    setup_response = json.loads(raw_response.decode("ascii"))

    # Send text message
    text_input = "Hello? Gemini are you there?"
    display(Markdown(f"**Input:** {text_input}"))

    msg = {
        "client_content": {
            "turns": [{"role": "user", "parts": [{"text": text_input}]}],
            "turn_complete": True,
        }
    }

    await ws.send(json.dumps(msg))

    responses = []
    input_transcriptions = []
    output_transcriptions = []

    # Receive chucks of server response
    async for raw_response in ws:
        response = json.loads(raw_response.decode())
        server_content = response.pop("serverContent", None)
        if server_content is None:
            break

        if (input_transcription := server_content.get("inputTranscription")) is not None:
            if (text := input_transcription.get("text")) is not None:
                input_transcriptions.append(text)
        if (output_transcription := server_content.get("outputTranscription")) is not None:
            if (text := output_transcription.get("text")) is not None:
                output_transcriptions.append(text)

        model_turn = server_content.pop("modelTurn", None)
        if model_turn is not None:
            parts = model_turn.pop("parts", None)
            if parts is not None:
                for part in parts:
                    pcm_data = base64.b64decode(part["inlineData"]["data"])
                    responses.append(np.frombuffer(pcm_data, dtype=np.int16))

        # End of turn
        turn_complete = server_content.pop("turnComplete", None)
        if turn_complete:
            break

    if input_transcriptions:
        display(Markdown(f"**Input transcription >** {''.join(input_transcriptions)}"))

    if responses:
        # Play the returned audio message
        display(Audio(np.concatenate(responses), rate=24000, autoplay=True))

    if output_transcriptions:
        display(Markdown(f"**Output transcription >** {''.join(output_transcriptions)}"))

추가 정보

라이브 API 사용에 관한 자세한 내용은 다음을 참고하세요.