Molayo

© 2026 Molayo

Qiita헤드라인2026. 06. 15. 05:41

Lyria 3 Pro API 입문 — 텍스트로부터 프로 품질 AI 음악을 생성하는 완전 가이드

요약

Google DeepMind의 Lyria 3 Pro API를 사용하여 텍스트나 이미지로부터 고품질 음악을 생성하는 방법을 다룹니다. Gemini API를 활용한 Python 구현 방법과 곡 구성 제어, 이미지 기반 무드 매칭 기술을 상세히 설명합니다.

핵심 포인트

  • Lyria 3 Pro는 최대 3분 길이의 풀 트랙 음악 생성 가능
  • 섹션 태그를 통한 인트로, 벌스, 코러스 등 세밀한 곡 구성 제어
  • 이미지 입력을 활용한 시각적 무드 매칭 기능 지원
  • SynthID 및 C2PA를 통한 오디오 워터마크 및 콘텐츠 인증 적용
  • Python 및 Gemini API를 이용한 간편한 구현 가이드 제공

Google DeepMind가 개발한 Lyria 3 Pro는 텍스트 프롬프트나 이미지로부터 최대 3분간의 프로 품질 음악을 생성할 수 있는 AI 음악 모델입니다. 2026년 4월 7일에 Vertex AI 및 Gemini API를 통해 퍼블릭 프리뷰(Public Preview)로 공개되었습니다.

동일한 Lyria 시리즈인 「Lyria RealTime」은 WebSocket을 사용한 실시간 스트리밍용이지만, Lyria 3 Pro는 인트로(Intro)·벌스(Verse)·코러스(Chorus)·브릿지(Bridge)와 같은 곡 구성을 가진 풀 트랙(Full Track) 생성에 특화되어 있습니다.

이 기사에서는 Lyria 3 Pro를 Gemini API로부터 호출하는 방법을 Python 코드와 함께 해설합니다.

  • Lyria 3와 Lyria 3 Pro의 차이점 및 용도 구분

  • Gemini API를 통해 Python으로 음악을 생성하는 방법

  • 가사·템포·곡 구성의 상세한 제어 방법

  • 이미지 입력을 사용한 무드 매칭(Mood Matching) 생성

  • WAV 형식의 고품질 출력

  • 프롬프트 베스트 프랙티스(Best Practices)

  • AI 음악 생성을 제품이나 업무에 도입하고 싶은 엔지니어

  • 영상 BGM·게임 사운드트랙·팟캐스트 삽입 음악의 자동 생성에 힘쓰고 있는 분

  • Gemini API를 활용한 새로운 유스케이스(Use Case)를 찾고 있는 개발자

  • Python 3.10+

  • Gemini API 키 (Google AI Studio에서 취득)

  • google-genai 패키지 (v0.8+)

  • Lyria 3 Clip (lyria-3-clip-preview): 30초 클립 생성, 고속·양산형

  • Lyria 3 Pro (lyria-3-pro-preview): 최대 약 3분의 풀 곡 생성, 구성 제어 대응

    • 일반적인 generateContent API에 response_mime_type="audio/mp3"를 전달하는 것만으로 음악 생성이 시작됨
    • [Verse], [Chorus], [Bridge] 섹션 태그와 타임스탬프로 곡 구성을 세밀하게 제어 가능
    • 이미지를 최대 10장까지 입력할 수 있으며, 비주얼의 무드에 맞춘 음악 생성 가능
    • Lyria 3 Pro만 WAV (44.1kHz 스테레오) 출력에 대응
    • 모든 출력에 SynthID 오디오 워터마크 + C2PA 콘텐츠 인증이 자동으로 부여됨

두 모델은 생성 시간과 용도에 따라 명확하게 구분됩니다1.

항목Lyria 3 (Clip)Lyria 3 Pro
모델 IDlyria-3-clip-previewlyria-3-pro-preview
최대 생성 시간약 30초약 3분
출력 형식MP3MP3 / WAV
곡 구성 제어기본풀 (Intro/Verse/Chorus/Bridge/Outro)
...

Lyria 3 Clip은 짧은 사운드 스니펫(Snippet)을 고속으로 양산하는 용도에 최적이며, Lyria 3 Pro는 복잡한 곡 구성이 필요한 풀 트랙 제작에 사용합니다.

필요한 패키지를 설치합니다.

pip install google-genai pillow python-dotenv

API 키를 환경 변수에 설정합니다.

export GEMINI_API_KEY="your-api-key-here"

클라이언트 초기화는 다음과 같습니다.

from google import genai
from google.genai import types
import os
...

먼저 30초 클립으로 기본적인 동작을 확인합니다2.

from google import genai
from google.genai import types
import os
...

inline_data.data에 MP3 바이트 열이 저장되어 있습니다. hasattr 체크는 response_modalities에 TEXT를 포함할 경우 가사 텍스트 파트가 혼재되기 때문에 그에 대한 대책입니다.

모델을 lyria-3-pro-preview로 전환하는 것만으로 최대 3분의 음악을 생성할 수 있습니다.

