TTS API 문서 및 연동 가이드

작성자 SynthVoice Lab 편집팀 · 업데이트됨 2026-11-19

이 페이지는 대규모 ML 데이터셋 생성 및 텍스트 음성 변환 파이프라인을 위한 SynthVoice Lab API의 기술적 명세입니다. POST /v1/audio/speech를 포함한 주요 엔드포인트 구조, 인증 방식, 요청 매개변수 상세, 그리고 OpenAI SDK와의 호환 연동 방법을 안내합니다. RESTful API 구조를 기반으로 하므로 기존 인프라에 즉시 통합할 수 있습니다.

문서에는 curl 기반 요청 예제와 curl 요청 예제와 Python, Node.js SDK 사용 가이드가 포함되어 있어 엔지니어가 빠르게 프로토타입을 구축할 수 있도록 합니다. 속도 제한(Rate Limit), 오디오 포맷 옵션, 그리고 에러 처리 기준도 명확히 기술되어 있어 안정적인 배치 처리 환경에서 API를 효율적으로 운영할 수 있습니다.

TTS API 문서 및 연동 가이드

자주 묻는 질문

API 엔드포인트는 무엇인가요?

TTS API 엔드포인트는 POST https://api.s6app.info/v1/audio/speech입니다. JSON 형식의 본문으로 텍스트를 전송하면 오디오 파일을 수신합니다. 다른 엔드포인트로는 GET /v1/voices와 GET /v1/models이 있으며, 음성 목록, 언어, 포맷 및 가격 정보를 제공합니다.

API 키는 어디서 확인하나요?

API 키는 사이트의 /get-api-key/ 페이지에서 확인할 수 있습니다. 페이지에는 키, 잔액, 무료 체험 기간, 남은 문자 수, 사용량 및 준비된 curl 예제가 표시됩니다. 계정에 활성 키는 하나만 있으며, 필요 시 새 키를 발급할 수 있습니다.

curl 명령어는 어떻게 사용하나요?

/get-api-key/ 페이지에서 제공되는 준비된 curl 예제를 참조하세요. Authorization 헤더에 Bearer 토큰을 설정하고, JSON 본문에 model, input, voice 등의 필드를 포함하여 POST 요청을 전송하면 됩니다. OpenAI SDK와 호환되므로 base_url만 변경하면 동일하게 동작합니다.

오픈AI SDK와 호환되나요?

네, 공식 OpenAI SDK와 호환됩니다. base_url을 https://api.s6app.info/v1로 변경하고 사이트의 API 키를 사용하면 동일한 요청 형식으로 작동합니다. 이는 OpenAI의 speech 엔드포인트와 동일한 구조를 따릅니다.

base_url을 어떻게 변경하나요?

OpenAI SDK를 사용할 때 base_url 매개변수를 https://api.s6app.info/v1로 설정하세요. 그런 다음 Authorization 헤더에 Bearer 토큰을 포함하여 요청을 전송하면 됩니다. 이는 공식 OpenAI SDK가 인식하는 형식과 동일하므로 별도의 커스텀 클라이언트 없이 바로 사용 가능합니다.

지원하는 오디오 포맷은 무엇인가요?

지원하는 response_format은 mp3, wav, opus, flac, pcm입니다. request_body의 response_format 필드에 원하는 포맷을 지정하여 오디오 파일을 생성할 수 있습니다. 각 포맷은 특정 용도에 적합하며, 데이터셋 생성 시 파일 크기와 품질 요구 사항에 따라 선택하면 됩니다.

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

model 파라미터는 'tts-1' 또는 'tts-1-hd' 중 하나로 설정합니다. 두 모델은 동일한 엔진과 가격을 가지며, 선택에 따라 가격 차이는 없습니다. request_body의 model 필드에 원하는 값을 입력하여 오디오 생성 요청을 전송하면 됩니다.

rate limit은 어떻게 적용되나요?

키당 분당 60개의 요청이 제한됩니다. 첫 번째 충전 전에는 분당 10개의 요청만 허용됩니다. 이는 계정당 활성 키 하나에 적용되며, 초과 시 요청이 대기열에 들어갈 수 있습니다. 긴 텍스트의 경우 4096자 단위로 분할하여 처리하므로 실제 처리 속도에 주의하세요.

오류 시 응답 데이터는 어떻게 되나요?

합성 실패 시 요금이 전액 환불됩니다. 실패한 요청에 대한 데이터는 청구 목적으로 유지되지만, 생성된 오디오 파일은 반환되지 않습니다. 오류 발생 시 응답 데이터에는 실패 상태와 관련된 정보가 포함되며, 이는 계정 잔액에서 차감되지 않음을 의미합니다.

API 키를 재생성하면 이전 키는 어떻게 되나요?

