실시간 애플리케이션을 위한 Python 텍스트 음성 변환 API

Cartesia Python SDK로 텍스트를 음성으로 바꾸세요. WAV 파일을 저장하거나, 애플리케이션에 오디오를 스트리밍하거나, Sonic을 실시간 음성 에이전트에 연결하세요.
API 키 받기Python 예제 보기
speech.py
audio = client.tts.generate(
    transcript="Hello, world.",
    model_id="sonic-3.6",
    voice=voice_id,
    output_format=wav_format,
)
audio.write_to_file("speech.wav")

speech.wav

전체 예제

첫 텍스트 음성 변환 요청

Cartesia Python SDK로 스크립트를 WAV 녹음으로 바꾸세요. 패키지를 설치하고 API 키를 추가한 뒤 서버에서 예제를 실행하세요.

Python SDK 레퍼런스

SDK 설치

가상 환경에서 Python 3.9 이상을 사용하세요.

터미널
python -m pip install --upgrade cartesia

API 키 설정

Playground에서 키를 만드세요. 아래 자리표시자를 교체하고 키는 서버에 보관하세요.

macOS / Linux
export CARTESIA_API_KEY="your-api-key"

PowerShell을 사용하시나요?$env:CARTESIA_API_KEY="your-api-key"

첫 녹음 생성

이 예제를 다음 이름으로 저장하세요. speech.py. 터미널에서 실행한 다음 다음 파일을 열어 speech.wav 들어보세요.

터미널
python speech.py

다른 결과를 들으려면 전사문을 바꾸거나 Playground에서 음성 ID를 선택하세요.

출력 파일
speech.wav
오디오 형식
44.1 kHz, 16-bit PCM
speech.py
import os
from cartesia import Cartesia

with Cartesia(api_key=os.environ["CARTESIA_API_KEY"]) as client:
    audio = client.tts.generate(
        model_id="sonic-3.6",
        transcript="Hello from your Python application.",
        voice="db6b0ed5-d5d3-463d-ae85-518a07d3c2b4",
        output_format={
            "container": "wav",
            "encoding": "pcm_s16le",
            "sample_rate": 44100,
        },
    )
    audio.write_to_file("speech.wav")

앱에 오디오를 전달하는 방식 선택

적절한 전송 방식은 텍스트가 준비되는 시점과 응답을 재생할 방식에 따라 달라집니다.

녹음 저장

전송 방식
HTTP
출력
WAV 또는 MP3

전체 스크립트를 오디오로 변환해 나중에 재생할 수 있도록 저장하세요. 위 예제는 오디오 플레이어가 읽을 수 있는 헤더를 갖춘 WAV 파일을 생성합니다.

오디오 출력 레퍼런스 읽기

텍스트가 들어오는 즉시 말하기

전송 방식
WebSocket
출력
원시 오디오 청크

LLM이 작성하는 대로 텍스트 조각을 보내고 Sonic이 생성하는 대로 오디오 청크를 받으세요. 요청한 오디오 형식으로 설정된 플레이어에 청크를 전달하세요.

스트리밍 예제 만들기

완성된 스크립트에서 오디오 스트리밍

전체 텍스트가 준비되어 있나요? 다음을 사용해 with_streaming_response HTTP 응답을 청크 단위로 읽으세요.

LLM 응답처럼 생성 도중 새 텍스트가 들어오는 경우 WebSocket 스트리밍을 사용하세요.

키는 서버에 보관

Python 백엔드가 요청을 처리하고 웹 앱, 모바일 앱, 전화 시스템이 재생을 담당할 수 있습니다.

01

Python 서버

환경에서 API 키를 읽으세요. 각 요청에 사용할 음성, 모델, 오디오 설정을 선택하세요.

02

Sonic

텍스트를 음성으로 변환하세요. 오디오 응답을 받거나 점진적인 입력을 위해 WebSocket을 열린 상태로 유지하세요.

03

