라이브 API

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

이 문서에서는 Live API의 기능, 시작 예시, 기본 사용 사례 코드 예시를 포함하여 Live API 사용에 관한 기본사항을 다룹니다. Live API를 사용하여 대화형 대화를 시작하는 방법을 알아보려면 Live API를 사용한 대화형 대화를 참고하세요. Live API에서 사용할 수 있는 도구에 관한 정보를 확인하려면 기본 제공 도구를 참고하세요.

지원되는 모델

Live API는 Google 생성형 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용 Gen AI SDK

# 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용 Gen AI SDK

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용 Gen AI SDK

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

추가 정보

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