새 API 키를 발급하면 이전 키는 즉시 무효화됩니다. 계정에 활성 키는 하나만 유지되며, 이전 키로 전송된 요청은 더 이상 처리되지 않습니다. 이는 보안 강화나 키 분실 시 즉각적인 대응을 위해 설계된 방식입니다.

특정 언어로 음성 생성은 어떻게 하나요?

language 필드에 ISO 코드를 지정하여 특정 언어로 음성을 생성합니다. 언어를 지정하지 않으면 스크립트에 따라 언어가 추측되지만, 비영어권 라틴 문자 텍스트의 경우 명시적으로 설정해야 합니다. 지원 언어는 23개이며, 지정된 언어로 음성이 생성됩니다.

오디오 파일 크기는 어떻게 결정되나요?

오디오 파일 크기는 입력 텍스트의 문자 수와 선택한 오디오 포맷에 따라 결정됩니다. 일반적으로 긴 텍스트의 경우 약 25자의 텍스트가 1초의 오디오를 생성합니다. 포맷에 따라 파일 크기가 다르므로, 데이터셋 생성 시 용량 계획을 세우세요.

비동기 처리가 가능한가요?

요청은 순차적으로 처리되며, 부하가 걸릴 경우 대기열에 들어갈 수 있습니다. 긴 텍스트의 경우 4096자 단위로 분할하여 처리하므로, 실제 처리 속도에 따라 비동기 처리를 설계해야 합니다.

스트리밍 응답이 제공되나요?

오디오 파일은 요청이 완료된 후 응답 본문으로 반환됩니다.

첫 번째 요청

curl

curl https://api.s6app.info/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.s6app.info/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.s6app.info/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 엔드포인트 개요

API 엔드포인트는 POST /v1/audio/speech로 텍스트를 오디오로 변환하고, GET /v1/voices와 GET /v1/models로 보이스 및 모델 정보를 조회합니다. OpenAI SDK 호환 구조로 기존 인프라에 즉시 통합할 수 있습니다.

POST /v1/audio/speech

POST /v1/audio/speech

JSON 본문으로 텍스트를 전송하면 오디오 파일이 반환됩니다. 입력 텍스트는 최대 4,096자까지 지원하며, 이를 초과할 경우 분할 생성 후 결합해야 합니다. 인증은 Bearer 토큰 방식을 사용합니다.

  • 엔드포인트: POST https://api.s6app.info/v1/audio/speech
  • 입력 텍스트 최대 길이: 4,096자

GET /v1/voices

GET /v1/voices

지원하는 보이스, 언어, 포맷 및 가격 정보를 조회합니다. 8가지 보이스 프리셋과 23개 언어의 매핑 정보를 확인하여 ML 데이터셋 생성 파이프라인을 구성할 수 있습니다.

  • 엔드포인트: GET https://api.s6app.info/v1/voices

GET /v1/models

현재 사용 가능한 모델 목록을 확인합니다. tts-1과 tts-1-hd 두 가지 엔진이 제공되며, 동일 엔진과 가격을 가집니다.

  • 엔드포인트: GET https://api.s6app.info/v1/models

인증 및 API 키

에 대한 소리 파동 일러스트레이션: 인증 및 API 키

모든 API 요청에는 Authorization: Bearer tts-... 형식의 API 키를 헤더에 포함해야 합니다. 이 키는 계정당 하나만 활성화되며, 새로운 키를 생성하면 이전 키는 즉시 무효화됩니다.

키 생성은 /get-api-key/ 페이지에서 진행됩니다. 생성된 키는 대시보드에서 확인 가능하며, 프로젝트에 직접 복사하여 사용할 수 있습니다.

Bearer 토큰 방식

API 호출 시 HTTP 헤더에 Authorization: Bearer <API_KEY>를 추가합니다. 이 방식은 OpenAI SDK 및 일반적인 HTTP 클라이언트와 호환됩니다.

API 키 생성 위치

계정 생성 후 /get-api-key/ 페이지에 접속하여 API 키를 발급받습니다. 이메일/비밀번호 또는 Google 로그인을 통해 접근할 수 있습니다.

키 재생성 절차

보안 강화 또는 키 누출 시 /get-api-key/ 페이지에서 새 키를 생성합니다. 새 키 생성 시 기존 키는 즉시 정지되므로 연동된 서비스의 키 업데이트가 필요합니다.

curl 요청 예제

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

API 키를 발급받았으면 curl 명령어를 통해 직접 음성 파일을 생성할 수 있습니다. 아래 예제는 OpenAI SDK와 동일한 JSON 구조를 따르므로, 기존 파이프라인에 쉽게 통합할 수 있습니다.

기본 텍스트 음성 변환 요청