애플리케이션

녹음을 저장하거나 플레이어에 오디오를 전달하세요. 인코딩과 샘플 레이트를 응답에 맞추세요.

스크립트에서 프로덕션 서비스로

성공적인 API 요청은 시작에 불과합니다. 청취자가 사용할 애플리케이션에 맞게 주변 동작을 구축하세요.

Python 스택에 맞추기

스크립트와 백그라운드 작업에는 동기 클라이언트를 사용하세요. FastAPI 같은 비동기 서비스에서는 AsyncCartesia를 사용하세요. 작업이 끝나면 클라이언트를 닫고 오디오를 저장소나 재생 서비스에 전달하세요.

전체 청취 경험 테스트

요청 시간 제한을 설정하고 속도 제한을 처리하세요. 출시할 음성으로 실제에 가까운 스크립트를 테스트하세요. 대화에서는 음성이 들릴 때까지의 시간을 측정하고 사용자가 끼어들면 대기 중인 재생이 중단되는지 확인하세요. 네트워크와 플레이어는 청취 경험에 영향을 줍니다.

엔터프라이즈 수준의 보안.클라우드에서 로컬까지.

  • HIPAA 준수 배지

    HIPAA 준수

  • SOC 2 Type 2 배지

    SOC 2 Type 2

  • GDPR 배지

    GDPR

  • PCI 배지

    PCI

Python 텍스트 음성 변환 질문

Python에서 텍스트를 음성으로 변환하려면 어떻게 하나요?

cartesia를 설치하고 서버 환경에 CARTESIA_API_KEY를 설정한 후 Cartesia 클라이언트를 만드세요. 대본, 모델, 음성 ID, 출력 형식을 지정해 client.tts.generate를 호출하고 write_to_file로 응답을 저장하세요. 이 페이지의 예제는 speech.wav를 생성합니다. 전체 요청은 Python 예제를 확인하세요.

어떤 Python 버전과 SDK가 필요한가요?

공식 SDK에는 Python 3.9 이상이 필요합니다. python -m pip install --upgrade cartesia로 설치하세요. WebSocket을 지원하려면 python -m pip install "cartesia[websockets]"를 설치하세요. 이전 예제를 수정할 때는 설치된 패키지 버전을 SDK 문서와 비교하세요.

생성된 음성을 WAV 또는 MP3로 저장할 수 있나요?

네. TTS 엔드포인트는 WAV, MP3, 원시 오디오 출력을 지원합니다. 음성을 생성하기 전에 output_format에서 컨테이너와 지원 설정을 선택하세요. 이 페이지의 예제에는 WAV를 사용하고, 애플리케이션에서 MP3가 필요하다면 해당 형식을 선택하세요. 파일 확장자만 바꿔서는 오디오가 변환되지 않습니다.

Python에서 LLM 응답을 음성으로 스트리밍하려면 어떻게 하나요?

애플리케이션이 텍스트를 조금씩 받는다면 WebSocket을 사용하세요. 공유 생성 컨텍스트를 통해 텍스트 청크를 전송하고 반환되는 오디오 청크를 도착하는 대로 처리하세요. 오디오의 버퍼링과 재생은 애플리케이션이 담당해야 합니다. WebSocket API는 대화형 애플리케이션의 연속 생성과 취소를 설명합니다.

텍스트 음성 변환에는 HTTP와 WebSocket 중 무엇을 사용해야 하나요?

완성된 내레이션이나 알림처럼 대본이 이미 준비되어 있다면 HTTP를 사용하세요. HTTP 응답도 오디오를 순차적으로 전달할 수 있습니다. 텍스트를 점진적으로 보내거나 계속되는 대화를 관리해야 한다면 WebSocket을 사용하세요. 입력 스트리밍과 출력 스트리밍은 별개의 선택이며, HTTP 응답은 파일 저장 외의 방식으로도 처리할 수 있습니다.

