Live API에 새로운 네이티브 오디오 모델을 사용할 수 있습니다. 자세히 알아보기

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Live Music API - WebSockets API reference

Lyria RealTime 음악 생성은 WebSockets를 사용하여 영구적인 양방향 저지연 스트리밍 연결을 사용합니다. 이 섹션에서는 WebSockets API에 관한 추가 세부정보를 확인할 수 있습니다.

세션

WebSocket 연결은 모델과의 실시간 통신을 유지하기 위한 세션을 설정합니다. 클라이언트가 새 연결을 시작한 후 세션에서 서버와 메시지를 교환하여 다음 작업을 실행할 수 있습니다.

음악 생성을 유도하는 프롬프트와 컨트롤을 전송합니다.
음악 재생 컨트롤을 전송합니다.
오디오 청크를 수신합니다.

WebSocket 연결

세션을 시작하려면 다음 WebSocket 엔드포인트에 연결하세요.

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateMusic

세션 구성

연결 후의 초기 메시지는 세션 중에 사용할 모델을 설정합니다.

다음 구성 예시를 참고하세요. SDK의 이름 대소문자는 다를 수 있습니다. Python SDK 구성 옵션은 여기에서 확인할 수 있습니다.


{
  "model": string
}

메시지 보내기

WebSocket 연결을 통해 메시지를 교환하려면 클라이언트가 열린 WebSocket 연결을 통해 JSON 객체를 전송해야 합니다. JSON 객체는 다음 객체 세트의 필드 중 정확히 하나를 포함해야 합니다.


{
  "setup": BidiGenerateMusicSetup,
  "client_content": BidiGenerateMusicClientContent,
  "music_generation_config": BidiGenerateMusicGenerationConfig,
  "playback_control": BidiGenerateMusicPlaybackControl
}

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

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

메시지	설명
`BidiGenerateMusicSetup`	첫 번째 메시지에서만 전송되는 세션 구성
`BidiGenerateMusicClientContent`	가중치가 적용된 프롬프트를 모델 입력으로 사용
`BidiGenerateMusicGenerationConfig`	음악 생성 구성
`BidiGenerateMusicPlaybackControl`	모델 생성을 위한 재생 제어 신호

메시지 수신

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

다음을 참조하세요.

async def receive_audio(session):
  """Example background task to process incoming audio."""
  while True:
    async for message in session.receive():
      audio_data = message.server_content.audio_chunks[0].data
      # Process audio...
      await asyncio.sleep(10**-12)

async with (
  client.aio.live.music.connect(model='models/lyria-realtime-exp') as session,
  asyncio.TaskGroup() as tg,
):
  # Set up task to receive server messages.
  tg.create_task(receive_audio(session))

  # Send initial prompts and config
  await session.set_weighted_prompts(
    prompts=[
      types.WeightedPrompt(text='minimal techno', weight=1.0),
    ]
  )
  await session.set_music_generation_config(
    config=types.LiveMusicGenerationConfig(bpm=90, temperature=1.0)
  )

  # Start streaming music
  await session.play()

서버 메시지에는 BidiGenerateMusicServerMessage 메시지의 다른 필드 중 정확히 하나가 포함됩니다. (messageType 결합은 JSON으로 표현되지 않으므로 필드가 메시지의 최상위 수준에 표시됩니다.)

메시지 및 이벤트

AudioChunk

오디오 청크의 표현입니다.

필드
통합 필드 `content`. `content`는 다음 중 하나여야 합니다.
`data`	`bytes` 오디오 청크의 원시 바이트입니다.
`mimeType`	`string` 오디오 청크의 콘텐츠 MIME 유형입니다(예: 'audio/wav').
`sourceMetadata`	`SourceMetadata` 출력 전용입니다. 이 오디오 청크를 생성하는 데 사용된 프롬프트와 구성입니다.

SourceMetadata

이 오디오 청크를 생성하는 데 사용된 입력 소스에 관한 메타데이터입니다.

필드

clientContent

BidiGenerateMusicClientContent

이 오디오 청크를 생성하기 위한 가중치가 적용된 프롬프트입니다.

musicGenerationConfig

BidiGenerateMusicGenerationConfig

이 오디오 청크를 생성하기 위한 음악 생성 구성입니다.

BidiGenerateMusicClientContent

음악을 시작하거나 조작하기 위한 사용자 입력

필드

필드
`weightedPrompts[]`	`WeightedPrompt` 필수입니다. 가중치가 적용된 프롬프트를 모델 입력으로 사용합니다.

weightedPrompts[]

WeightedPrompt

필수입니다. 가중치가 적용된 프롬프트를 모델 입력으로 사용합니다.

BidiGenerateMusicClientMessage

BidiGenerateMusic 호출에서 클라이언트가 전송한 메시지입니다.