가장 간단한 텍스트 음성 변환 요청 예시입니다. tts-1 모델을 사용하고 aria 보이스로 mp3 파일을 생성합니다.

  • curl -X POST https://api.s6app.info/v1/audio/speech \ -H "Authorization: Bearer tts-..." \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "aria", "response_format": "mp3"}'

속도 조절 포함 요청

속도 매개변수(speed)를 변경하여 음성 재생 속도를 조절할 수 있습니다. 0.25에서 4.0 사이의 값을 설정합니다.

  • curl -X POST https://api.s6app.info/v1/audio/speech \ -H "Authorization: Bearer tts-..." \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Fast narration", "voice": "nova", "response_format": "mp3", "speed": 2.0}'

특정 포맷 요청

반환받을 오디오 포맷을 명시하여 필요한 형식으로 다운로드합니다. opus 또는 wav 형식도 지원합니다.

  • curl -X POST https://api.s6app.info/v1/audio/speech \ -H "Authorization: Bearer tts-..." \ -H "Content-Type: application/json" \ -d '{"model": "tts-1-hd", "input": "High quality audio", "voice": "atlas", "response_format": "wav"}'

오픈AI SDK 연동

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

기존 OpenAI SDK를 수정 없이 바로 사용하려면 base_url을 https://api.s6app.info/v1로 변경하세요. 인증 헤더에 API 키를 설정하면 동일한 요청 구조로 음성 합성 API를 호출할 수 있습니다.

base_url 변경 방법

SDK 초기화 시 base_url 파라미터에 API 엔드포인트 주소를 지정합니다. 이는 기존 OpenAI 호환 클라이언트를 변경하지 않고 SynthVoice Lab의 TTS API에 연결할 수 있는 방법입니다.

  • Base URL: https://api.s6app.info/v1
  • Auth Header: Authorization: Bearer {YOUR_API_KEY}

Python SDK 사용 예제

OpenAI Python 라이브러리에서 base_url을 지정하여 음성 파일을 생성합니다. 생성된 오디오는 바이트 단위로 반환되며, 로컬 저장 또는 ML 데이터셋 파이프라인에 즉시 입력할 수 있습니다.

Node.js SDK 사용 예제

Node.js 환경에서도 동일한 방식으로 base_url을 설정하여 SDK를 사용합니다. 비동기 요청 처리를 통해 대용량 텍스트 처리 시 병렬로 음성 파일을 생성할 수 있습니다.

요청 매개변수

에 대한 소리 파동 일러스트레이션: 요청 매개변수

API 호출 시 model, voice, response_format 등 핵심 매개변수를 JSON body에 포함해야 합니다. 텍스트는 최대 4,096자까지 지원되며, 공백과 구두점을 포함한 문자 수가 과금 단위가 됩니다.

음성 생성 속도는 일반적으로 실시간에 가깝지만(초당 약 25자), 긴 텍스트는 분할 처리되므로 큐 대기 시간이 발생할 수 있습니다. language 파라미터를 명시하지 않으면 라틴 문자 기준 영어로 기본 설정됩니다.

model 선택 (tts-1, tts-1-hd)

tts-1과 tts-1-hd는 동일한 엔진을 사용하며 가격도 동일합니다. 두 모델은 동일한 엔진과 가격을 가지며, 호환성 테스트가 완료된 환경에서는 tts-1을 권장합니다.

최대 입력 길이는 4,096자이며, 이 한도를 초과하는 텍스트는 프론트엔드에서 분할하여 여러 요청으로 전송해야 합니다.

voice 프리셋 목록

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion

response_format 옵션

출력 오디오 형식을 mp3, wav, opus, flac, pcm 중 선택합니다. ML 데이터셋 생성 시에는 mp3 또는 wav가 일반적으로 적합하며, 대역폭 절감을 위해 opus를 사용할 수 있습니다.

생성된 오디오 파일에는 합성 음성임을 나타내는 무음의 워터마크가 포함됩니다. 각 요청당 하나의 오디오 파일이 반환됩니다.

요청 매개변수

에러 처리 및 상태 코드

에 대한 소리 파동 일러스트레이션: 에러 처리 및 상태 코드

API는 표준 HTTP 상태 코드를 사용하여 요청 결과를 반환합니다. 성공적인 처리는 200 OK를, 유효하지 않은 입력 또는 서버 오류는 400, 500번 코드로 구분됩니다.

실패한 요청의 경우 요금이 전액 환불됩니다. 이를 통해 파이프라인의 예외 처리 로직을 정확하게 구성할 수 있습니다.

일반 HTTP 에러 코드

400 Bad Request: 입력 텍스트가 4096자를 초과하거나 형식이 잘못되었습니다. 404 Not Found: 요청 엔드포인트가 존재하지 않습니다. 500 Internal Server Error: 서버 내부 처리 중 오류가 발생했습니다.

