ElevenLabs 완벽 설치 가이드 - API 키 발급부터 Python SDK 설정, 첫 음성 합성까지
ElevenLabs 완벽 설치 가이드: API 키 발급부터 첫 음성 합성까지
ElevenLabs는 최첨단 AI 음성 합성(TTS) 플랫폼으로, 자연스러운 인간 음성을 생성할 수 있습니다. 이 가이드에서는 계정 생성부터 Python SDK를 활용한 첫 음성 파일 생성까지 전체 워크플로우를 단계별로 안내합니다.
1단계: 계정 생성 및 API 키 발급
- 계정 생성:
elevenlabs.io에 접속하여 Sign Up 버튼을 클릭합니다. Google 계정 또는 이메일로 가입할 수 있습니다.- 플랜 선택: 무료 플랜(월 10,000자)으로 시작할 수 있습니다. 상업적 용도라면 Starter 이상 플랜을 권장합니다.- API 키 발급: 로그인 후 우측 상단 프로필 아이콘 →Profile + API key로 이동합니다.xi-api-key항목에서 API 키를 복사합니다.플랜 월 제공 글자 수 음성 클론 상업적 사용 Free 10,000자 3개 불가 Starter 30,000자 10개 가능 Creator 100,000자 30개 가능 Pro 500,000자 160개 가능
2단계: Python 환경 설정 및 SDK 설치
사전 요구사항
- Python 3.8 이상- pip 패키지 매니저
SDK 설치
# ElevenLabs Python SDK 설치
pip install elevenlabs
설치 확인
pip show elevenlabs
환경 변수로 API 키 설정
# Linux / macOS
export ELEVEN_API_KEY="YOUR_API_KEY"
# Windows PowerShell
$env:ELEVEN_API_KEY="YOUR_API_KEY"
# .env 파일 사용 (권장)
# .env 파일 생성 후 아래 내용 작성
ELEVEN_API_KEY=YOUR_API_KEY# python-dotenv로 .env 파일 로드
pip install python-dotenv
3단계: 첫 음성 합성 (Text-to-Speech)
기본 TTS 코드
from elevenlabs.client import ElevenLabs
from elevenlabs import play, save
import os
# 클라이언트 초기화
client = ElevenLabs(
api_key=os.getenv("ELEVEN_API_KEY") # 또는 직접 "YOUR_API_KEY" 입력
)
# 음성 합성 실행
audio = client.text_to_speech.convert(
voice_id="JBFqnCBsd6RMkjVDRZzb", # George 음성
model_id="eleven_multilingual_v2", # 다국어 모델 (한국어 지원)
text="안녕하세요, ElevenLabs 음성 합성 테스트입니다. 자연스러운 한국어 음성을 생성할 수 있습니다."
)
# 파일로 저장
save(audio, "output.mp3")
print("음성 파일이 output.mp3로 저장되었습니다.")
# 바로 재생 (mpv 또는 ffmpeg 필요)
# play(audio)4단계: 사용 가능한 음성 목록 조회
from elevenlabs.client import ElevenLabs
import os
client = ElevenLabs(api_key=os.getenv("ELEVEN_API_KEY"))
# 모든 사용 가능한 음성 조회
voices = client.voices.get_all()
for voice in voices.voices:
print(f"이름: {voice.name} | ID: {voice.voice_id} | 카테고리: {voice.category}")5단계: 스트리밍 음성 합성
긴 텍스트의 경우 스트리밍 방식으로 실시간 재생이 가능합니다.
from elevenlabs.client import ElevenLabs
import os
client = ElevenLabs(api_key=os.getenv(“ELEVEN_API_KEY”))
스트리밍 방식으로 음성 생성
audio_stream = client.text_to_speech.convert_as_stream(
voice_id=“JBFqnCBsd6RMkjVDRZzb”,
model_id=“eleven_multilingual_v2”,
text=“스트리밍 방식으로 생성되는 음성입니다. 긴 텍스트도 실시간으로 재생할 수 있습니다.”,
output_format=“mp3_44100_128”
)
스트리밍 데이터를 파일로 저장
with open(“stream_output.mp3”, “wb”) as f:
for chunk in audio_stream:
f.write(chunk)
print(“스트리밍 음성이 저장되었습니다.”)
6단계: 음성 설정 커스터마이징
from elevenlabs.client import ElevenLabs
from elevenlabs import VoiceSettings
import os
client = ElevenLabs(api_key=os.getenv("ELEVEN_API_KEY"))
audio = client.text_to_speech.convert(
voice_id="JBFqnCBsd6RMkjVDRZzb",
model_id="eleven_multilingual_v2",
text="음성 설정을 세밀하게 조정할 수 있습니다.",
voice_settings=VoiceSettings(
stability=0.5, # 안정성 (0.0~1.0, 낮을수록 표현력 증가)
similarity_boost=0.75, # 원본 음성 유사도 (0.0~1.0)
style=0.3, # 스타일 강도 (0.0~1.0)
use_speaker_boost=True # 스피커 부스트 활성화
)
)
from elevenlabs import save
save(audio, "custom_output.mp3")Pro Tips: 파워 유저를 위한 고급 팁
- 모델 선택: 영어 전용이라면
eleven_monolingual_v1이 더 빠릅니다. 한국어는 반드시eleven_multilingual_v2를 사용하세요.- 출력 포맷 최적화: 웹 서비스에는mp3_44100_128, 고품질 용도에는pcm_44100을 사용하세요.- SSML 활용: 일시 정지, 강조 등을 제어하려면 텍스트에client.user.get_subscription()으로 남은 글자 수를 수시로 확인하세요.- 비동기 처리: 대량 변환 시elevenlabs.client.AsyncElevenLabs클라이언트를 사용하면 처리 속도가 크게 향상됩니다.
Troubleshooting: 자주 발생하는 오류 해결
| 오류 | 원인 | 해결 방법 |
|---|---|---|
401 Unauthorized | API 키가 잘못되었거나 누락 | API 키를 재확인하고 환경 변수가 올바르게 설정되었는지 점검 |
429 Too Many Requests | API 호출 한도 초과 | 잠시 대기 후 재시도하거나 플랜을 업그레이드 |
ModuleNotFoundError: No module named 'elevenlabs' | SDK 미설치 또는 잘못된 Python 환경 | pip install elevenlabs 재실행, 가상환경 확인 |
ValidationError (voice_id) | 존재하지 않는 음성 ID | 음성 목록 조회 코드로 유효한 voice_id 확인 |
| 한국어 음성이 부자연스러움 | 단일 언어 모델 사용 | model_id를 eleven_multilingual_v2로 변경 |
play() 함수 작동 안 됨 | mpv 또는 ffmpeg 미설치 | brew install mpv (macOS) 또는 apt install mpv (Ubuntu) |
from elevenlabs.client import ElevenLabs import osclient = ElevenLabs(api_key=os.getenv(“ELEVEN_API_KEY”))
구독 정보 및 잔여 글자 수 확인
subscription = client.user.get_subscription() print(f”플랜: {subscription.tier}”) print(f”사용한 글자 수: {subscription.character_count}”) print(f”글자 수 한도: {subscription.character_limit}”) print(f”잔여 글자 수: {subscription.character_limit - subscription.character_count}“)
자주 묻는 질문 (FAQ)
Q1: ElevenLabs 무료 플랜으로 한국어 음성 합성이 가능한가요?
네, 가능합니다. 무료 플랜에서도 eleven_multilingual_v2 모델을 사용하여 한국어 음성을 생성할 수 있습니다. 다만 월 10,000자 제한이 있으므로 본격적인 활용을 위해서는 유료 플랜 업그레이드를 권장합니다. 무료 플랜에서 생성한 음성은 상업적으로 사용할 수 없다는 점도 유의하세요.
Q2: API 키 보안을 위해 어떤 방법을 사용해야 하나요?
API 키를 소스 코드에 직접 하드코딩하지 마세요. .env 파일에 저장하고 python-dotenv로 로드하는 방식을 권장합니다. .gitignore에 .env를 반드시 추가하여 Git에 커밋되지 않도록 하세요. 프로덕션 환경에서는 AWS Secrets Manager나 Azure Key Vault 같은 시크릿 관리 서비스를 활용하는 것이 가장 안전합니다.
Q3: 음성 클론 기능은 어떻게 사용하나요?
ElevenLabs는 Instant Voice Cloning과 Professional Voice Cloning 두 가지 방식을 지원합니다. Instant 방식은 짧은 음성 샘플(1분 이상 권장)을 업로드하면 즉시 사용 가능하며, SDK에서 client.clone() 메서드로 구현할 수 있습니다. Professional 방식은 더 긴 샘플(최소 30분)이 필요하지만 훨씬 높은 품질을 제공합니다. 음성 클론 사용 시 해당 음성 소유자의 동의가 반드시 필요합니다.