가이드

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

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

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

API용 음성 보기 엔진의 다른 설치 방법

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

클라우드 음성 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으로 배포됩니다. 비상업 조항 대신 금지 용도 목록이 있는 로열티 없는 라이선스입니다. 동의 없이 다른 사람을 사칭하거나, 속이거나, 괴롭히는 데 음성을 쓰지 말고, 중요한 경우에는 기계가 생성한 오디오임을 밝히세요.