TTS API 기술 문서 및 사용 가이드

작성자 뮤지오 편집팀 · 업데이트됨 2026-11-18

이 문서는 박물관 및 관광 산업의 제품 팀을 위해 설계된 TourVoice TTS API의 기술적 사용 가이드입니다. 오디오 가이드 콘텐츠의 대량 생성과 다국어 음성 합성을 위한 안정적인 API 엔드포인트 구조와 데이터 흐름을 설명합니다. API 키 발급부터 실제 요청 전송까지의 전 과정을 단계별로 안내합니다.

POST 엔드포인트 구조, OpenAI SDK 연동 방법, 그리고 8가지 음성 프리셋과 23개 언어 지원 옵션을 상세히 다룹니다. JSON 요청 파라미터 설정부터 응답 처리, 오류 코드 확인, 그리고 분당 60회의 요청 한도(Rate Limit) 조건까지 기술적 세부 사항을 명확히 제시합니다. 개발자가 API를 정확히 이해하고 효율적으로 연동할 수 있도록 구성된 문서입니다.

TTS API 기술 문서 및 사용 가이드

자주 묻는 질문

API 키는 어떻게 발급받나요?

/get-api-key/ 페이지에서 Google 또는 이메일/비밀번호로 계정을 생성하면 API 키가 발급됩니다. 계정은 사이트별로 독립적이며, 키는 하나의 계정당 하나만 활성화됩니다. 필요 시 새 키를 발급하면 이전 키는 즉시 무효화됩니다.

curl 예제는 어떻게 사용하나요?

GET /v1/voices 엔드포인트를 호출하여 사용 가능한 음성, 언어, 포맷 및 가격 정보를 확인하세요. POST /v1/audio/speech 엔드포인트로 JSON 요청을 보내면 오디오 파일이 반환됩니다. curl 예제는 /get-api-key/ 페이지에서 확인하여 사용할 수 있습니다.

OpenAI SDK와 어떻게 연동하나요?

공식 OpenAI SDK의 base_url을 https://api.playz28.com/v1로 변경하고 사이트의 API 키를 사용하면 연동할 수 있습니다. 요청 형식은 OpenAI 스피치 엔드포인트와 동일하므로 기존 SDK를 그대로 활용하여 텍스트를 오디오로 변환할 수 있습니다.

지원되는 response_format은 무엇인가요?

mp3, wav, opus, flac, pcm 형식을 지원합니다. response_format 필드에 원하는 형식을 지정하여 요청하면 해당 형식의 오디오 파일이 응답으로 반환됩니다. 기본값은 명시되지 않았으므로 필요 시 명시적으로 설정해야 합니다.

rate limit은 어떻게 되나요?

API 키당 분당 60회 요청이 허용됩니다. 첫 충전 전에는 분당 10회로 제한됩니다. 요청은 순차적으로 처리되므로 부하가 걸리면 대기열에 진입할 수 있으며, 이는 생성 시간에 영향을 줄 수 있습니다.

오류가 발생하면 어떻게 처리하나요?

합성 실패 시 요금이 전액 환불됩니다. 오류가 발생하면 해당 요청에 대한 요금이 청구되지 않으므로 안심하고 사용할 수 있습니다. 성공한 요청에만 요금이 부과됩니다.

voice 파라미터는 어떻게 설정하나요?

aria, nova, luna, sage, felix, milo, atlas, orion 중 하나를 선택합니다. GET /v1/voices 엔드포인트를 통해 사용 가능한 음성의 목록과 세부 정보를 확인할 수 있습니다. 각 음성은 고유한 특성을 가지고 있어 콘텐츠 성격에 맞게 선택해야 합니다.

speed 파라미터의 범위는 무엇인가요?

0.25에서 4.0 사이의 값을 설정할 수 있습니다. 기본 속도는 1.0이며, 이를 조정하여 음성 속도를 늦추거나 빠르게 할 수 있습니다. 오디오 가이드의 가청성에 맞게 최적의 속도를 실험해 보십시오.

언어 코드를 명시해야 하나요?

