자주 묻는 질문
TTS API는 무엇인가요?
TourVoice는 텍스트를 음성 파일로 변환하는 클라우드 TTS API입니다. POST 엔드포인트로 JSON 요청을 보내면 mp3, wav 등 오디오 파일을 받습니다. OpenAI SDK와 호환되며, 8가지 음성 프리셋과 23개 언어를 지원합니다. 박물관 오디오 가이드 콘텐츠 생성을 위한 안정적인 엔드포인트를 제공합니다.
오디오 가이드에 TTS API를 사용할 수 있나요?
네, 본 API는 박물관 및 관광 산업의 제품 팀을 위해 설계되었습니다. 텍스트 입력 시 음성 파일을 반환하므로 오디오 가이드 콘텐츠 생성에 적합합니다. 최대 4096자까지 처리 가능하며, 다국어 지원을 통해 다양한 지역의 방문객을 위한 오디오 가이드 제작이 가능합니다.
지원되는 언어는 무엇인가요?
아랍어, 중국어, 덴마크어, 네덜란드어, 영어, 핀란드어, 프랑스어, 독일어, 그리스어, 히브리어, 힌디어, 이탈리아어, 일본어, 한국어, 말레이어, 노르웨이어, 폴란드어, 포르투갈어, 러시아어, 스페인어, 스와힐리어, 스웨덴어, 터키어 등 23개 언어를 지원합니다. 모든 음성은 모든 언어로 발화할 수 있습니다.
음성 preset은 무엇인가요?
8가지 음성 프리셋을 제공합니다. 여성: aria, nova, luna, sage. 남성: felix, milo, atlas, orion. 각 음성은 LibriTTS-R 및 LibriVox 데이터 기반으로 합니다. 오디오 가이드의 성격에 따라 내러레이터형, 안내형, 다큐멘터리형 등 적절한 음성을 선택하여 사용할 수 있습니다.
과금 모델은 어떻게 되나요?
100만 자당 $10의 종량제입니다. 실패한 요청은 무료이며 요금이 반환됩니다. Google 로그인 시 $0.50 무료 크레딧(7일 유효)이 제공됩니다. USDT(TRC-20)로 최소 $5부터 충전하며, 월 구독이나 추가 요금은 없습니다. 잔액은 만료되지 않습니다.
데이터는 어떻게 처리되나요?
입력 텍스트는 오디오 생성에만 사용되며 학습에 사용되지 않습니다. 생성된 오디오는 응답으로 반환되며 저장되지 않습니다. 청구용 요청 메타데이터(시간, 문자 수, 상태)만 보관됩니다. 오디오 가이드 생성 후 데이터는 외부로 유출되지 않습니다.
스트리밍이 지원되나요?
스트리밍, WebSocket, 실시간 부분 오디오는 지원되지 않습니다. 텍스트를 전송하면 전체 오디오 파일이 반환됩니다. 긴 텍스트의 경우 최대 4096자 단위로 분할된 후 오디오 파일이 반환되므로, 스트리밍 없이도 오디오 가이드 제작이 가능합니다.
SSML이 지원되나요?
SSML은 지원되지 않습니다. 속도 조절은 0.25~4.0 범위의 숫자 파라미터로 설정합니다. 발음 사전이나 사용자 정의 발음 사전도 제공되지 않습니다. 오디오 가이드의 정확한 발음 제어가 필요할 경우, 텍스트 자체의 표기를 조정하여 사용하는 것을 권장합니다.
커스텀 목소리를 사용할 수 있나요?
고객용 커스텀 음성 클로닝, 자체 음성 업로드, 음성 디자인 기능은 제공되지 않습니다. 8가지 고정 프리셋 중 하나를 선택하여 사용합니다. 오디오 가이드의 일관된 톤을 위해 특정 프리셋을 선택하여 전체 콘텐츠에 적용할 수 있습니다.
OpenAI SDK와 호환되나요?
네, OpenAI SDK와 호환됩니다. base_url을 https://api.playz28.com/v1로 변경하고 API 키를 설정하면 공식 SDK를 사용할 수 있습니다. 요청 형식은 OpenAI 스피치 엔드포인트와 동일하며, tts-1 또는 tts-1-hd 모델을 지원합니다.
API 키는 어떻게 발급받나요?
/get-api-key/ 페이지에서 Google 또는 이메일/비밀번호로 가입하여 API 키를 발급받습니다. 키는 계정당 하나이며, 언제든지 새 키를 발급할 수 있습니다. 기존 키는 새 키 발급 시 즉시 정지됩니다. 키는 대시보드에서 확인할 수 있습니다.
Rate Limit은 무엇인가요?
키당 분당 60회 요청 제한이 있습니다. 첫 충전 전에는 분당 10회로 제한됩니다. 요청은 순차적으로 처리되므로 부하 시 대기열에 서게 될 수 있습니다. 오디오 가이드 대량 생성 시에는 충분한 대기 시간을 고려하여 요청을 전송해야 합니다.
오류 시 환불이 되나요?
네, 합성 실패 시 요금이 전액 반환됩니다. 성공적으로 생성된 요청에만 요금이 부과됩니다. 오류 발생 시 API 응답을 통해 확인할 수 있으며, 해당 요청의 문자 수는 차감되지 않으므로 오디오 가이드 콘텐츠 생성 시 비용 효율적입니다.
오디오 파일의 포맷은 무엇인가요?
mp3, wav, opus, flac, pcm 형식을 지원합니다. response_format 파라미터를 통해 원하는 형식을 지정할 수 있습니다. 오디오 가이드 애플리케이션의 호환성에 따라 적절한 형식을 선택하여 오디오 파일을 생성하고 배포할 수 있습니다.
언어 감지 기능은 어떻게 작동하나요?
language 파라미터를 지정하지 않으면 스크립트 기반으로 언어가 감지됩니다. 라틴 문자 텍스트는 기본적으로 영어로 처리되므로, 영어 외 라틴 문자 텍스트는 반드시 language 파라미터를 설정해야 합니다. 모든 음성은 모든 지원 언어로 발화할 수 있습니다.
긴 텍스트는 어떻게 처리되나요?
텍스트는 최대 4096자 단위로 분할되어 처리됩니다. 각 분할된 텍스트에 대해 오디오 파일이 생성되며, 이 파일들은 결합됩니다. 긴 오디오 가이드 스크립트의 경우 여러 요청을 통해 전체 오디오 파일을 생성할 수 있습니다.
TTS API의 정의
TourVoice TTS API는 클라우드에서 텍스트 데이터를 오디오 파일로 변환하는 서비스입니다. 입력된 텍스트를 분석하여 자연스러운 음성으로 생성하며, 박물관 및 관광 산업의 오디오 가이드 콘텐츠 제작을 위해 설계되었습니다.
텍스트를 오디오로 변환
API는 지정된 모델을 사용하여 텍스트를 오디오 파일로 변환합니다. 최대 4096자의 텍스트를 한 번에 처리할 수 있으며, 긴 텍스트는 자동으로 분할되어 결합된 오디오를 생성합니다.
클라우드 기반 서비스
API 호출을 통한 자동화
REST API 엔드포인트를 통해 프로그래밍 방식으로 오디오 생성을 자동화할 수 있습니다. OpenAI SDK나 HTTP 요청을 사용하여 대규모 오디오 가이드 콘텐츠를 효율적으로 생성할 수 있습니다.
오디오 가이드 적용 사례
박물관 오디오 가이드 제작에서 텍스트 TTS API는 대본을 자동으로 음성 파일로 변환하여 효율성을 높입니다. 전시 해설, 안내 멘트, 역사적 설명 등 고정된 텍스트를 신속하게 오디오로 생성하여 콘텐츠 배포 기간을 단축합니다.
전시 해설 음성 생성
고정된 해설 텍스트를 API에 입력하면 tts-1 또는 tts-1-hd 모델을 통해 오디오 파일이 생성됩니다. 생성된 오디오는 안내 데스크나 모바일 앱에 직접 배포할 수 있습니다.
다국어 오디오 가이드
23개 언어를 지원하며, 언어 코드를 명시하면 정확한 발음으로 오디오를 생성합니다. 방문객의 국적에 따라 영어, 중국어, 프랑스어 등 다양한 언어의 가이드를 동일한 엔드포인트로 제공합니다.
콘텐츠 대량 생성
4096자 제한 내에서 긴 텍스트도 처리 가능하며, 여러 요청으로 분할해 오디오를 결합할 수 있습니다. 대량의 전시 데이터를 일괄 생성하여 운영 부담을 줄입니다.
기술적 사양
TourVoice는 OpenAI SDK와 호환되는 REST API 구조를 제공합니다. 기존 오픈소스 SDK를 활용하여 오디오 가이드 콘텐츠를 효율적으로 생성할 수 있습니다.
JSON 형식의 POST 요청을 통해 텍스트를 오디오 파일로 변환합니다. 인증 키를 기반으로 안정적으로 연동할 수 있습니다.
OpenAI SDK 호환
TourVoice의 API는 OpenAI의 speech 엔드포인트와 동일한 요청 형식을 따릅니다. 따라서 공식 OpenAI SDK를 사용하여 base_url만 수정하면 바로 연동할 수 있습니다. 별도의 전용 SDK나 모바일 라이브러리를 제공하지는 않습니다. 기존 Python 또는 JavaScript 환경에서 바로 사용할 수 있습니다.
- 공식 OpenAI SDK 호환
- base_url 변경으로 즉시 사용 가능
- 전용 SDK 미제공
REST API 구조
모든 기능은 RESTful API로 제공됩니다. POST 요청을 통해 텍스트를 전송하면 오디오 파일이 응답됩니다. 음성 목록이나 모델 정보는 GET /v1/voices 및 /v1/models 엔드포인트에서 확인할 수 있습니다. 인증은 Authorization 헤더에 Bearer 토큰을 추가하여 처리합니다.
JSON 요청 형식
요청 본문은 JSON 형식으로 구성됩니다. 필수 필로는 모델명(tts-1 또는 tts-1-hd), 입력 텍스트(input), 음성.voice, 응답 포맷(response_format)이 있습니다. 최대 4,096자까지의 텍스트를 한 번에 전송할 수 있으며, 속도(speed)와 언어(language) 옵션도 설정할 수 있습니다. 실패 시에는 요금이 부과되지 않습니다.
- POST https://api.playz28.com/v1/audio/speech
- JSON 본문 형식 지원
- 최대 4,096자 텍스트 한도
지원 언어
TourVoice API는 박물관 및 관광 콘텐츠 제작에 필요한 23개 언어를 지원합니다. 아랍어부터 시작해 한국어, 중국어, 스페인어까지 광범위한 언어군을 포괄하며, 다양한 지역 방문객을 위한 오디오 가이드 제작에 적합합니다.
이 목록은 베트남어, 태국어, 우크라이나어 등 일부 언어를 미지원합니다. 정확한 언어 범위는 공식 문서에서 확인할 수 있으며, API 호출 시 언어 코드를 명시하면 더 안정적인 결과를 얻을 수 있습니다.
23개 언어 지원
지원 언어는 아랍어, 중국어, 덴마크어, 네덜란드어, 영어, 핀란드어, 프랑스어, 독일어, 그리스어, 히브리어, 힌디어, 이탈리아어, 일본어, 한국어, 말레이어, 노르웨이어, 폴란드어, 포르투갈어, 러시아어, 스페인어, 스와힐리어, 스웨덴어, 터키어 등 총 23개 언어입니다. 어떤 음성 프리셋도 이 모든 언어를 지원합니다.
언어 감지 기능
language 파라미터를 지정하지 않으면 시스템이 텍스트의 문자를 분석하여 언어를 자동 감지합니다. 라틴 문자로 된 텍스트의 경우 기본값이 영어로 설정되므로, 영어가 아닌 라틴 문자 기반 언어(예: 스페인어, 프랑스어 등)의 오디오 가이드를 생성할 때는 반드시 언어 코드를 명시해야 합니다.
자동 감지는 정확도를 높이는 데 도움이 되지만, 명확한 지시가 필요한 전문적인 박물관 콘텐츠의 경우 수동 지정이 권장됩니다.
언어 코드 지정
ISO 언어 코드(예: ko, ja, es, fr)를 요청 본문의 language 필드에 명시적으로 전달할 수 있습니다. 이를 통해 의도한 언어로 정확한 발음과 억양을 보장할 수 있습니다.
지원되지 않는 언어(베트남어, 인도네시아어, 태국어, 우크라이나어, 루마니아어, 체코어, 벵골어 등)를 지정하여 호출할 경우 예상치 못한 결과가 생성될 수 있습니다.
음성 preset
TourVoice TTS API는 오디오 가이드 콘텐츠 제작을 위한 8가지 사전 설정된 음성(Voice Presets)을 제공합니다. 각 음성은 라이선스된 녹음(LibriTTS-R, CC BY 4.0)을 기반으로 하며, 일관된 품질을 제공합니다.
8가지 preset 음성
모든 음성은 라이선스된 기록(LibriTTS-R, CC BY 4.0)과 LibriVox 퍼블릭 도메인 오디오북을 기반으로 합니다. 생성된 모든 오디오 파일에는 합성 음성임을 나타내는 무음의 워터마크가 포함됩니다.
- 여성: aria, nova, luna, sage
- 남성: felix, milo, atlas, orion
남성 및 여성 목소리
4가지 여성 음성(aria, nova, luna, sage)과 4가지 남성 음성(felix, milo, atlas, orion)을 선택할 수 있습니다. 모든 음성은 23개 언어를 지원하므로, 특정 언어에 국한되지 않는 유연한 배치가 가능합니다.
용도별 음성 선택
음성 특성에 따라 적합한 용도를 선택하세요. aria는 따뜻하고 명확한 내레이터, nova는 밝고 역동적인 분위기, luna는 부드럽고 스토리텔링에 적합합니다. sage는 차분한 안내에, felix는 에너지 넘치는 프로모션에 사용됩니다.
milo은 친근한 대화형, atlas는 중립적인 뉴스, orion은 깊고 다큐멘터리 스타일의 콘텐츠에 최적화되어 있습니다. 박물관 전시 해설의 성격에 맞는 음성을 선택하여 일관된 청취 경험을 제공하세요.
과금 모델
TourVoice은 표준화된 문자 단위로 과금을 진행합니다. 100만 문자당 $10 ($0.01/1,000자)이며, 공백 및 구두점도 문자 수에 포함됩니다. 합성 실패 시 비용이 전액 환불됩니다.
Google 로그인 시 $0.50 체험 크레딧(약 5만 문자)이 제공되며 7일 후 만료됩니다. 이메일/비밀번호 계정 생성 시 체험 크레딧이 없습니다.
문자 기반 과금
사용량은 생성된 문자 수에 따라 실시간으로 차감됩니다. 100만 문자당 $10의 정산이 이루어지며, 공백과 특수문자도 포함됩니다.
오디오 생성 중 오류가 발생하여 요청이 실패한 경우, 해당 문자 수에 대한 비용은 전액 환불됩니다.
- 단가: $0.01 / 1,000자 (공백 및 구두점 포함)
- 실패 시 전액 환불
- 월 정액제 없음
무료 체험 크레딧
Google 계정으로 로그인하여 API 키를 생성할 경우, $0.50의 무료 체험 크레딧이 제공됩니다. 이는 약 5만 문자에 해당하는 양입니다.
체험 크레딧은 계정 생성 후 7일 동안 유효하며, 기간이 만료되면 자동으로 소멸됩니다.
- 크레딧 금액: $0.50
- 유효 기간: 7일
- 적용 조건: Google 로그인 계정
USDT 충전
충전 방식은 TRON 네트워크(TRC-20)의 USDT만 지원합니다. 최소 충전 금액은 $5이며, 트랜잭션 확인 후 몇 분 내에 잔액이 자동으로 반영됩니다.
카드, PayPal, 구독형 요금제 또는 VAT 포함 청구서가 존재하지 않습니다. 잔액은 유효 기간 없이 영구적으로 유지됩니다.
한 계정당 활성 API 키는 하나이며, 키 재생성 시 기존 키는 즉시 무효화됩니다.
- 결제 수단: USDT (TRC-20)
- 최소 충전 금액: $5
- 잔액 유효 기간: 없음