필드
통합 필드 `messageType`. `messageType`는 다음 중 하나여야 합니다.
`setup`	`BidiGenerateMusicSetup` 선택사항입니다. 세션 구성은 첫 번째 클라이언트 메시지에서만 전송됩니다.
`clientContent`	`BidiGenerateMusicClientContent` 선택사항입니다. 가중치가 적용된 프롬프트와 음악 생성 구성을 음악 생성의 입력으로 사용합니다.
`musicGenerationConfig`	`BidiGenerateMusicGenerationConfig` 선택사항입니다. 음악 생성 구성입니다.
`playbackControl`	`BidiGenerateMusicPlaybackControl` 선택사항입니다. 음악 생성을 위한 재생 제어 신호입니다.

BidiGenerateMusicFilteredPrompt

이유가 포함된 필터링된 프롬프트입니다.

필드

필드
`filteredReason`	`string` 출력 전용입니다. 프롬프트가 필터링된 이유입니다.
통합 필드 `prompt`. 필터링된 프롬프트입니다. `prompt`은 다음 중 하나여야 합니다.
`text`	`string` 선택사항입니다. 텍스트 프롬프트

filteredReason

string

출력 전용입니다. 프롬프트가 필터링된 이유입니다.

통합 필드 prompt. 필터링된 프롬프트입니다. prompt은 다음 중 하나여야 합니다.

text

string

선택사항입니다. 텍스트 프롬프트

BidiGenerateMusicGenerationConfig

음악 생성 구성입니다.

필드
`temperature`	`float` 선택사항입니다. 오디오 생성의 분산을 제어합니다. 값이 클수록 분산이 커집니다. 범위는 [0.0, 3.0]입니다. 기본값은 1.1입니다.
`topK`	`int32` 선택사항입니다. 모델이 출력용 토큰을 선택하는 방식을 제어합니다. 확률이 가장 높은 topK 토큰을 샘플링합니다. 범위는 [1, 1000]입니다. 기본값은 40입니다.
`seed`	`int32` 선택사항입니다. 오디오 생성을 시드합니다. 설정하지 않으면 요청에서 무작위로 생성된 시드를 사용합니다.
`guidance`	`float` 선택사항입니다. 모델이 프롬프트를 얼마나 엄격하게 따르는지 제어합니다. 안내를 더 잘 따르지만 전환이 더 갑작스러워집니다. 범위는 [0.0, 6.0]입니다. 기본값은 4.0입니다.
`bpm`	`int32` 선택사항입니다. 분당 심박수입니다. 범위는 [60, 200]입니다.
`density`	`float` 선택사항입니다. 소리의 밀도입니다. 범위는 [0.0, 1.0]입니다.
`brightness`	`float` 선택사항입니다. 값이 높을수록 오디오가 더 밝아집니다. 범위는 [0.0, 1.0]입니다.
`scale`	`Scale` 선택사항입니다. 생성된 음악의 스케일입니다.
`muteBass`	`bool` 선택사항입니다. 오디오 출력에 베이스가 포함되어서는 안 됩니다.
`muteDrums`	`bool` 선택사항입니다. 오디오 출력에 드럼이 포함되어서는 안 됩니다.
`onlyBassAndDrums`	`bool` 선택사항입니다. 오디오 출력에는 베이스와 드럼만 포함되어야 합니다.
`musicGenerationMode`	`MusicGenerationMode` 선택사항입니다. 음악 생성 모드입니다. 기본값은 QUALITY입니다.

MusicGenerationMode

열거형
`MUSIC_GENERATION_MODE_UNSPECIFIED`	이 값은 사용되지 않습니다.
`QUALITY`	이 모드는 텍스트 프롬프트를 고품질 음악이 있는 잠재 공간 영역으로 안내합니다.
`DIVERSITY`	이 모드는 텍스트 프롬프트를 음악의 다양성이 더 큰 잠재 공간 영역으로 안내합니다.
`VOCALIZATION`	이 모드는 텍스트 프롬프트를 보컬 음악을 생성할 가능성이 더 높은 잠재 공간 영역으로 안내합니다.

확장

생성된 음악의 스케일입니다.

열거형
`SCALE_UNSPECIFIED`	기본값 이 값은 사용되지 않습니다.
`C_MAJOR_A_MINOR`	C장조 또는 A단조
`D_FLAT_MAJOR_B_FLAT_MINOR`	D 플랫 장조 또는 B 플랫 단조
`D_MAJOR_B_MINOR`	D장조 또는 B단조
`E_FLAT_MAJOR_C_MINOR`	E 플랫 장조 또는 C 단조
`E_MAJOR_D_FLAT_MINOR`	E장조 또는 D플랫 단조
`F_MAJOR_D_MINOR`	F장조 또는 D단조
`G_FLAT_MAJOR_E_FLAT_MINOR`	G 플랫 장조 또는 E 플랫 단조
`G_MAJOR_E_MINOR`	G장조 또는 E단조
`A_FLAT_MAJOR_F_MINOR`	A 플랫 장조 또는 F 단조
`A_MAJOR_G_FLAT_MINOR`	A장조 또는 G플랫 단조
`B_FLAT_MAJOR_G_MINOR`	B 플랫 장조 또는 G 단조
`B_MAJOR_A_FLAT_MINOR`	B장조 또는 A플랫 단조

