Skip to main content
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.
코드 없이 터미널에서 바로 텍스트를 음성으로 변환하세요. Supertone CLI는 문자열·파일·표준 입력(stdin)으로 합성하고, 스피커로 실시간 스트리밍하고, 디렉터리 전체를 일괄 처리하고, 보이스·사용량·크레딧을 관리합니다. 소스: supertone-inc/supertone-cli.

​
빠른 시작

1

설치

pip install "supertone-cli[stream]"
Python 3.12+ 필요. [stream] 추가 옵션은 실시간 재생을 더합니다.
2

API 키 설정

export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
3

소리 듣기

supertone tts "터미널에서 내뱉는 첫 마디." \
  --voice 91992bbd4758bdcf9c9b01 -m sona_speech_1 --stream
소리가 들리면 준비 완료입니다. ✅
애플리케이션 코드에 통합하시나요? Python 또는 TypeScript SDK를 사용하세요. AI 에이전트용은 MCP를 참고하세요.

​
설치

pip install supertone-cli
Python 3.12+ 필요. [stream] 추가 옵션은 --stream을 통한 시스템 스피커 실시간 재생을 활성화합니다.

​
인증

export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."
기본값을 한 번 저장해 두면 매 호출마다 해당 플래그를 생략할 수 있습니다:
설정 키생략 시 사용처기본값
api_key항상—
default_voice--voice 미지정 시—
default_model--model 미지정 시sona_speech_2
default_lang--lang 미지정 시ko
supertone config set default_voice 20160a4c5ba38967330c84
supertone config set default_lang en

​
음성 합성

# 문자열로부터
supertone tts "터미널에서 안녕하세요." --voice VOICE_ID -o output.wav

# 파일로부터
supertone tts -i input.txt -v VOICE_ID -o output.wav

# 표준 입력(stdin)으로부터 — 파이프 친화적
echo "파이프로 전달된 텍스트." | supertone tts -v VOICE_ID -o output.wav

# 저장 대신 실시간 재생 ([stream] 추가 옵션 필요)
supertone tts "이건 실시간으로 재생됩니다." -v VOICE_ID -m sona_speech_1 --stream

# 포맷·보이스 설정 조정
supertone tts "더 느리고 더 낮게." -v VOICE_ID --output-format mp3 --speed 0.9 --pitch -2

# 폴더 전체 일괄 처리 — 입력마다 오디오 파일 하나
supertone tts -i scripts/ --outdir audio/ -v VOICE_ID

​
보이스 관리

supertone voices list                                  # Supertone 제공 프리셋 보이스
supertone voices list --type custom                    # 내가 복제한 보이스만
supertone voices search --lang en --gender female      # 프리셋 필터링
supertone voices get VOICE_ID                         # 상세 정보
supertone voices clone --name "My Voice" --sample sample.wav
supertone voices edit VOICE_ID --name "Renamed"
supertone voices delete VOICE_ID --yes               # --yes는 확인 절차 생략

​
길이 예측 및 사용량 추적

tts-predict는 크레딧을 소모하지 않고 길이와 크레딧 비용을 추정합니다 — 대량 일괄 처리 전에 유용합니다. 
supertone tts-predict "이건 얼마나 길까요?" -v VOICE_ID

supertone usage balance
supertone usage analytics --start 2026-04-01 --end 2026-04-30
supertone usage voices    --start 2026-04-01 --end 2026-04-30

​
레시피

.txt 파일을 한 디렉터리에 모아 한꺼번에 합성합니다:
supertone tts -i chapters/ --outdir narration/ -v VOICE_ID --output-format mp3
어떤 명령의 출력이든 실시간 음성으로 파이프합니다:
my-llm "오늘 헤드라인 요약해줘" | supertone tts -v VOICE_ID -m sona_speech_1 --stream
--format json은 모든 읽기 명령을 스크립트화할 수 있게 합니다:
supertone voices list --type custom --format json | jq '.[].name'
입력을 순회하며 예측 길이를 합산해 크레딧 소모 전에 가늠합니다:
for f in scripts/*.txt; do supertone tts-predict -i "$f" -v VOICE_ID; done

​
레퍼런스

sona_speech_1, sona_speech_2, sona_speech_2_flash, sona_speech_2t, supertonic_api_1, supertonic_api_3. 각 모델의 기능과 장단점은 모델을 참고하세요.
코드의미
0성공
1API 오류
2인증 오류
3입력 검증 오류
130중단됨 (Ctrl-C)

​
문제 해결

설치 디렉터리가 PATH에 없거나, 활성화되지 않은 가상환경에 설치된 경우입니다. 가상환경을 다시 활성화하거나, pip install --user supertone-cli로 재설치하고 사용자 스크립트 디렉터리를 PATH에 추가하세요.
API 키가 없거나 잘못되었습니다. echo $SUPERTONE_API_KEY로 확인하거나 supertone config set api_key your-api-key를 실행하세요. 키는 Developer Console에서 발급받습니다.
실시간 재생에는 스트리밍 추가 옵션(pip install "supertone-cli[stream]")과 sona_speech_1 모델이 필요합니다 — -m sona_speech_1을 전달하세요. 다른 모델은 “Streaming requires sona_speech_1” 오류를 내며, 그 경우 -o output.wav로 파일에 저장하세요.
잔액이 바닥나면 합성이 중단됩니다. supertone usage balance로 확인하고 Developer Console에서 충전하세요.

​
관련 문서

MCP

Model Context Protocol을 통해 AI 에이전트가 Supertone를 호출하도록 합니다.

Python SDK

애플리케이션 코드를 위한 동일한 API.