데이터 처리
TourVoice TTS API는 입력된 텍스트를 오디오 가이드 콘텐츠로 변환하는 데만 사용합니다. 생성된 오디오 파일은 응답을 통해 전송되며 서버에 영구 저장되지 않습니다. 요청 메타데이터(시간, 문자 수, 상태)는 청구 확인을 위해 보관됩니다.
입력 텍스트 사용 목적
사용자가 전송한 텍스트는 오디오 파일 생성 프로세스의 입력 원료로만 활용됩니다. 생성이 완료된 후 텍스트 자체는 다른 용도로 재사용되지 않습니다.
생성 오디오 비저장
API 호출을 통해 생성된 오디오 데이터는 응답 스트림으로 전송된 후 즉시 제거됩니다. 서버에는 오디오 파일이 영구적으로 보관되지 않으므로, 사용자가 원할 경우 매번 새로 요청하여 다운로드해야 합니다.
학습용 데이터 미사용
입력 텍스트와 생성된 오디오는 AI 모델 학습을 위해 사용되지 않습니다. 박물관 및 관광 산업의 고유한 콘텐츠가 학습 데이터베이스에 누적되어 공개되지 않으며, 데이터 프라이버시가 보장됩니다.
성능
TourVoice API는 긴 텍스트 처리 시 약 1초당 25자의 속도로 생성하며, 이는 실시간 내레이션에 근접한 수준입니다. 짧은 문장 생성은 수초이므로 배치 처리 시 대기열이 발생할 수 있습니다.
API 엔드포인트는 요청을 순차적으로 처리하므로, 동시 요청 시 지연이 발생할 수 있습니다.
실시간 근접 속도
긴 텍스트의 경우 초당 약 25자의 속도로 오디오를 생성합니다. 이는 실시간 해설에 근접한 속도로, 대량 콘텐츠 생성 시 효율적입니다. 짧은 문장은 생성에 수초이 걸립니다.
- 긴 텍스트: 약 25자/초 생성 속도
- 짧은 문장: 수초 단위 생성 시간
- 실시간성에 최적화된 처리 구조
긴 텍스트 처리
4096자 제한이 있는 텍스트는 자동으로 분할되어 생성된 오디오 파일들이 연결됩니다. 이를 통해 긴 해설 자료도 연속적인 오디오 가이드로 제공합니다.
각 분할 구간은 독립적으로 처리되므로, 전체 길이에 따른 지연은 최소화됩니다.
- 최대 4096자 per request
- 자동 분할 및 오디오 연결
- 연속적인 오디오 가이드 제공
Rate Limit
키당 분당 60회의 요청을 지원합니다. 첫 충전 전에는 분당 10회로 제한됩니다. 이는 대용량 데이터 처리 시 용량 계획을 수립하는 데 필요합니다.
요청은 순차적으로 처리되므로, 동시 요청 시 대기열이 발생할 수 있습니다.
과부하 시 지연이 발생할 수 있으며, 이는 실시간 처리와 무관합니다.
- 분당 60회 요청 (충전 후)
- 분당 10회 요청 (충전 전)
- 순차적 처리로 인한 대기열 발생 가능
포맷 및 형식
API는 mp3, wav, opus, flac, pcm 등 다양한 오디오 포맷을 지원합니다. 특정 환경에 맞는 형식을 선택하여 오디오 가이드를 구축할 수 있습니다.
다양한 오디오 포맷
mp3, wav, opus, flac, pcm 형식을 선택할 수 있습니다.
속도 조절
0.25부터 4.0까지 속도를 조절하여 콘텐츠의 흐름에 맞게 합성 속도를 조정할 수 있습니다.
워터마크 포함
생성된 모든 오디오 파일에는 합성 음성임을 나타내는 비가청 워터마크가 포함되어 있습니다.
호환성
TourVoice API는 OpenAI의 Speech 엔드포인트와 동일한 요청 형식을 따릅니다. base_url을 https://api.playz28.com/v1로 변경하고 API 키를 설정하면 기존 OpenAI SDK를 그대로 사용할 수 있습니다.
공식 SDK 없이도 표준 HTTP 요청으로 직접 호출할 수 있습니다. 별도의 전용 SDK나 모바일 SDK를 제공하지 않으며, REST API 구조를 기반으로 한 간단한 구현이 가능합니다.
OpenAI SDK 호환
요청 형식이 OpenAI의 speech 엔드포인트와 동일하여 기존 라이브러리와 호환됩니다. base_url만 수정하면 바로 사용할 수 있습니다.
기본 HTTP 요청
HTTP POST 요청을 통해 JSON body로 모델, 텍스트, 음성, 포맷 등을 지정할 수 있습니다. 복잡한 설정 없이 표준 방식의 API 호출로 오디오 파일을 받을 수 있습니다.
SDK 미제공
우리가 자체적으로 개발한 전용 SDK는 없습니다. OpenAI SDK나 plain HTTP를 활용하여 통합해야 합니다.
모바일 전용 SDK나 브라우저 확장 프로그램도 별도로 제공하지 않습니다. 웹 및 서버 환경에서 HTTP 요청 방식으로 통합하는 것이 기본 방식입니다.
제한 사항
TourVoice API는 실시간 스트리밍을 제공하지 않습니다. 텍스트를 전송하면 전체 오디오 파일이 완성된 후 응답으로 반환되며, 중간 청취는 불가능합니다. 이는 오디오 가이드의 안정적인 배포에 적합합니다.
스트리밍 없음
API 호출 시 오디오 파일의 전체 생성이 완료될 때까지 대기해야 합니다. 웹소켓이나 부분적 오디오 스트림을 지원하지 않으므로, 실시간 상호작용이 필요한 시나리오에는 적합하지 않습니다.
SSML 미지원
Speech Synthesis Markup Language(SSML)을 지원하지 않습니다. 억양, 정지 시간, 발음 변경 등을 위한 마크업 태그 입력이 불가능하며, 단순 텍스트 기반의 음성 생성만 가능합니다.
커스텀 목소리 없음
고객 전용 목소리 복제(Clone) 기능을 제공하지 않습니다. 미리 정의된 8가지preset 음성 중 하나를 선택하여 사용해야 하며, 고유한 목소리를 업로드하거나 커스터마이즈할 수 없습니다.
8개 음성 듣기
아래의 각 샘플은 동일한 문장을 이 API로 생성한 것입니다. 박물관 전시물의 설명 문구를 텍스트로 입력하면, 지정된 음성(Aria, Luna 등)으로 변환된 오디오 파일을 즉시 받아볼 수 있습니다.
23개 언어
모든 음성은 이 언어들을 구사합니다.
출처 및 참고 자료
- Wikipedia
- TRON developer hub: TRC-20
- MDN: Web Speech API
- IETF RFC 7845: Ogg Opus
- ISO 639 language codes
- LibriTTS-R paper (arXiv 2305.18802)
- W3C WAI: making audio and video accessible
- OpenAI API reference: create speech
- Python documentation
- LibriVox public-domain audiobooks
- openai-node on GitHub
- FFmpeg documentation
