Multimodal Live API를 사용하면 Gemini와의 양방향 음성 및 동영상 상호작용으로 지연 시간이 짧습니다. Multimodal Live API를 사용하면 최종 사용자에게 자연스럽고 인간과 같은 음성 대화 환경을 제공하고 음성 명령을 사용하여 모델의 응답을 중단할 수 있는 기능을 제공할 수 있습니다. 이 모델은 텍스트, 오디오, 동영상 입력을 처리할 수 있으며 텍스트 및 오디오 출력을 제공할 수 있습니다.
Google AI Studio에서 Multimodal Live API를 사용해 볼 수 있습니다.
Multimodal Live API 사용
이 섹션에서는 SDK 중 하나와 함께 Multimodal Live API를 사용하는 방법을 설명합니다. 기본 WebSockets API에 관한 자세한 내용은 아래의 WebSockets API 참조를 참고하세요.
문자 메시지 주고받기
import asyncio
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
while True:
message = input("User> ")
if message.lower() == "exit":
break
await session.send(input=message, end_of_turn=True)
async for response in session.receive():
if response.text is not None:
print(response.text, end="")
if __name__ == "__main__":
asyncio.run(main())
오디오 수신
다음 예는 오디오 데이터를 수신하여 .wav
파일에 쓰는 방법을 보여줍니다.
import asyncio
import wave
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"
config = {"response_modalities": ["AUDIO"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
wf = wave.open("audio.wav", "wb")
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(24000)
message = "Hello? Gemini are you there?"
await session.send(input=message, end_of_turn=True)
async for idx,response in async_enumerate(session.receive()):
if response.data is not None:
wf.writeframes(response.data)
# Comment this out to print audio data info
# if response.server_content.model_turn is not None:
# print(response.server_content.model_turn.parts[0].inline_data.mime_type)
wf.close()
if __name__ == "__main__":
asyncio.run(main())
오디오 형식
Multimodal Live API는 다음 오디오 형식을 지원합니다.
- 입력 오디오 형식: 16kHz little-endian의 원시 16비트 PCM 오디오
- 출력 오디오 형식: 24kHz little-endian의 원시 16비트 PCM 오디오
오디오 및 동영상 스트리밍
시스템 안내
시스템 안내를 사용하면 특정 요구사항 및 사용 사례에 따라 모델의 동작을 조정할 수 있습니다. 시스템 안내는 설정 구성에서 설정할 수 있으며 전체 세션 동안 적용됩니다.
from google.genai import types
config = {
"system_instruction": types.Content(
parts=[
types.Part(
text="You are a helpful assistant and answer in a friendly tone."
)
]
),
"response_modalities": ["TEXT"],
}
증분 콘텐츠 업데이트
증분 업데이트를 사용하여 텍스트 입력을 전송하거나, 세션 컨텍스트를 설정하거나, 세션 컨텍스트를 복원합니다. 짧은 컨텍스트의 경우 세부 경로 상호작용을 전송하여 정확한 이벤트 시퀀스를 나타낼 수 있습니다.
from google.genai import types
turns = [
types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))
turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))
{
"clientContent": {
"turns": [
{
"parts":[
{
"text": ""
}
],
"role":"user"
},
{
"parts":[
{
"text": ""
}
],
"role":"model"
}
],
"turnComplete": true
}
}
컨텍스트가 더 긴 경우 후속 상호작용에 컨텍스트 창을 확보할 수 있도록 단일 메시지 요약을 제공하는 것이 좋습니다.
음성 변경
멀티모달 실시간 API는 Aoede, Charon, Fenrir, Kore, Puck 음성을 지원합니다.
음성을 지정하려면 speechConfig
객체 내에서 음성 이름을 세션 구성의 일부로 설정합니다.
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
)
)
)
{
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Kore"
}
}
}
함수 호출 사용
Multimodal Live API를 사용하여 도구를 정의할 수 있습니다. 함수 호출에 대해 자세히 알아보려면 함수 호출 튜토리얼을 참고하세요.
도구는 세션 구성의 일부로 정의되어야 합니다.
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
tools=[set_light_values]
)
async with client.aio.live.connect(model=model, config=config) as session:
await session.send(input="Turn the lights down to a romantic level", end_of_turn=True)
async for response in session.receive():
print(response.tool_call)
모델은 단일 프롬프트에서 여러 함수 호출과 출력을 연결하는 데 필요한 코드를 생성할 수 있습니다. 이 코드는 샌드박스 환경에서 실행되어 후속 BidiGenerateContentToolCall 메시지를 생성합니다. 각 함수 호출의 결과를 사용할 수 있을 때까지 실행이 일시중지되므로 순차 처리가 보장됩니다.
클라이언트는 BidiGenerateContentToolResponse로 응답해야 합니다.
오디오 입력과 오디오 출력은 모델의 함수 호출 사용 능력에 부정적인 영향을 미칩니다.
방해 요소 처리
사용자는 언제든지 모델의 출력을 중단할 수 있습니다. 음성 활동 감지 (VAD)가 중단을 감지하면 진행 중인 생성이 취소되고 삭제됩니다. 이미 클라이언트로 전송된 정보만 세션 기록에 보관됩니다. 그런 다음 서버는 중단을 보고하기 위해 BidiGenerateContentServerContent 메시지를 전송합니다.
또한 Gemini 서버는 대기 중인 모든 함수 호출을 삭제하고 취소된 호출의 ID가 포함된 BidiGenerateContentServerContent
메시지를 전송합니다.
async for response in session.receive():
if response.server_content.interrupted is not None:
# The generation was interrupted
제한사항
프로젝트를 계획할 때는 멀티모달 실시간 API 및 Gemini 2.0의 다음 제한사항을 고려하세요.
클라이언트 인증
멀티모달 라이브 API는 서버 간 인증만 제공하며 직접 클라이언트용으로 사용하지 않는 것이 좋습니다. 클라이언트 입력은 멀티모달 라이브 API와의 보안 인증을 위해 중간 애플리케이션 서버를 통해 라우팅되어야 합니다.
대화 기록
모델은 세션 내 상호작용을 추적하지만 대화 기록은 저장되지 않습니다. 세션이 종료되면 해당 컨텍스트가 삭제됩니다.
이전 세션을 복원하거나 모델에 사용자 상호작용의 이전 맥락을 제공하려면 애플리케이션이 자체 대화 로그를 유지하고 BidiGenerateContentClientContent 메시지를 사용하여 새 세션이 시작될 때 이 정보를 전송해야 합니다.
최대 세션 시간
세션 시간은 오디오의 경우 최대 15분, 오디오 및 동영상의 경우 최대 2분으로 제한됩니다. 세션 시간이 한도를 초과하면 연결이 종료됩니다.
또한 모델은 컨텍스트 크기에 따라 제한됩니다. 동영상 및 오디오 스트림과 함께 대용량 콘텐츠를 전송하면 세션이 더 일찍 종료될 수 있습니다.
음성 활동 감지 (VAD)
이 모델은 연속 오디오 입력 스트림에서 음성 활동 감지 (VAD)를 자동으로 실행합니다. VAD는 항상 사용 설정되어 있으며 매개변수는 구성할 수 없습니다.
토큰 수
토큰 수는 지원되지 않습니다.
비율 제한
다음 비율 한도가 적용됩니다.
- API 키당 동시 세션 3개
- 분당 4백만 토큰
WebSockets API 참조
멀티모달 라이브 API는 WebSockets를 사용하는 상태ful API입니다. 이 섹션에서는 WebSockets API에 관한 추가 세부정보를 확인할 수 있습니다.
세션
WebSocket 연결은 클라이언트와 Gemini 서버 간에 세션을 설정합니다. 클라이언트가 새 연결을 시작한 후 세션은 서버와 메시지를 교환하여 다음 작업을 실행할 수 있습니다.
- 텍스트, 오디오 또는 동영상을 Gemini 서버로 전송합니다.
- Gemini 서버로부터 오디오, 텍스트 또는 함수 호출 요청을 수신합니다.
연결 후 첫 번째 메시지는 모델, 생성 매개변수, 시스템 안내, 도구를 포함하는 세션 구성을 설정합니다.
다음 구성 예시를 참고하세요. SDK의 이름 대소문자는 다를 수 있습니다. Python SDK 구성 옵션은 여기에서 확인할 수 있습니다.
{
"model": string,
"generationConfig": {
"candidateCount": integer,
"maxOutputTokens": integer,
"temperature": number,
"topP": number,
"topK": integer,
"presencePenalty": number,
"frequencyPenalty": number,
"responseModalities": [string],
"speechConfig": object
},
"systemInstruction": string,
"tools": [object]
}
메시지 보내기
WebSocket 연결을 통해 메시지를 교환하려면 클라이언트가 열린 WebSocket 연결을 통해 JSON 객체를 전송해야 합니다. JSON 객체는 다음 객체 세트의 필드 중 하나만 포함해야 합니다.
{
"setup": BidiGenerateContentSetup,
"clientContent": BidiGenerateContentClientContent,
"realtimeInput": BidiGenerateContentRealtimeInput,
"toolResponse": BidiGenerateContentToolResponse
}
지원되는 클라이언트 메시지
지원되는 클라이언트 메시지는 다음 표를 참고하세요.
메시지 | 설명 |
---|---|
BidiGenerateContentSetup |
첫 번째 메시지로 전송할 세션 구성 |
BidiGenerateContentClientContent |
클라이언트에서 전송된 현재 대화의 점진적 콘텐츠 업데이트 |
BidiGenerateContentRealtimeInput |
실시간 오디오 또는 동영상 입력 |
BidiGenerateContentToolResponse |
서버에서 수신한 ToolCallMessage 에 대한 응답 |
메시지 수신
Gemini에서 메시지를 수신하려면 WebSocket 'message' 이벤트를 리슨한 다음 지원되는 서버 메시지의 정의에 따라 결과를 파싱합니다.
다음을 참조하세요.
async with client.aio.live.connect(model='...', config=config) as session:
await session.send(input='Hello world!', end_of_turn=True)
async for message in session.receive():
print(message)
서버 메시지에는 다음 객체 세트의 필드 중 하나만 포함됩니다.
{
"setupComplete": BidiGenerateContentSetupComplete,
"serverContent": BidiGenerateContentServerContent,
"toolCall": BidiGenerateContentToolCall,
"toolCallCancellation": BidiGenerateContentToolCallCancellation
}
지원되는 서버 메시지
다음 표에서 지원되는 서버 메시지를 확인하세요.
메시지 | 설명 |
---|---|
BidiGenerateContentSetupComplete |
설정이 완료될 때 클라이언트에서 전송하는 BidiGenerateContentSetup 메시지 |
BidiGenerateContentServerContent |
클라이언트 메시지에 대한 응답으로 모델에서 생성한 콘텐츠 |
BidiGenerateContentToolCall |
클라이언트가 함수 호출을 실행하고 일치하는 ID와 함께 응답을 반환하도록 요청 |
BidiGenerateContentToolCallCancellation |
사용자가 모델 출력을 중단하여 함수 호출이 취소되면 전송됩니다. |
메시지 및 이벤트
BidiGenerateContentClientContent
클라이언트에서 전송된 현재 대화의 증분 업데이트입니다. 여기에 있는 모든 콘텐츠는 무조건 대화 기록에 추가되며 콘텐츠를 생성하기 위한 모델에 대한 프롬프트의 일부로 사용됩니다.
여기에 메시지가 표시되면 현재 모델 생성이 중단됩니다.
필드 | |
---|---|
turns[] |
선택사항입니다. 모델과의 현재 대화에 추가된 콘텐츠입니다. 싱글턴 쿼리의 경우 이는 단일 인스턴스입니다. 멀티턴 쿼리의 경우 이는 대화 기록과 최근 요청이 포함된 반복 필드입니다. |
turn_ |
선택사항입니다. true인 경우 서버 콘텐츠 생성이 현재 누적된 프롬프트로 시작해야 함을 나타냅니다. 그렇지 않으면 서버는 생성을 시작하기 전에 추가 메시지를 기다립니다. |
BidiGenerateContentRealtimeInput
실시간으로 전송되는 사용자 입력입니다.
이는 BidiGenerateContentClientContent
와 몇 가지 차이점이 있습니다.
- 모델 생성을 중단하지 않고 연속으로 전송할 수 있습니다.
BidiGenerateContentClientContent
와BidiGenerateContentRealtimeInput
에서 교차 삽입된 데이터를 혼합해야 하는 경우 서버는 최적의 응답을 위해 최적화하려고 시도하지만 보장되지는 않습니다.- 턴 종료는 명시적으로 지정되지 않으며 대신 사용자 활동 (예: 음성 종료)에서 파생됩니다.
- 턴이 끝나기 전에도 모델의 응답을 빠르게 시작할 수 있도록 데이터가 점진적으로 처리됩니다.
- 항상 사용자의 입력으로 간주됩니다 (대화 기록을 채우는 데 사용할 수 없음). 중단 없이 연속으로 전송할 수 있습니다. 모델은 사용자 음성의 시작과 끝을 자동으로 감지하고 그에 따라 응답 스트리밍을 시작하거나 종료합니다. 데이터가 도착하는 대로 점진적으로 처리되므로 지연 시간이 최소화됩니다.
필드 | |
---|---|
media_ |
선택사항입니다. 미디어 입력을 위한 인라인 바이트 데이터입니다. |
BidiGenerateContentServerContent
클라이언트 메시지에 대한 응답으로 모델에서 생성된 증분 서버 업데이트입니다.
콘텐츠는 실시간이 아닌 최대한 빨리 생성됩니다. 클라이언트는 버퍼링하고 실시간으로 재생할 수 있습니다.
필드 | |
---|---|
turn_ |
출력 전용입니다. true인 경우 모델 생성이 완료되었음을 나타냅니다. 생성은 추가 클라이언트 메시지에 대한 응답으로만 시작됩니다. |
interrupted |
출력 전용입니다. true인 경우 클라이언트 메시지가 현재 모델 생성을 중단했음을 나타냅니다. 클라이언트가 콘텐츠를 실시간으로 재생하는 경우 현재 재생목록을 중지하고 비우는 것이 좋습니다. |
grounding_ |
출력 전용입니다. 생성된 콘텐츠의 그라운딩 메타데이터입니다. |
model_ |
출력 전용입니다. 모델이 사용자와의 현재 대화의 일부로 생성한 콘텐츠입니다. |
BidiGenerateContentSetup
첫 번째이자 유일한 첫 번째 클라이언트 메시지로 전송할 메시지입니다. 스트리밍 세션 기간 동안 적용할 구성을 포함합니다.
클라이언트는 추가 메시지를 보내기 전에 BidiGenerateContentSetupComplete
메시지를 기다려야 합니다.
필드 | |
---|---|
model |
필수입니다. 모델의 리소스 이름입니다. 이는 모델에서 사용할 ID로 사용됩니다. 형식: |
generation_ |
선택사항입니다. 생성 구성 다음 필드는 지원되지 않습니다.
|
system_ |
선택사항입니다. 사용자가 모델의 시스템 지침을 제공했습니다. 참고: 부분에는 텍스트만 사용해야 합니다. 각 부분의 콘텐츠는 별도의 단락에 위치합니다. |
tools[] |
선택사항입니다. 모델이 다음 응답을 생성하는 데 사용할 수 있는
|
BidiGenerateContentSetupComplete
이 유형에는 필드가 없습니다.
클라이언트의 BidiGenerateContentSetup
메시지에 대한 응답으로 전송됩니다.
BidiGenerateContentToolCall
클라이언트가 함수 호출을 실행하고 일치하는 id
와 함께 응답을 반환하도록 요청합니다.
필드 | |
---|---|
function_ |
출력 전용입니다. 실행할 함수 호출입니다. |
BidiGenerateContentToolCallCancellation
지정된 id
가 포함된 이전에 발급된 ToolCallMessage
가 실행되어서는 안 되며 취소되어야 한다는 클라이언트 알림입니다. 이러한 도구 호출에 부작용이 있는 경우 클라이언트는 도구 호출을 실행취소하려고 시도할 수 있습니다. 이 메시지는 클라이언트가 서버 전환을 중단하는 경우에만 표시됩니다.
필드 | |
---|---|
ids[] |
출력 전용입니다. 취소할 도구 호출의 ID입니다. |
BidiGenerateContentToolResponse
클라이언트가 서버에서 수신한 ToolCall
에 대한 응답을 생성했습니다. 개별 FunctionResponse
객체는 id
필드를 통해 각 FunctionCall
객체와 일치합니다.
단항 및 서버 스트리밍 GenerateContent API에서는 Content
부분을 교환하여 함수를 호출하는 반면, bidi GenerateContent API에서는 이러한 전용 메시지 세트를 통해 함수를 호출합니다.
필드 | |
---|---|
function_ |
선택사항입니다. 함수 호출에 대한 응답입니다. |
일반적인 유형에 대한 자세한 정보
일반적으로 사용되는 API 리소스 유형 Blob
, Content
, FunctionCall
, FunctionResponse
, GenerationConfig
, GroundingMetadata
, Tool
에 관한 자세한 내용은 콘텐츠 생성을 참고하세요.
타사 통합
웹 및 모바일 앱 배포의 경우 다음 옵션을 살펴볼 수 있습니다.