Multimodal Live API

Multimodal Live API를 사용하면 Gemini와 양방향 음성 및 동영상 상호작용을 지연 시간 없이 지원할 수 있습니다. Multimodal Live API를 사용하면 최종 사용자에게 자연스럽고 인간과 같은 음성 대화 환경을 제공하고 음성 명령을 사용하여 모델의 응답을 중단할 수 있는 기능을 제공할 수 있습니다. 이 모델은 텍스트, 오디오, 동영상 입력을 처리할 수 있으며 텍스트 및 오디오 출력을 제공할 수 있습니다.

기능

Multimodal Live API에는 다음과 같은 주요 기능이 포함됩니다.

• 멀티모달리티: 모델이 보고, 듣고, 말할 수 있습니다.
• 짧은 지연 시간의 실시간 상호작용: 빠른 응답을 제공합니다.
• 세션 메모리: 모델은 단일 세션 내의 모든 상호작용에 관한 메모리를 유지하여 이전에 듣거나 본 정보를 호출합니다.
• 함수 호출, 코드 실행, 검색 도구 지원: 외부 서비스 및 데이터 소스와 통합할 수 있습니다.
• 자동 음성 활동 감지 (VAD): 모델은 사용자가 말하기 시작하고 중지하는 시점을 정확하게 인식할 수 있습니다. 이를 통해 자연스러운 대화형 상호작용이 가능하며 사용자가 언제든지 모델을 중단할 수 있습니다.

Google AI Studio에서 멀티모달 실시간 API를 사용해 볼 수 있습니다.

시작하기

멀티모달 실시간 API는 WebSockets를 사용하는 상태ful API입니다.

이 섹션에서는 Python 3.9 이상을 사용하여 텍스트 간 생성에 멀티모달 실시간 API를 사용하는 방법의 예를 보여줍니다.

Gemini API 라이브러리 설치

google-genai 패키지를 설치하려면 다음 pip 명령어를 사용합니다.

!pip3 install google-genai

종속 항목 가져오기

종속 항목을 가져오려면 다음 단계를 따르세요.

from google import genai

문자 메시지 주고받기

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model_id = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model_id, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(message, end_of_turn=True)

            async for response in session.receive():
                if response.text is None:
                    continue
                print(response.text, end="")

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

통합 가이드

이 섹션에서는 Multimodal Live API와의 통합이 작동하는 방식을 설명합니다.

세션

세션은 클라이언트와 Gemini 서버 간의 단일 WebSocket 연결을 나타냅니다.

클라이언트가 새 연결을 시작한 후 세션은 서버와 메시지를 교환하여 다음 작업을 실행할 수 있습니다.

• 텍스트, 오디오 또는 동영상을 Gemini 서버로 전송합니다.
• Gemini 서버에서 오디오, 텍스트 또는 함수 호출 응답을 수신합니다.

세션 구성은 연결 후 첫 번째 메시지로 전송됩니다. 세션 구성에는 모델, 생성 매개변수, 시스템 안내, 도구가 포함됩니다.

다음 구성 예시를 참고하세요.

{​​
  "model": string,
  "generation_config": {​
    "candidate_count": integer,
    "max_output_tokens": integer,
    "temperature": number,
    "top_p": number,
    "top_k": integer,
    "presence_penalty": number,
    "frequency_penalty": number,
    "response_modalities": string,
    "speech_config":object
  },

  "system_instruction": "",
  "tools":[]
}

자세한 내용은 BidiGenerateContentSetup을 참고하세요.

메시지 보내기

메시지는 WebSocket 연결을 통해 교환되는 JSON 형식의 문자열입니다.

메시지를 전송하려면 클라이언트가 지원되는 클라이언트 메시지를 JSON 형식 문자열로 전송해야 하며, 이때 열린 WebSocket 연결을 통해 전송해야 합니다.

지원되는 클라이언트 메시지

지원되는 클라이언트 메시지는 다음 표를 참고하세요.

메시지 수신

Gemini에서 메시지를 수신하려면 WebSocket 'message' 이벤트를 수신 대기한 다음 지원되는 서버 메시지의 정의에 따라 결과를 파싱합니다.

다음을 참조하세요.

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

지원되는 서버 메시지

다음 표에서 지원되는 서버 메시지를 확인하세요.

증분 콘텐츠 업데이트

증분 업데이트를 사용하여 텍스트 입력을 전송하거나 세션 컨텍스트를 설정하거나 복원합니다. 짧은 컨텍스트의 경우 세부 경로 상호작용을 전송하여 정확한 이벤트 시퀀스를 나타낼 수 있습니다. 컨텍스트가 긴 경우 후속 상호작용에 사용할 수 있도록 컨텍스트 창을 확보할 수 있도록 단일 메시지 요약을 제공하는 것이 좋습니다.

다음 컨텍스트 메시지 예시를 참고하세요.

{
  "client_content": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turn_complete": true
  }
}

