Python 음성 합성: 오디오를 WAV 파일로 저장하기

Python에서 텍스트를 음성으로 바꾸려면 음성 모델에 원문을 보내고 반환된 오디오를 저장하세요. 이 가이드에서는 Cartesia Python SDK와 Sonic으로 WAV 파일을 생성합니다.

Python 3.9 이상, 인터넷 연결, API 접근 권한이 있는 Cartesia 계정이 필요합니다. 아래 예제는 SDK 4.2.0을 대상으로 합니다.¹ 호스팅 API를 호출하므로 텍스트가 기기 밖으로 전송됩니다. 오프라인 합성이 필요하다면 로컬 음성 엔진을 사용하세요.

Python SDK 설치

프로젝트 디렉터리에 가상 환경을 만드세요.

python -m venv .venv

macOS나 Linux에서는 다음과 같이 활성화하세요.

source .venv/bin/activate

Windows PowerShell에서는 다음을 사용하세요.

.venv\Scripts\Activate.ps1

이 가이드에서 사용하는 버전을 설치하세요.

python -m pip install "cartesia==4.2.0"

시스템이 python 대신 python3를 사용한다면 해당 명령으로 환경을 만드세요. SDK 버전을 고정하면 예제의 메서드 이름을 일정하게 유지할 수 있습니다. 업그레이드할 때는 SDK 릴리스 노트에서 변경 사항을 확인하세요.

API 키 설정

Cartesia Playground에서 API 키를 만들고 음성 합성 생성에 필요한 권한을 부여하세요. Python을 실행할 터미널에서 키를 설정하세요.

macOS 또는 Linux:

export CARTESIA_API_KEY="your-api-key"

Windows PowerShell:

$env:CARTESIA_API_KEY = "your-api-key"

your-api-key를 자신의 키로 바꾸세요. 비밀번호처럼 다뤄야 합니다. Git에 커밋하거나 공개 노트북에 붙여 넣거나 브라우저 코드에 넣지 마세요. 배포한 앱에서는 서버의 비밀 정보 관리 도구에 보관하세요. 키가 노출되면 폐기하고 새로 만드세요.

WAV 파일 생성 및 저장

다음을 speak.py로 저장하세요.

import os
from pathlib import Path

from cartesia import Cartesia

api_key = os.environ.get("CARTESIA_API_KEY")
if not api_key:
    raise SystemExit("Set CARTESIA_API_KEY before running this script.")

output_path = Path("hello.wav")

with Cartesia(api_key=api_key) as client:
    response = client.tts.generate(
        model_id="sonic-latest",
        transcript="Hello from Python. Your first audio file is ready.",
        voice="e07c00bc-4134-4eae-9ea4-1a55fb45746b",
        output_format={
            "container": "wav",
            "encoding": "pcm_f32le",
            "sample_rate": 44100,
        },
    )
    response.write_to_file(output_path)

print(f"Saved audio to {output_path.resolve()}")

같은 터미널에서 실행하세요.

python speak.py

요청에 성공하면 부동소수점 PCM WAV를 지원하는 오디오 플레이어로 hello.wav를 여세요. 스크립트가 전체 경로를 출력하므로 Python이 사용한 디렉터리를 추측할 필요가 없습니다. 오디오를 저장할 뿐 자동 재생하지는 않습니다. 다시 실행하면 hello.wav를 덮어쓰고 API 요청을 한 번 더 보냅니다.

요청은 SDK의 공개 사용 예제를 따릅니다.¹ 음성 ID는 해당 자료의 예시 목소리입니다. 자신의 계정에서 사용할 수 있는 음성 ID로 바꿀 수 있습니다.

목소리, 모델, 오디오 형식 선택

transcript는 Sonic이 말할 텍스트입니다. 긴 문서를 보내기 전에 한 문장부터 시작하세요. API로 보내도 되는 텍스트를 사용하고 비공개 원문을 애플리케이션 로그에 남기지 마세요.

voice는 화자를 선택합니다. 음성 생성기에서 문장을 테스트한 뒤 선택한 목소리의 ID를 요청에 사용하세요. 표시 이름과 음성 ID는 다릅니다. 복제한 목소리를 사용한다면 화자의 목소리를 사용할 권한이 있는지 확인하세요.

예제는 SDK 참조와 같이 sonic-latest를 사용합니다. 모델 별칭은 설치한 SDK와 관계없이 바뀔 수 있습니다. 반복 가능한 프로덕션 테스트를 위해 모델 문서에서 지원하는 특정 모델 ID를 선택하고 음성 ID 및 테스트 텍스트와 함께 기록하세요.

출력 형식은 오디오 파일을 설명합니다.

원시 PCM에는 WAV 헤더가 없습니다. 원시 PCM 파일의 확장자를 .wav로 바꿔도 WAV 파일이 되지 않습니다. 전화 시스템이나 다른 서비스로 오디오를 보낸다면 음성을 생성하기 전에 필요한 컨테이너, 인코딩, 샘플레이트를 확인하세요.

흔한 오류 해결

도움을 요청할 때는 Python과 SDK 버전, 상태 코드, 오류와 함께 반환된 요청 ID를 포함하세요. 먼저 API 키와 비공개 텍스트를 제거하세요.

스트리밍을 사용하는 경우

WAV 파일 저장은 내레이션, 보이스오버, 통합 확인에 유용합니다. 대화형 앱은 전체 응답이 준비되기 전에 오디오를 재생하거나 LLM이 생성하는 대로 텍스트를 받아야 할 수 있습니다.

이 경우 같은 환경에 WebSocket 지원을 설치하세요.

python -m pip install "cartesia[websockets]==4.2.0"

그런 다음 SDK의 스트리밍 입력 WebSocket 예제부터 시작하세요.¹ 오디오 재생, 버퍼링, 끼어들기 처리도 필요합니다. 도착하는 청크를 디스크에 쓰는 것만으로 실시간 발화가 구현되지는 않습니다.

짧은 예제가 작동하면 원문을 앱에서 사용하는 문장으로 바꾸세요. 대량 생성 전에 이름, 숫자, 약어를 들어보세요. API 요금을 확인하고 테스트 결과와 함께 모델 및 음성 ID를 보관하세요.