언어 코드는 선택 사항이지만, 비영어권 라틴 문자 텍스트의 경우 명시하는 것이 좋습니다. 언어를 지정하지 않으면 스크립트 기반으로 추측되나, 영어로 기본 설정될 수 있으므로 정확한 발음을 위해 language 파라미터를 설정하십시오.

긴 텍스트는 어떻게 처리되나요?

4096자까지의 텍스트를 요청할 수 있으며, 그 이상일 경우 클라이언트에서 청크로 나누어 요청해야 합니다. 각 청크의 오디오 파일을 생성한 후 클라이언트에서 연결하여 긴 오디오를 완성해야 합니다.

스트리밍이 지원되나요?

스트리밍, WebSocket, 실시간 부분 오디오는 지원되지 않습니다. 전체 오디오 파일이 생성된 후 응답으로 반환됩니다. 긴 텍스트의 경우 청크 단위로 요청하여 각 청크의 오디오 파일을 생성한 후 클라이언트에서 연결해야 합니다.

SSML이 지원되나요?

SSML은 지원되지 않습니다. 텍스트는 단순한 문자열로 전달되며, SSML 태그나 발음 사전, 감정 태그 등의 추가적인 제어 기능은 제공되지 않습니다.

오디오 파일의 길이 제한은 무엇인가요?

요청당 최대 4096자의 텍스트를 처리할 수 있습니다. 긴 텍스트는 여러 청크로 나누어 처리해야 합니다. 생성된 오디오의 길이는 텍스트 길이에 비례합니다. 긴 텍스트의 경우 대략 실시간 속도로 생성됩니다.

API 엔드포인트 URL은 무엇인가요?

API 엔드포인트 URL은 https://api.playz28.com/v1 입니다. POST /v1/audio/speech는 오디오 생성, GET /v1/voices는 음성 목록 조회, GET /v1/models는 모델 정보를 조회하는 데 사용됩니다.

첫 번째 요청

curl

curl https://api.playz28.com/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playz28.com/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.playz28.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
aria여성
nova여성
luna여성
sage여성
felix남성
milo남성
atlas남성
orion남성
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

시작하기: API 키 발급

에 대한 소리 파동 일러스트레이션: 시작하기: API 키 발급

Playz28.com에서 API 키를 발급받으려면 /get-api-key/ 페이지로 이동하세요. Google 계정으로 로그인하면 즉시 계정이 생성되고 $0.50의 무료 체험 크레딧이 제공됩니다. 이메일과 비밀번호로 생성된 계정은 초기 크레딧이 없습니다.

API 키 대시보드 확인

API 키 대시보드 확인

대시보드에서는 활성화된 API 키와 잔액, 사용량 정보가 표시됩니다. 계정당 활성 키는 하나만 존재하며, 새 키를 발급하면 이전 키는 즉시 비활성화됩니다.

  • API 키, 잔액, 사용량 정보 확인
  • 키 재생성 시 이전 키 즉시 정지

Bearer Token 사용

Bearer Token 사용

API 요청 시 HTTP 헤더에 Authorization: Bearer tts-... 형식으로 키를 포함해야 합니다. 이 키를 사용하여 오디오 생성 엔드포인트에 접근할 수 있습니다.

Google 로그인으로 계정 생성

Google 로그인을 통해 신속하게 계정을 생성하고 API 키를 발급받을 수 있습니다. 이 방식은 빠른 테스트와 초기 설정에 적합합니다.

첫 번째 요청 (curl 예제)

에 대한 소리 파동 일러스트레이션: 첫 번째 요청 (curl 예제)

API 키를 발급받은 후, POST 엔드포인트를 통해 텍스트를 오디오로 변환할 수 있습니다. 모든 요청은 JSON 형식의 본문(body)을 포함해야 하며, 인증은 Bearer 토큰을 사용하여 수행합니다.

첫 번째 요청은 기본 설정을 검증하는 단계입니다. 올바른 엔드포인트와 필드 구조를 이해하면 이후 대량 오디오 생성 워크플로우를 안정적으로 구축할 수 있습니다.

POST 엔드포인트 구조

오디오 생성 요청은 다음 엔드포인트로 전송됩니다.

POST https://api.playz28.com/v1/audio/speech

요청 헤더에는 Content-Type: application/json과 Authorization: Bearer YOUR_API_KEY가 필수로 포함되어야 합니다. 이 구조는 OpenAI의 스피치 엔드포인트와 호환됩니다.