response = client.models.generate_content(
model="lyria-3-pro-preview",
contents=(
...

프롬프트에 Duration: 3 minutes를 명시함으로써, Lyria 3 Pro의 풀 길이 (Full-length) 생성 능력을 최대한으로 끌어올릴 수 있습니다.

Lyria 3 Pro는 [Verse], [Chorus], [Bridge] 등의 섹션 태그와 타임스탬프(Timestamp) 지정에 의한 세밀한 구성 제어를 지원합니다2.

prompt = """
A heartfelt indie pop song. 90 BPM. Key of D major.
[Intro] 0:00-0:15
...
"""

response_modalities=["AUDIO", "TEXT"]를 지정하면, 오디오 데이터와 함께 생성된 가사 텍스트도 반환됩니다.

for part in response.candidates[0].content.parts:
if hasattr(part, "text"):
print("생성된 가사:")
...

공식 문서에서는 "텍스트 파트가 항상 처음은 아닐 수 있다"라고 명시되어 있으므로, hasattr을 통한 타입 체크 (Type check)로 각 파트를 처리하는 구현이 권장됩니다.

텍스트 외에도 최대 10장의 이미지를 입력하여 무드(Mood)나 분위기를 곡에 반영할 수 있습니다.

import PIL.Image
# 분위기 참조 이미지를 불러오기
image = PIL.Image.open("sunset_cityscape.jpg")
...

이 기능은 동영상 썸네일이나 사진첩의 BGM 자동 생성 등, 비주얼 콘텐츠와 음악의 연동에서 특히 효과적입니다. 여러 장의 이미지를 전달함으로써 스토리 전개에 따른 곡 생성도 가능합니다.

Lyria 3 Pro는 WAV (44.1kHz 스테레오) 출력을 지원합니다. Lyria 3 Clip에서는 WAV 형식을 사용할 수 없습니다.

response = client.models.generate_content(
model="lyria-3-pro-preview",
contents=(
...

WAV는 MP3에 비해 파일 크기가 크지만, 포스트 프로덕션 (Post-production)이나 DAW로의 가져오기 등 음악 제작 워크플로우 통합에 적합합니다.

Google Cloud의 공식 프롬프팅 가이드 (Prompting guide)에 기반한 포인트를 정리합니다.

요소구체적인 예시
장르`

훈련 데이터는 YouTube 및 Google 내의 권리 처리된 콘텐츠를 사용하고 있으며, 생성물이 기존 곡과 유사하지 않은지 확인하는 출력 필터링 (Output filtering)도 실시되고 있습니다.

비결정성 (Non-determinism): 동일한 프롬프트라도 매번 다른 결과가 생성됨
멀티턴 편집 미지원: "템포를 더 높여줘"와 같은 대화형 수정은 현재 지원되지 않음. 수정이 필요한 경우 프롬프트를 변경하여 재생성해야 함
특정 아티스트 이름 제한: 특정 아티스트의 목소리나 음악 스타일을 모방하도록 명시적으로 지시하면 세이프티 필터 (Safety filter)에 의해 거부될 수 있음
배치 API 및 캐싱 미지원: 대량 생성에는 자체적인 병렬 처리 구현이 필요함
WAV 출력은 Lyria 3 Pro에서만 가능: lyria-3-clip-preview에 audio/wav를 지정하면 에러가 발생함

Lyria 3 Pro (lyria-3-pro-preview)는 최대 3분의 풀 트랙(Full track)을 생성할 수 있으며, [Verse], [Chorus] 등의 섹션 태그와 타임스탬프(Timestamp)를 통해 구성을 세밀하게 제어할 수 있음
Lyria 3 Clip (lyria-3-clip-preview)은 30초 클립의 빠른 생성에 최적화되어 있어 대량 생산 용도에 적합함
일반적인 Gemini API의 generateContent를 response_mime_type="audio/mp3"로 호출하는 것만으로 음악 생성을 시작할 수 있음
이미지를 최대 10장까지 입력할 수 있어, 비주얼 콘텐츠의 분위기에 맞춘 음악 자동 생성이 가능함
SynthID 워터마크와 C2PA 인증이 모든 출력물에 자동으로 부여되어, 상업적 이용 시 컴플라이언스 (Compliance) 대응에 도움이 됨

영상 BGM, 게임 사운드트랙, 팟캐스트 삽입 음악 등 AI 음악 생성의 활용 영역은 넓어지고 있습니다. Gemini API의 범용 엔드포인트 (Endpoint)에서 심리스(Seamless)하게 호출할 수 있다는 점이 기존 AI 애플리케이션으로의 통합을 용이하게 합니다.

  • Lyria 3 음악 생성 가이드 (Gemini API)
  • Lyria 3 Pro Preview 모델 사양
  • Lyria 3와 Lyria 3 Pro on Vertex AI (Google Cloud Blog)
  • Lyria 3 Pro 공식 프롬프팅 가이드
  • 개발자용 Lyria 3 해설 (Google AI Blog)
  • Lyria 3 모델 사양 (Vertex AI)
  • SynthID 오디오 워터마크

AI 자동 생성 콘텐츠

본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0