BidiGenerateMusicPlaybackControl

음악 생성의 재생 컨트롤입니다.

열거형
`PLAYBACK_CONTROL_UNSPECIFIED`	이 값은 사용되지 않습니다.
`PLAY`	음악 생성을 시작합니다.
`PAUSE`	음악 생성을 보류합니다. PLAY를 사용하여 현재 위치에서 다시 시작합니다.
`STOP`	음악 생성을 중지하고 컨텍스트를 재설정합니다 (프롬프트는 유지됨). PLAY를 사용하여 음악 생성을 다시 시작합니다.
`RESET_CONTEXT`	음악 생성을 중지하지 않고 컨텍스트를 재설정합니다 (프롬프트는 유지됨).

BidiGenerateMusicServerContent

클라이언트 메시지에 대한 응답으로 모델에서 생성된 증분 서버 업데이트입니다.

콘텐츠는 실시간이 아닌 최대한 빨리 생성됩니다. 클라이언트는 버퍼링 및 실시간 재생을 선택할 수 있습니다.

필드

필드
`audioChunks[]`	`AudioChunk` 출력 전용입니다. 모델이 생성한 오디오 청크입니다.

audioChunks[]

AudioChunk

출력 전용입니다. 모델이 생성한 오디오 청크입니다.

BidiGenerateMusicServerMessage

BidiGenerateMusic 호출의 응답 메시지입니다.

필드
통합 필드 `messageType`. 메시지 유형입니다. `messageType`은 다음 중 하나여야 합니다.
`setupComplete`	`BidiGenerateMusicSetupComplete` 출력 전용입니다. 설정이 완료되면 클라이언트의 `BidiGenerateMusicSetup` 메시지에 대한 응답으로 전송됩니다.
`serverContent`	`BidiGenerateMusicServerContent` 출력 전용입니다. 클라이언트 메시지에 대한 응답으로 모델에서 생성된 콘텐츠입니다.
`filteredPrompt`	`BidiGenerateMusicFilteredPrompt` 출력 전용입니다. 이유가 포함된 필터링된 프롬프트입니다.
`warning`	`string` 출력 전용입니다. 서버의 경고 메시지입니다. 경고로 인해 스트림이 종료되지는 않습니다.

BidiGenerateMusicSetup

첫 번째 BidiGenerateMusicClientMessage에서 전송할 메시지 (첫 번째에서만 전송).

클라이언트는 추가 메시지를 보내기 전에 BidiGenerateMusicSetupComplete 메시지를 기다려야 합니다.

필드

필드
`model`	`string` 필수입니다. 모델의 리소스 이름입니다. 이는 모델에서 사용할 ID로 사용됩니다. 형식: `models/{model}`

model

string

필수입니다. 모델의 리소스 이름입니다. 이는 모델에서 사용할 ID로 사용됩니다.

형식: models/{model}

BidiGenerateMusicSetupComplete

이 유형에는 필드가 없습니다.

클라이언트의 BidiGenerateMusicSetup 메시지에 대한 응답으로 전송됩니다.

WeightedPrompt

가중치가 적용된 프롬프트를 모델 입력으로 사용합니다.

필드

필드
`weight`	`float` 필수입니다. 프롬프트의 가중치입니다. 가중치는 프롬프트의 상대적 중요도를 제어하는 데 사용됩니다. 가중치가 높을수록 가중치가 낮은 것보다 더 중요합니다. 이 BidiGenerateMusicClientContent에 있는 모든 weighted_prompts의 가중치가 모두 0이어서는 안 됩니다. 이 BidiGenerateMusicClientContent 메시지에 있는 모든 weighted_prompts의 가중치가 정규화됩니다.
통합 필드 `prompt`. `prompt`는 다음 중 하나여야 합니다.
`text`	`string` 텍스트 프롬프트

weight

float

필수입니다. 프롬프트의 가중치입니다.

가중치는 프롬프트의 상대적 중요도를 제어하는 데 사용됩니다. 가중치가 높을수록 가중치가 낮은 것보다 더 중요합니다.

이 BidiGenerateMusicClientContent에 있는 모든 weighted_prompts의 가중치가 모두 0이어서는 안 됩니다. 이 BidiGenerateMusicClientContent 메시지에 있는 모든 weighted_prompts의 가중치가 정규화됩니다.

통합 필드 prompt.

prompt는 다음 중 하나여야 합니다.

text

string

텍스트 프롬프트

유형에 대한 추가 정보

API에서 사용되는 유형에 관한 자세한 내용은 Python SDK를 참고하세요.