JSON 본문 필드 설명

요청 본문은 다음 필드들을 포함해야 합니다. model은 tts-1 또는 tts-1-hd 중 하나입니다. input 필드에는 4096자를 초과하지 않는 텍스트를 입력합니다. voice는 8가지 프리셋 중 하나를 선택하며, response_format은 mp3, wav, opus, flac, pcm 중 하나입니다.

optional language 필드를 사용하여 ISO 언어 코드를 명시할 수 있습니다. 지정하지 않으면 스크립트에 따라 언어가 추론됩니다. speed는 0.25에서 4.0 사이에서 조절 가능합니다.

  • model: tts-1, tts-1-hd
  • input: 최대 4096자 텍스트
  • voice: aria, nova, luna, sage, felix, milo, atlas, orion
  • response_format: mp3, wav, opus, flac, pcm

응답 처리 방법

OpenAI SDK 연동

에 대한 소리 파동 일러스트레이션: OpenAI SDK 연동

이 TTS API는 OpenAI의 Speech 엔드포인트와 동일한 요청 형식을 사용하므로, 공식 OpenAI SDK를 그대로 활용할 수 있습니다. SDK 내에서 base_url을 https://api.playz28.com/v1로 변경하기만 하면 됩니다.

이러한 호환성을 통해 별도의 커스텀 클라이언트 개발 없이 기존 Python 또는 JavaScript 환경에서 즉시 오디오 생성 서비스를 연동할 수 있습니다.

base_url 변경 방법

OpenAI SDK를 사용할 때 base_url 파라미터를 API 엔드포인트 주소로 설정해야 합니다. 이 설정은 SDK가 요청을 올바른 서버로 라우팅하도록 합니다.

예를 들어 Python SDK에서는 OpenAI(base_url="https://api.playz28.com/v1", api_key="tts-...")와 같이 초기화하면 됩니다.

SDK 설정 예제

아래는 Python을 사용하여 음성 파일을 생성하는 최소한의 코드 예제입니다. model은 'tts-1' 또는 'tts-1-hd'를 사용합니다.

```python from openai import OpenAI client = OpenAI(base_url="https://api.playz28.com/v1", api_key="tts-your-api-key") response = client.audio.speech.create(model="tts-1", voice="nova", input="박물관 관람을 시작합니다.") response.stream_to_file("output.mp3") ```"], "bullets": [] }, {

요청 파라미터

에 대한 소리 파동 일러스트레이션: 요청 파라미터

TTS API는 텍스트를 오디오 파일로 변환하는 핵심 엔드포인트입니다. 요청 본문에는 모델, 음성, 포맷 등 필수 파라미터를 JSON 형식으로 전달해야 합니다.

각 파라미터는 생성되는 오디오의 품질, 어조, 파일 형식을 결정합니다. 올바른 값 선택은 오디오 가이드의 일관성을 유지하는 데 중요합니다.

model: tts-1 또는 tts-1-hd

모델 매개변수는 'tts-1' 또는 'tts-1-hd' 중 하나를 지정합니다. 두 모델은 동일한 엔진과 가격($10/100만 자)을 사용하지만, hd 모델은 동일한 엔진과 가격을 사용합니다.

모든 요청은 두 모델 중 하나를 명시해야 하며, 생략 시 기본값이 적용되지 않을 수 있으므로 명시적으로 설정하는 것을 권장합니다.

  • tts-1: 표준 품질, 실시간 생성에 적합
  • tts-1-hd: 고해상도 오디오, 사전 예약 콘텐츠에 적합
  • 두 모델 모두 동일 가격 및 엔진 사용

voice: 8가지 preset 중 선택

8가지 사전 설정된 음성 중 하나를 선택할 수 있습니다. aria, nova, luna, sage는 여성 보이스이며, felix, milo, atlas, orion은 남성 보이스입니다.

모든 음성은 지정된 23개 언어를 지원하며, 언어 코드를 명시하지 않으면 텍스트 스크립트에 따라 언어가 추론됩니다. 예외적으로 비영어권 라틴 문자 텍스트는 언어 코드를 명시해야 합니다.