API 키 오류

401 Unauthorized: 제공된 API 키가 유효하지 않거나 만료되었습니다. Authorization 헤더에 올바른 Bearer 토큰이 포함되어 있는지 확인하세요. 키 재생성 시 이전 키는 즉시 무효화됩니다.

한도 초과 에러

429 Too Many Requests: 분당 60회 요청 한도를 초과했습니다. 초기 계정에는 분당 10회 제한이 적용됩니다. 재시도 전에 적절한 대기 시간을 확보해야 합니다.

과도한 요청은 큐에 대기되거나 즉시 반환될 수 있으며, 이는 실시간성이 중요한 파이프라인 설계 시 고려해야 할 요소입니다.

속도 제한 (Rate Limit)

에 대한 소리 파동 일러스트레이션: 속도 제한 (Rate Limit)

API 키당 분당 60회 요청 한도가 적용됩니다. 이는 대용량 데이터셋 생성 파이프라인에서 안정적으로 처리할 수 있는 선을 기준으로 설정되었습니다.

초기 상태에서는 분당 10회로 제한되며, 첫 번째 충전 이후 제한이 확대됩니다.

분당 60회 요청 한도

모든 API 키는 분당 60회 요청을 처리할 수 있습니다. 이는 긴 텍스트를 분할하여 처리할 때에도 일관된 처리를 지원합니다.

초기 제한 (분당 10회)

계정 생성 후 첫 충전 전까지 분당 10회의 요청이 허용됩니다. 이는 API 키가 활성화된 직후 과도한 사용으로 인한 리소스 소모를 방지합니다.

제한 초과 시 동작

한도 초과 시 요청은 큐에 배치되어 순차적으로 처리되거나, 일시적으로 429 Too Many Requests 응답을 반환합니다. 긴 텍스트 처리 시에도 큐를 통해 정상적으로 처리됩니다.

  • 요청은 한도 내에서 대기열에 의해 순차 처리됨
  • 초과 시 HTTP 429 상태 코드 반환

오디오 포맷 및 인코딩

에 대한 소리 파동 일러스트레이션: 오디오 포맷 및 인코딩

API 응답에서 response_format 필드를 통해 생성된 오디오의 인코딩 형식을 명시할 수 있습니다. 기본값은 MP3이며, ML 데이터셋 생성이나 낮은 대역폭 환경에서의 전송에 적합합니다.

원본 데이터의 무결성이 중요한 워크플로우에서는 WAV나 FLAC 포맷을 선택할 수 있습니다. 각 포맷은 서로 다른 용량과 품질 특성을 가지므로 사용 목적에 맞게 설정해야 합니다.

MP3 포맷

MP3는 가장 널리 사용되는 압축 오디오 형식입니다. API의 기본 응답 형식이며, 네트워크 대역폭을 효율적으로 사용하면서도 명확한 음질을 유지합니다. 대용량 텍스트를 처리하여 ML 학습용 오디오 파일을 생성할 때 적합한 선택입니다.

  • 가장 일반적인 호환성 제공
  • 네트워크 전송 효율성 우수

WAV 포맷

WAV는 압축되지 않은 원본 오디오 데이터입니다. 추가적인 인코딩/디코딩 오버헤드가 필요 없으므로, 실시간 처리나 정밀한 오디오 분석이 필요한 파이프라인에 적합합니다. 데이터셋의 원본 품질을 그대로 유지해야 할 때 사용합니다.

  • 무손실 원본 데이터 제공
  • 추가 디코딩 과정 불필요

FLAC, OPUS, PCM 지원

FLAC은 손실 없는 압축 형식으로, WAV보다 작은 파일 크기를 원하지만 무손질 품질을 필요로 할 때 유용합니다. OPUS는 낮은 지연 시간과 높은 압축률을 제공하며, PCM은 비압축 바이너리 데이터로 직접 처리가 필요한 경우에 사용됩니다.

  • FLAC: 손실 없는 고품질 압축
  • OPUS: 효율적인 스트리밍용
  • PCM: 바이너리 원시 데이터

8개 음성 듣기

아래의 각 샘플은 동일한 문장을 이 API로 생성한 것입니다.

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

23개 언어

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

출처 및 참고 자료

  1. Wikipedia
  2. TRON developer hub: TRC-20
  3. openai-python on GitHub
  4. W3C WAI: making audio and video accessible
  5. openai-node on GitHub
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. ISO 639 language codes
  8. Tether (USDT)
  9. FFmpeg documentation
  10. MDN: Web Speech API
  11. LibriTTS-R corpus (OpenSLR 141)
  12. curl documentation

이 사이트의 다른 콘텐츠