비동기 Python 또는 FastAPI에서 Cartesia를 사용할 수 있나요?

네. 비동기 애플리케이션에서 AsyncCartesia를 사용하고 API 호출을 await로 기다리세요. SDK의 비동기 예제는 생성, 파일 출력, 스트리밍을 보여줍니다. 반환된 오디오를 애플리케이션의 응답이나 플레이어에 연결하고 수명 주기가 끝나면 클라이언트를 닫으세요.

Cartesia API 키는 어디에 저장해야 하나요?

장기 키는 서버 환경 변수 또는 배포용 비밀 관리 도구에 보관하세요. 커밋하거나 브라우저 코드로 보내지 마세요. 브라우저에 직접 연결이 필요하다면 백엔드에서 액세스 토큰 API를 통해 범위가 제한된 단기 토큰을 생성하세요.

Python TTS의 음성과 언어는 어떻게 선택하나요?

Playground에서 음성을 미리 들어보고 요청에 해당 ID를 전달하세요. 대본에 맞게 language 또는 locale 중 하나만 설정하세요. 자체 스크립트의 이름, 숫자, 약어를 테스트하세요. 모든 음성이 같은 억양을 지원한다고 가정하지 말고 요청 참조에서 언어 및 음성 설정을 확인하세요.

프로덕션에서 어떤 Sonic 모델 ID를 사용해야 하나요?

최신 Sonic 문서에서 모델을 선택하고 애플리케이션과 함께 테스트하세요. sonic-3.6 ID에는 안정적인 스냅샷 업데이트가 적용됩니다. 공개된 날짜 지정 스냅샷을 사용하면 새 릴리스를 평가하는 동안 모델 동작을 고정할 수 있습니다. 업그레이드 후 결과를 비교할 수 있도록 테스트와 함께 모델 ID를 기록하세요.

원시 PCM에 특별한 재생 설정이 필요한 이유는 무엇인가요?

원시 PCM에는 재생 방법을 설명하는 파일 헤더가 없습니다. 플레이어에는 요청에서 사용한 샘플링 레이트와 인코딩이 필요합니다. 설정이 다르면 잡음, 무음 또는 잘못된 속도의 음성이 발생할 수 있습니다. 먼저 WAV 출력으로 스트리밍 플레이어와 별개로 생성된 음성을 확인한 후 원시 오디오 재생 경로를 테스트하세요.

Python TTS를 프로덕션에서 사용하기 전에 무엇을 처리해야 하나요?

인증 실패, 요청 한도, 네트워크 오류, 시간 초과를 처리하세요. 애플리케이션에 맞게 SDK의 재시도와 시간 초과를 설정하세요. 재생 중단을 테스트하고 사용자의 방향이 바뀐 후 대기 중인 오디오가 다시 재생되지 않도록 하세요. 네트워크와 재생 버퍼를 포함해 텍스트가 준비된 시점부터 실제로 음성이 들리는 시점까지 측정하세요.

Sonic으로 계속 개발

음성을 비교하고 오디오 형식을 확인하며 통합을 계획하세요.

Sonic 살펴보기

자연스러운 전달을 위한 음성 모델과 제어 기능을 살펴보세요. Sonic이 음성 애플리케이션에 어떻게 들어가는지 확인하세요.

Sonic 살펴보기

언어별 음성 듣기

내 스크립트와 음성을 테스트하기 전에 목표 언어의 음성 예시를 들어보세요.

언어 둘러보기

API 요금제 비교

통합에 필요한 현재 사용량 한도와 요금제 기능을 확인하세요.

요금 보기

오늘 시작하세요

전문가와 상담하세요.

팀원과 연결해 Cartesia가 세계적 수준의 음성 경험을 만드는 데 어떻게 도움이 되는지 알아보세요.

영업팀 문의

개발을 시작하세요.

API로 모델을 사용하고 몇 분 만에 음성 에이전트를 프로덕션에 배포하세요.

Cartesia 사용해 보기