# Docker로 직접 운영하는 음성 합성 API

업데이트 2026-10-22

내 서버의 음성 합성 API는 HTTP 요청을 보낼 수 있는 모든 프로그램을 위해 텍스트를 오디오로 바꿉니다. 웹사이트, 봇, 게임 백엔드, 어떤 언어의 스크립트든 상관없습니다. 텍스트는 내 컴퓨터를 벗어나지 않고, 글자 수에 따른 요금도 없습니다.

이 가이드는 오픈 모델 Supertonic 3 기반의 SuperClonica 엔진을 Docker에서 HTTP 서버로 실행하는 방법을 보여 줍니다. CPU나 NVIDIA GPU에서의 시작, 내장 음성과 커스텀 음성 요청, 실제 운영 준비까지 다룹니다. 이미지와 엔진은 저희 제품이므로 해당 부분에서는 그렇다고 밝힙니다.

## 음성 합성을 직접 운영하는 이유

클라우드 음성 API는 시작하기 쉽지만, 요청할 때마다 텍스트가 제공업체로 전송되고 글자 수만큼 비용이 듭니다. 직접 운영하는 API는 이를 내가 관리하는 서버로 바꿉니다.

- 개인정보 보호: 텍스트와 오디오가 내 하드웨어에 머뭅니다. 내부 문서, 메시지, 사용자 데이터에 중요합니다.
- 비용: 하드웨어 비용 외에는 음성 생성이 무료입니다. 긴 텍스트나 대량 작업도 비용을 늘리지 않습니다.
- 모든 클라이언트: 하나의 HTTP 엔드포인트로 Python, JavaScript, Go, PHP, C#, 셸 스크립트를 모두 지원합니다.
- 오프라인: 모델을 한 번 내려받으면 서버에 인터넷 연결이 필요 없습니다.

## 서버 시작하기

모든 CPU에서: docker run -d --name tts -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cpu. NVIDIA GPU에서는 NVIDIA Container Toolkit을 설치하고 docker run -d --name tts --gpus all -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cuda를 실행합니다. 이미지에 CUDA와 cuDNN이 들어 있어 호스트에는 드라이버만 있으면 됩니다.

처음 시작할 때 Supertonic 3 모델(약 385 MB)이 superclonica-models 볼륨에 다운로드되고, 이후에는 재사용됩니다. GET http://localhost:8000/health가 상태, 버전, 사용 중인 장치를 반환하면 준비된 것입니다. 이미지에 자체 헬스 체크가 있어 docker ps로 준비 상태를 확인할 수 있습니다.

## 요청 보내기

POST /synthesize는 JSON을 받아 16비트 모노 WAV 파일로 응답합니다: curl -X POST http://localhost:8000/synthesize -H "Content-Type: application/json" -d '{"text": "내 서버에서 보내는 인사입니다!", "voice": "F1", "lang": "ko"}' -o hello.wav. X-Sample-Rate와 X-Duration-Seconds 헤더가 오디오 정보를 알려 줍니다.

필드는 text, voice, lang, seed, normalize입니다. voice는 M1~M5와 F1~F5의 내장 음성 10가지 중 하나이거나 커스텀 음성이고, lang은 텍스트의 언어로 모델이 지원하는 31개 언어 중 하나입니다(중국어는 포함되지 않습니다). seed를 고정하면 같은 텍스트에서 같은 오디오가 나오고, normalize는 음량을 맞춥니다. GET /voices는 내장 음성과 언어 목록을 반환하고, /docs에서는 대화형 API 문서를 볼 수 있습니다.

## 커스텀 음성 사용하기

Supertonic 3 음성은 약 0.3 MB 크기의 JSON 파일입니다. 오디오 샘플이 있는 무료 음성은 GitHub의 superclonica/supertonic-voices 저장소에 있고, SuperClonica 카탈로그에는 170개가 넘는 음성이 있으며 모두 무료 온라인 데모를 제공합니다.