각 음성은 고유한 톤을 가지며, 박물관 오디오 가이드의 컨텍스트에 맞게 신중하게 선택해야 합니다. 생성된 오디오에는 합성 음성임을 나타내는 무음의 워터마크가 포함됩니다.

  • aria: 따뜻하고 명확한 내레이터
  • nova: 밝고 활기찬 어조
  • luna: 부드럽고 스토리텔링
  • sage: 차분하고 교육적
  • felix: 역동적인 홍보
  • milo: 친근한 대화체

response_format: mp3, wav 등

응답 형식은 mp3, wav, opus, flac, pcm 중 하나를 선택할 수 있습니다. 각 형식은 오디오 파일의 압축 방식 및 품질 특성을 결정합니다.

대규모 오디오 가이드 배포의 경우 용량 효율성을 위해 opus 또는 mp3를 권장하며, 편집이 필요한 경우 wav 또는 flac을 사용할 수 있습니다.

pcm은 비압축 원시 데이터로, 특정 하드웨어 장치에 직접 로드해야 하는 경우에 적합합니다. 형식 선택은 전송 비용과 재생 호환성에 영향을 미칩니다.

  • mp3: 널리 지원되는 압축 형식
  • wav: 손실 없는 PCM 데이터
  • opus: 고효율 압축 형식
  • flac: 고품질 저장용
  • pcm: 비압축 원시 데이터

오류 처리

에 대한 소리 파동 일러스트레이션: 오류 처리

합성 요청이 실패한 경우 생성된 크레딧은 전액 환불됩니다. 이는 시스템 오류나 처리 실패 시에도 과금되지 않음을 보장합니다.

API 응답의 상태 코드와 에러 메시지를 확인하여 실패 원인을 파악하세요.

실패 시 환불 정책

TTS API는 요청 처리 중 오류가 발생했을 경우, 해당 요청에 대한 크레딧을 전액 환불합니다. 이는 실패한 합성 작업이 과금되지 않음을 의미합니다.

오류 코드 확인

JSON 응답 body의 'error' 필드에서 구체적인 실패 원인을 확인하십시오. 일반적으로 유효하지 않은 모델, 음성, 또는 형식 파라미터가 원인입니다.

  • 400 Bad Request: 파라미터 형식 오류
  • 429 Too Many Requests: Rate limit 초과
  • 500 Internal Server Error: 서버 처리 실패

재시도 로직

429 오류 발생 시 지수 백오프(exponential backoff) 방식을 권장합니다. 1분당 60회(초기 10회) 한도를 초과하지 않도록 큐를 관리하세요.

  • 429: 잠시 후 재시도
  • 500: 잠시 후 재시도
오류 처리

Rate Limit

에 대한 소리 파동 일러스트레이션: Rate Limit

TourVoice API는 분당 최대 60회의 요청을 지원합니다. 이는 대량의 오디오 가이드 생성 시에도 안정적인 서비스 제공을 위한 기본 한도입니다.

분당 60회 요청 한도

모든 API 키는 분당 60회의 요청으로 제한됩니다. 요청은 순차적으로 처리되므로, 부하가 걸리면 요청이 대기열에 진입할 수 있습니다.

초기 충전 전 분당 10회

초기 무료 크레딧($0.50) 상태에서는 분당 10회로 제한이 적용됩니다. 유료 충전(USDT TRC-20)이 완료되면 즉시 60회/분의 제한으로 상향 조정됩니다.

큐 처리 방식

요청은 순차적으로 처리됩니다. 요청이 급증할 경우, 대기열에 진입하여 처리 순서를 기다려야 할 수 있습니다. 이는 실시간 스트리밍이 아닌 방식의 특성입니다.

지원 포맷 및 속성

에 대한 소리 파동 일러스트레이션: 지원 포맷 및 속성

TourVoice API는 오디오 가이드 제작에 적합한 다양한 오디오 포맷을 지원합니다. mp3, wav, opus, flac, pcm 중 하나를 선택하여 응답 형식을 지정할 수 있습니다. 각 포맷은 용량과 품질 요구 사항에 따라 유연하게 선택 가능합니다.

오디오 포맷: mp3, wav, opus, flac, pcm