콘텐츠 부분은 functionResponse 유형일 수 있지만 BidiGenerateContentClientContent은 모델에서 실행된 함수 호출에 응답을 제공하는 데 사용해서는 안 됩니다. 대신 BidiGenerateContentToolResponse를 사용해야 합니다. BidiGenerateContentClientContent는 이전 맥락을 설정하거나 대화에 텍스트 입력을 제공하는 데만 사용해야 합니다.

오디오 및 동영상 스트리밍

함수 호출

모든 함수는 BidiGenerateContentSetup 메시지의 일부로 도구 정의가 전송되어 세션 시작 시 선언되어야 합니다.

함수 호출에 관한 자세한 내용은 함수 호출 튜토리얼을 참고하세요.

모델은 단일 프롬프트에서 여러 함수 호출과 출력을 연결하는 데 필요한 코드를 생성할 수 있습니다. 이 코드는 샌드박스 환경에서 실행되어 후속 BidiGenerateContentToolCall 메시지를 생성합니다. 각 함수 호출의 결과를 사용할 수 있을 때까지 실행이 일시중지되므로 순차 처리가 보장됩니다.

클라이언트는 BidiGenerateContentToolResponse로 응답해야 합니다.

오디오 입력과 오디오 출력은 모델의 함수 호출 사용 능력에 부정적인 영향을 미칩니다.

오디오 형식

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

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

시스템 안내

시스템 안내를 제공하여 모델의 출력을 더 효과적으로 제어하고 오디오 응답의 어조와 감정을 지정할 수 있습니다.

시스템 안내는 상호작용이 시작되기 전에 프롬프트에 추가되며 전체 세션 동안 유효합니다.

시스템 안내는 초기 연결 직후 세션이 시작될 때만 설정할 수 있습니다. 세션 중에 모델에 추가 입력을 제공하려면 점진적 콘텐츠 업데이트를 사용하세요.

중단

사용자는 언제든지 모델의 출력을 중단할 수 있습니다. 음성 활동 감지 (VAD)가 중단을 감지하면 진행 중인 생성이 취소되고 삭제됩니다. 이미 클라이언트로 전송된 정보만 세션 기록에 보관됩니다. 그런 다음 서버는 BidiGenerateContentServerContent 메시지를 전송하여 중단을 보고합니다.

또한 Gemini 서버는 대기 중인 모든 함수 호출을 삭제하고 취소된 호출의 ID가 포함된 BidiGenerateContentServerContent 메시지를 전송합니다.

음성

멀티모달 실시간 API는 Aoede, Charon, Fenrir, Kore, Puck 음성을 지원합니다.

음성을 지정하려면 세션 구성의 일부로 speech_config 객체 내에서 voice_name를 설정합니다.

speech_config 객체의 다음 JSON 표현을 참고하세요.

{
  "voice_config": {
    "prebuilt_voice_config ": {
      "voice_name": <var>VOICE_NAME</var>
    }
  }
}

제한사항

프로젝트를 계획할 때는 멀티모달 실시간 API 및 Gemini 2.0의 다음 제한사항을 고려하세요.

클라이언트 인증

멀티모달 라이브 API는 서버 간 인증만 제공하며 직접 클라이언트용으로 사용하지 않는 것이 좋습니다. 클라이언트 입력은 멀티모달 라이브 API와의 보안 인증을 위해 중간 애플리케이션 서버를 통해 라우팅되어야 합니다.

웹 및 모바일 앱의 경우 Daily의 파트너 통합을 사용하는 것이 좋습니다.

대화 기록

모델은 세션 내 상호작용을 추적하지만 대화 기록은 저장되지 않습니다. 세션이 종료되면 해당 컨텍스트가 삭제됩니다.

이전 세션을 복원하거나 모델에 사용자 상호작용의 이전 맥락을 제공하려면 애플리케이션이 자체 대화 로그를 유지하고 BidiGenerateContentClientContent 메시지를 사용하여 새 세션이 시작될 때 이 정보를 전송해야 합니다.

최대 세션 시간

세션 시간은 오디오의 경우 최대 15분, 오디오 및 동영상의 경우 최대 2분으로 제한됩니다. 세션 시간이 한도를 초과하면 연결이 종료됩니다.

또한 모델은 컨텍스트 크기에 따라 제한됩니다. 동영상 및 오디오 스트림과 함께 대용량 콘텐츠를 전송하면 세션이 더 일찍 종료될 수 있습니다.

음성 활동 감지 (VAD)

이 모델은 연속 오디오 입력 스트림에서 음성 활동 감지 (VAD)를 자동으로 실행합니다. VAD는 항상 사용 설정되어 있으며 매개변수는 구성할 수 없습니다.

토큰 수

토큰 수는 지원되지 않습니다.

비율 제한

다음 비율 한도가 적용됩니다.

• API 키당 동시 세션 3개
• 분당 토큰 4백만 개

메시지 및 이벤트

일반적인 유형에 대한 자세한 정보

일반적으로 사용되는 API 리소스 유형 Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata, Tool에 관한 자세한 내용은 콘텐츠 생성을 참고하세요.