음성은 JSON 객체 그대로 요청의 voice 필드에 들어가므로 서버는 음성 파일을 보관하지 않습니다. 객체가 크기 때문에 요청은 파일로 만들어 curl -d @request.json으로 보내거나, 코드에서 Python의 json.load나 JavaScript의 JSON.parse로 음성을 읽어 텍스트와 함께 보내세요. 요청 본문은 최대 2 MB까지 가능합니다.

## 설정

서버는 환경 변수에서 설정을 읽습니다. docker run의 -e나 Compose 파일로 전달하세요.

- SUPERCLONICA_API_KEY: 설정하면 /synthesize와 /voices에 Authorization: Bearer와 키로 된 헤더가 필요합니다.
- SUPERCLONICA_LANES: 모델 사본 수, 1~8(기본값 1). 각 사본은 한 번에 요청 하나를 처리하며 별도의 메모리가 필요합니다.
- SUPERCLONICA_DEVICE: auto, cuda, cpu(기본값 auto: GPU가 있으면 GPU).
- SUPERCLONICA_THREADS: CPU 스레드 수(기본값은 물리 코어당 하나).
- SUPERCLONICA_MAX_TEXT: 텍스트의 최대 글자 수(기본값 5000).

## 실제 운영 전에

몇 가지 습관으로 직접 운영하는 음성 API를 빠르고 안전하게 유지할 수 있습니다.

- /models 볼륨을 유지해 재시작 때 모델을 다시 내려받지 않도록 하고, 컨테이너는 --restart unless-stopped로 실행하세요.
- 포트 8000을 그대로 인터넷에 공개하지 마세요. API 키를 설정하고 HTTPS 리버스 프록시 뒤에 두거나 사설 네트워크 안에서 사용하세요.
- 진행 상황 표시나 스트리밍이 필요하면 긴 텍스트를 직접 문단으로 나누세요. 엔진도 긴 텍스트를 최대 160자의 자연스러운 조각으로 읽습니다.
- UI 문구처럼 반복되는 텍스트의 오디오는 캐시하세요. 같은 텍스트, 음성, seed는 항상 같은 파일을 만듭니다.
- 내 하드웨어에서 측정하세요. 저희 테스트에서 짧은 문장은 RTX 5070 Ti에서 0.12초, Ryzen 7 5800X의 4스레드에서 0.43초가 걸렸습니다.

## 라이선스

SuperClonica 엔진과 이미지는 Apache License 2.0으로 배포됩니다. Supertonic 3 모델은 OpenRAIL-M으로 배포됩니다. 비상업 조항 대신 금지 용도 목록이 있는 로열티 없는 라이선스입니다. 동의 없이 다른 사람을 사칭하거나, 속이거나, 괴롭히는 데 음성을 쓰지 말고, 중요한 경우에는 기계가 생성한 오디오임을 밝히세요.

## 다른 가이드