mp3와 opus는 네트워크 효율성이 높으며, wav와 flac은 무손실 품질이 필요합니다. pcm은 바이너리 데이터로 직접 처리해야 합니다. 생성된 오디오 파일은 서버에 저장되지 않고 응답으로 직접 반환됩니다.

  • mp3: 일반적인 오디오 가이드 배포용
  • wav/flac: 고해상도 오디오 가이드용
  • opus: 대역폭이 제한된 환경용
  • pcm: 특정 하드웨어 장치에 직접 로드해야 하는 경우에 적합

속도 조절: 0.25–4.0

속도 파라미터는 0.25에서 4.0까지 설정할 수 있습니다. 기본값은 1.0이며, 이 범위 내에서 음성 속도를 조정하여 오디오 가이드의 청취 편의성을 최적화할 수 있습니다.

언어 코드 지정

ISO 언어 코드를 명시적으로 지정하면 언어 감지 오류를 방지할 수 있습니다. 23개 언어를 지원하며, 언어를 지정하지 않으면 라틴 문자는 영어로, 그 외 문자는 자동으로 감지됩니다. 예를 들어, 프랑스어 텍스트에 'language': 'fr'을 설정해야 합니다.

긴 텍스트 처리

에 대한 소리 파동 일러스트레이션: 긴 텍스트 처리

API는 최대 4096자까지의 텍스트를 한 번의 요청으로 처리합니다. 이를 초과하는 오디오 가이드 콘텐츠는 여러 작은 단위로 나누어 생성해야 합니다.

각 요청은 독립적으로 처리되므로, 긴 텍스트의 경우 여러 API 호출을 통해 오디오 파일을 생성한 후 서버 측 또는 클라이언트에서 연결해야 합니다.

4096자 제한

단일 요청에 포함할 수 있는 텍스트의 최대 길이는 4096자입니다. 공백과 구두점도 문자 수에 포함되므로, 전체 문자 수를 계산한 후 요청을 전송해야 합니다. 이 제한은 서버 리소스 관리 및 일관된 오디오 품질 유지를 위해 적용됩니다.

자동 분할 및 결합

API는 요청 내 텍스트를 자동으로 분할하거나 오디오 파일을 결합하지 않습니다. 개발자가 4096자를 초과하는 텍스트를 여러 요청으로 나누어 전송해야 하며, 생성된 오디오 파일을 순서대로 연결하여 최종 오디오 가이드를 완성합니다. 이를 위해 SDK의 반복문이나 별도의 스크립트를 사용할 수 있습니다.

스트리밍 아님

현재 API는 스트리밍 또는 WebSocket을 통한 실시간 부분 오디오 제공을 지원하지 않습니다. 오디오 파일의 생성이 완료될 때까지 응답을 기다려야 하며, 생성 중에는 부분적인 오디오 데이터를 받을 수 없습니다. 이는 실시간 상호작용이 필요한 애플리케이션보다는 사전 제작된 오디오 가이드 생성에 적합합니다.

8개 음성 듣기

아래의 각 샘플은 동일한 문장을 이 API로 생성한 것입니다. 박물관 전시물의 설명 문구를 텍스트로 입력하면, 지정된 음성(Aria, Luna 등)으로 변환된 오디오 파일을 즉시 받아볼 수 있습니다.

음성 아바타 aria
aria여성
음성 아바타 nova
nova여성
음성 아바타 luna
luna여성
음성 아바타 sage
sage여성
음성 아바타 felix
felix남성
음성 아바타 milo
milo남성
음성 아바타 atlas
atlas남성
음성 아바타 orion
orion남성

23개 언어

모든 음성은 이 언어들을 구사합니다.

출처 및 참고 자료

  1. Wikipedia
  2. OpenAI API reference: create speech
  3. IETF RFC 7845: Ogg Opus
  4. LibriVox public-domain audiobooks
  5. Python documentation
  6. curl documentation
  7. MDN: Web Speech API
  8. LibriTTS-R paper (arXiv 2305.18802)
  9. TRON developer hub: TRC-20
  10. Node.js documentation
  11. Creative Commons Attribution 4.0
  12. LibriTTS-R corpus (OpenSLR 141)

이 사이트의 다른 콘텐츠