- [내 컴퓨터에서 오프라인으로 텍스트를 음성으로 바꾸는 방법](https://superclonica.com/ko/guides/offline-text-to-speech)
- [목소리 복제: 녹음과 비슷한 목소리를 얻는 방법](https://superclonica.com/ko/guides/voice-cloning)
- [2026년 로컬에서 쓸 수 있는 무료 음성 합성 모델](https://superclonica.com/ko/guides/best-free-tts-models)
- [영상, 오디오북, 게임, 앱을 위한 음성 합성](https://superclonica.com/ko/guides/text-to-speech-for-videos)
- [Supertonic 3 목소리: 커스텀 목소리를 구하는 곳과 사용법](https://superclonica.com/ko/guides/supertonic-3-voices)
- [파이썬 텍스트 음성 변환: 오프라인, 무료, 자연스러운 목소리로](https://superclonica.com/ko/guides/python-text-to-speech)

## 음성 합성과 비교

- [내 컴퓨터에서 돌아가는 음성 합성(TTS)](https://superclonica.com/ko/text-to-speech)
- [Supertonic vs SuperClonica: 같은 모델, 더 빠르고 깨끗하게](https://superclonica.com/ko/compare/supertonic)
- [Fish Audio·Fish Speech와 SuperClonica 비교](https://superclonica.com/ko/compare/fish-audio)
- [OmniVoice와 SuperClonica: 언어 수인가, 속도인가](https://superclonica.com/ko/compare/omnivoice)
- [로컬 음성 합성, Qwen3-TTS와 SuperClonica 중 무엇을 쓸까](https://superclonica.com/ko/compare/qwen3-tts)
- [VoxCPM 2와 SuperClonica: 스튜디오 음질인가, CPU 속도인가](https://superclonica.com/ko/compare/voxcpm)
- [F5-TTS와 SuperClonica: 제로샷 복제인가, CPU에서 빠른 음성인가](https://superclonica.com/ko/compare/f5-tts)
- [오프라인으로 쓰는 ElevenLabs 대안](https://superclonica.com/ko/compare/elevenlabs)
- [Kokoro TTS와 SuperClonica: 로컬 음성 합성을 위한 작은 모델 두 가지](https://superclonica.com/ko/compare/kokoro)
- [Piper TTS와 SuperClonica: 소형 기기인가, 맞춤 목소리인가](https://superclonica.com/ko/compare/piper)
- [Coqui XTTS-v2와 SuperClonica: Coqui TTS 대안](https://superclonica.com/ko/compare/xtts)
- [Chatterbox TTS와 SuperClonica: 즉시 복제인가, 학습된 목소리 파일인가](https://superclonica.com/ko/compare/chatterbox)

## 자주 묻는 질문

### 이 API는 OpenAI 음성 엔드포인트와 호환되나요?

아니요. 자체적인 간단한 JSON 형식을 사용합니다. text, voice, lang과 몇 가지 옵션을 보내면 WAV 파일이 돌아옵니다. 코드나 프록시에 작은 어댑터를 두면 다른 형식을 변환할 수 있습니다.

### GPU가 필요한가요?

아니요. cpu 이미지는 일반 프로세서에서 동작하며 짧은 문장은 1초보다 훨씬 짧게 걸립니다. NVIDIA GPU와 cuda 이미지는 몇 배 더 빠르고 대량 작업에 적합합니다.

### 동시에 몇 개의 요청을 처리하나요?

요청은 모델 사본인 레인에서 처리되며, 레인이 하나면 차례를 기다립니다. SUPERCLONICA_LANES(최대 8)를 설정하면 여러 요청을 동시에 처리할 수 있습니다. CPU에서는 레인이 코어를 나눠 쓰고, GPU에서는 더 효율적으로 활용합니다.

### 인터넷 없이 작동하나요?

네, 처음 시작한 뒤에는 작동합니다. 모델은 /models 볼륨에 저장되고 이후 서버는 연결이 필요 없습니다. 인터넷은 이미지와 모델을 내려받을 때만 필요합니다.

- [API용 음성 보기](https://superclonica.com/ko/explore)
- [엔진의 다른 설치 방법](https://superclonica.com/ko/superclonica)

## 출처

- [SuperClonica Docker 이미지 (Docker Hub)](https://hub.docker.com/r/superclonica/superclonica)
- [NVIDIA Container Toolkit 설치 안내](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
- [SuperClonica 엔진 (PyPI)](https://pypi.org/project/superclonica-cpu/)
- [Supertonic 3 모델 카드 (Hugging Face)](https://huggingface.co/supertone-oss-archive/supertonic-3)
- [무료 Supertonic 3 음성 (GitHub)](https://github.com/superclonica/supertonic-voices)
- [SuperClonica](https://superclonica.com/ko/)
- [텍스트 읽기용 AI 목소리 카탈로그](https://superclonica.com/ko/explore)
- [Supertonic 3 커스텀 목소리 의뢰](https://superclonica.com/ko/requests)
- [작동 방식: 목소리, 로컬 음성 합성, 학습](https://superclonica.com/ko/guide)
- [더 빠른 Supertonic 3 엔진 설치](https://superclonica.com/ko/superclonica)
- [소개: 음성 합성을 사랑하는 팀](https://superclonica.com/ko/about)
- [연락처, 지원 및 목소리 신고](https://superclonica.com/ko/contacts)
- [개인정보 처리방침](https://superclonica.com/ko/privacy)
- [이용약관](https://superclonica.com/ko/terms)
- [음성 합성](https://superclonica.com/ko/text-to-speech)