자주 묻는 질문
API 키는 어떻게 발급받나요?
/get-api-key/ 페이지에서 Google 또는 이메일로 가입하세요. 생성된 계정은 사이트별로 독립적입니다. 대시보드에서 API 키를 확인하고, 필요 시 새로운 키를 발급할 수 있습니다. 새 키 발급 시 이전 키는 즉시 정지됩니다. 키는 Authorization 헤더에 Bearer 토큰 형태로 사용합니다.
오픈AI SDK를 그대로 사용할 수 있나요?
네, 요청 구조가 동일하므로 공식 OpenAI SDK를 그대로 사용할 수 있습니다. base_url만 https://api.8768.top/v1로 변경하면 됩니다. HTTP 라이브러리나 오픈AI SDK를 통해 POST /v1/audio/speech 엔드포인트를 호출하여 오디오 파일을 생성할 수 있습니다.
base_url은 어떻게 설정하나요?
SDK 설정 시 base_url을 https://api.8768.top/v1로 지정하세요. API 키는 Authorization 헤더에 Bearer 토큰으로 추가합니다. 이 설정으로 오픈AI 호환 엔드포인트에 접근할 수 있으며, voices 목록 조회나 모델 정보 확인도 동일한 base_url에서 가능합니다.
tts-1과 tts-1-hd의 차이는 무엇인가요?
두 모델은 엔진과 가격이 동일합니다. tts-1과 tts-1-hd 모두 동일한 엔진을 사용하며, 가격 차이는 없습니다. 요청 시 model 필드에 두 값 중 하나를 지정하면 되며, 기능적 차이 없이 동일한 품질의 오디오 파일을 생성합니다.
에러 코드는 어떻게 처리하나요?
API는 표준 HTTP 상태 코드를 반환합니다. 응답 본문에 에러 세부 정보가 포함됩니다. 에러가 발생하면 해당 요청에 대한 과금은 발생하지 않으며, 충전 금액은 전액 환불됩니다. 클라이언트 측에서 HTTP 상태 코드와 응답 바디를 확인하여 적절히 처리하세요.
rate limit은 어떻게 되나요?
키당 분당 60회 요청이 허용됩니다. 첫 충전 전에는 분당 10회로 제한됩니다. 요청은 순차적으로 처리되므로 부하 시 대기열에 진입할 수 있습니다. 긴 텍스트는 4096자 단위로 나누어 처리합니다.
language를 설정하지 않으면 어떻게 되나요?
언어를 명시하지 않으면 스크립트 기반으로 언어가 자동 감지됩니다. 라틴 문자 텍스트는 기본적으로 영어로 간주됩니다. 비영어권 라틴 문자 텍스트의 경우 정확한 발음을 위해 language 필드에 ISO 코드를 명시적으로 설정해야 합니다. 지원 언어 목록은 /v1/voices 엔드포인트에서 확인하세요.
오디오 파일은 어떻게 받나요?
POST 요청에 대한 응답 본문에서 오디오 파일이 직접 반환됩니다. response_format 파라미터에 mp3, wav, opus, flac, pcm 중 하나를 선택하세요. 파일은 응답 본문으로 제공되며, 별도의 저장소나 URL이 없습니다. 생성된 오디오는 응답 후 저장되지 않습니다.
JSON 응답 구조는 무엇인가요?
성공 시 응답 본문은 요청한 형식(mp3, wav 등)의 바이너리 데이터입니다. JSON 메타데이터는 헤더나 별도 필드에 포함되지 않습니다. 에러 발생 시 JSON 형식으로 에러 코드와 메시지를 반환합니다.voices 목록 조회 등 다른 엔드포인트는 JSON 구조를 따릅니다.
curl 예제는 어디서 확인하나요?
/get-api-key/ 페이지 대시보드에서 준비된 curl 예제를 확인할 수 있습니다. 페이지에는 API 키, 잔액, 사용량 정보가 함께 표시됩니다. 이 예제를 복사하여 base_url과 API 키만 수정하면 바로 테스트할 수 있습니다. 문서 페이지의 별도 예제 블록은 없습니다.
Python SDK 설정 예제는 있나요?
공식 Python SDK 예제는 별도 제공되지 않습니다. OpenAI Python SDK를 사용하되 base_url을 https://api.8768.top/v1로 변경하면 됩니다. 표준 HTTP 라이브러리나 오픈AI SDK의 구조를 참고하여 POST /v1/audio/speech 엔드포인트를 호출하세요. 자체 SDK는 없습니다.
JavaScript SDK 설정 예제는 있나요?
공식 JavaScript SDK 예제는 별도 제공되지 않습니다. OpenAI JavaScript SDK를 사용하되 base_url을 https://api.8768.top/v1로 변경하세요. fetch API나 Axios 같은 HTTP 라이브러리를 사용해도 무방합니다. 요청 구조는 오픈AI와 동일하므로 해당 문서를 참고하세요.
에러 시 충전이 되나요?
합성 실패 시 과금이 발생하지 않습니다. 에러가 발생하면 충전 금액이 전액 환불됩니다. 성공한 요청에만 문자 수에 따라 요금이 부과됩니다. 실패한 요청은 사용량 통계에서 제외되며, 계정 잔액에 영향을 미치지 않습니다.
API 키는 몇 개까지 만들 수 있나요?
계정당 활성 키는 하나만 유지됩니다. 새 키를 발급하면 이전 키는 즉시 정지됩니다. 따라서 동시에 활성화된 키는 항상 1개입니다. 필요 시 언제든지 새 키를 발급할 수 있으며, 이전 키는 즉시 사용 불가 상태가 됩니다.
첫 번째 요청
curl
curl https://api.8768.top/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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.8768.top/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.8768.top/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 | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
API 키 발급 및 인증
API 키 발급 및 인증 — GET /v1/voices 엔드포인트; Bearer 토큰 구조; 키 발급 및 갱신
API 키 발급 및 인증 — GET /v1/voices 엔드포인트; Bearer 토큰 구조; 키 발급 및 갱신
GET /v1/voices 엔드포인트
/v1/voices 엔드포인트를 통해 사용 가능한 음성 목록, 지원 언어, 포맷 및 가격 정보를 확인할 수 있습니다. 이 엔드포인트는 API 키 없이도 접근할 수 있어 연동 전에 설정을 미리 검토하는 데 유용합니다.
Bearer 토큰 구조
모든 API 요청에는 Authorization: Bearer tts-... 헤더가 필요합니다. 이 토큰은 계정당 하나만 유효하며, 새 키를 발급하면 이전 키는 즉시 무효화됩니다.
키 발급 및 갱신
/get-api-key/ 페이지에서 Google 또는 이메일로 가입하여 API 키를 발급받으세요. 필요시 언제든 새 키를 생성할 수 있으며, 이전 키는 즉시 정지됩니다.
이 키는 POST https://api.8768.top/v1/audio/speech 요청 인증에 사용되며, OpenAI SDK 호환성을 위해 base_url만 변경하면 바로 연동할 수 있습니다.
- Google 또는 이메일 가입으로 즉시 키 발급
- 새 키 생성 시 기존 키 즉시 정지
- API 키는 계정당 하나만 유효
첫 번째 요청 (curl 예제)
API 키를 발급했으면 이제 오디오 생성의 핵심인 POST 요청을 확인해 보세요. 이 엔드포인트는 텍스트를 받아 실제 오디오 파일로 변환하는 역할을 하며, 오픈AI와 동일한 JSON 구조를 사용해 연동 부담을 줄였습니다. 복잡한 설정 없이 바로 테스트할 수 있는 curl 예제를 준비했습니다.
POST 엔드포인트 구조
오디오 생성 요청은 https://api.8768.top/v1/audio/speech 엔드포인트로 전송합니다. HTTP 메서드는 반드시 POST를 사용하며, 요청 본문에는 생성할 텍스트와 음성 속성 정보가 포함됩니다. 이 구조는 오픈AI의 스피치 엔드포인트와 호환되므로 기존 SDK를 그대로 활용할 수 있습니다.
JSON 본문 필드 설명
요청 본문에는 model, input, voice 필드가 필수입니다. model은 "tts-1" 또는 "tts-1-hd" 중 하나를 선택하며 엔진과 가격은 동일합니다. input 필드에는 생성할 텍스트를 최대 4096자까지 입력합니다. voice 필드에는 aria, nova 등 8가지 프리셋 중 하나를 지정합니다.
선택 사항으로 response_format(mp3, wav 등), speed(0.25-4.0), language(ISO 코드)를 설정할 수 있습니다. 언어를 명시하지 않으면 입력된 스크립트에 따라 자동으로 감지되지만, 비영어권 라틴 문자의 경우 정확한 인식을 위해 language 필드를 설정하는 것이 좋습니다.
응답 형식
성공적인 요청 시 응답 본문에는 오디오 데이터가 직접 포함됩니다. 이는 mp3, wav, opus, flac, pcm 형식 중 선택한 response_format에 따라 반환됩니다. 파일은 즉시 클라이언트 측에서 저장하거나 재생할 수 있도록 설계되었습니다.
요청이 실패할 경우 JSON 오류 메시지가 반환되며, 이 경우 해당 요청에 대한 요금은 청구되지 않습니다. 실패 시 반환되는 에러 코드와 처리 방법은 하단 '에러 처리' 섹션에서 자세히 설명합니다.
OpenAI SDK 연동
기존 OpenAI SDK를 그대로 사용하면서 base_url만 변경하면 연동이 완료됩니다. 인증 키는 기존 방식과 동일하게 Authorization: Bearer 헤더에 담아 전송합니다.
이 방식은 별도의 복잡한 설정 없이도 API 호환성을 유지하며, 에이전시 개발자가 익숙한 도구로 빠르게 오디오 파일을 생성할 수 있게 합니다.
base_url 변경 방법
SDK 초기화 시 base_url을 https://api.8768.top/v1로 설정합니다. 이 변경만으로 모든 요청이 Vokality 엔드포인트로 전달됩니다.
기존 OpenAI SDK의 코드 구조를 유지하면서도, 실제 처리는 Vokality의 TTS 엔진을 통해 이루어집니다. 인증 키는 각 계정에서 발급된 전용 토큰을 사용합니다.
python SDK 설정
Python OpenAI SDK를 설치한 후, BaseOpenAIClient를 상속받아 api_key와 base_url을 지정합니다.
이후 client.audio.speech.create() 메서드를 호출하여 텍스트를 음성으로 변환할 수 있습니다. 설정 과정은 기존 OpenAI 사용 방식과 동일합니다.
javascript SDK 설정
JavaScript 환경에서도 기존 OpenAI JS SDK의 baseUrl 옵션을 수정하여 연동합니다.
이렇게 하면 프론트엔드 또는 Node.js 백엔드에서 손쉽게 TTS 기능을 구현할 수 있습니다. 응답은 오디오 파일 데이터로 직접 반환됩니다.
요청 파라미터详解
API 호출 시 필수로 지정해야 하는 요청 파라미터들을 정리합니다. 모델과 음성, 포맷 설정이 생성되는 오디오의 품질과 파일 크기를 결정합니다.
각 파라미터의 유효한 값과 에이전시 워크플로우에서 자주 고려해야 할 기술적 제약 사항을 명확히 설명합니다.
s30s
model 선택 (tts-1 vs tts-1-hd)
모델 파라미터는 'tts-1'과 'tts-1-hd' 두 가지 중 선택할 수 있습니다. 두 모델은 동일한 엔진과 가격($10/백만 자)을 공유하므로 기능상 차이가 없습니다.
호환성이나 특정 품질 선호도가 아니라 단순히 코드의 가독성을 위해 선택하면 됩니다. 둘 중 하나만 지정하면 됩니다.
- 두 모델 모두 동일한 엔진과 가격대를 가집니다.
- 호환성 테스트나 가독성을 위해 임의로 선택 가능
voice presets 목록
8가지 미리 설정된 음성 중 하나를 선택합니다. 여성 보이스로는 aria, nova, luna, sage가 있으며 남성 보이스로는 felix, milo, atlas, orion이 있습니다.
각 목소리는 교육 콘텐츠나 HR 자료의 분위기에 맞춰 선별됩니다. 예를 들어 뉴스 형식에는 atlas, 대화체에는 milo가 적합합니다.
모든 목소리는 지정된 23개 언어를 모두 지원하므로, 언어에 따라 목소리를 변경할 필요가 없습니다.
- aria: 따뜻하고 명확한 내레이터
- nova: 밝고 경쾌한 톤
- luna: 부드럽고 스토리텔링 중심
- sage: 차분한 교육용
- felix: 에너지 넘치는 프로모션
- milo: 친근한 대화체
- atlas: 중립적인 뉴스
- orion: 깊고 다큐멘터리 톤
response_format 옵션
생성된 오디오 파일의 형식을 mp3, wav, opus, flac, pcm 중 하나로 지정합니다. 저장 용량과 품질 요구사항에 따라 결정합니다.
대규모 데이터 저장 시에는 mp3나 opus가 적합하며, 추가 편집이 필요할 경우 wav나 flac을 사용할 수 있습니다. pcm은 비압축 원본 데이터용입니다.
기본값은 보통 mp3이며, 필요 시 다른 형식으로 변경하여 요청할 수 있습니다.
- mp3: 가벼운 파일 크기, 넓은 호환성
- wav: 비압축 고품질, 편집 용이
- opus: 고효율 압축
- flac: 손실 없는 고품질
- pcm: 비압축 원본 데이터
속도 및 언어 설정
API는 0.25배에서 4.0배까지 속도를 지원합니다. 교육 콘텐츠나 HR 교육 자료의 길이에 맞춰 재생 속도를 조절할 수 있습니다.
speed 범위 (0.25-4.0)
속도는 0.25부터 4.0까지 0.25 단위 조절이 가능합니다. 긴 교육 스크립트는 2배 속도로, 복잡한 HR 가이드는 0.75배로 조절해 가청성을 높여보세요.
language ISO 코드 설정
지원 언어 목록에 있는 23개 언어의 ISO 코드를 명시적으로 설정하세요. 아라비아어, 중국어, 한국어 등 특정 언어 콘텐츠 제작 시 언어 감지 오류를 방지합니다.
지원하지 않는 언어(베트남어, 태국어 등)는 명시하지 않으면 기본값이 적용될 수 있으므로 주의하세요.
- 지원 언어: 아라비아어, 중국어, 덴마크어, 네덜란드어, 영어, 핀란드어, 프랑스어, 독일어, 그리스어, 히브리어, 힌디어, 이탈리아어, 일본어, 한국어, 말레이어, 노르웨이어, 폴란드어, 포르투갈어, 러시아어, 스페인어, 스와힐리어, 스웨덴어, 터키어
언어 감지 로직
language 필드를 비워두면 시스템이 텍스트의 문자를 분석해 언어를 추측합니다. 라틴 문자 기반 비영어권 텍스트의 경우 영어로 오인될 수 있으므로, 반드시 language 파라미터를 명시하세요.
예를 들어, 네덜란드어 교육 자료라면 language: nl을 설정해 정확한 발음을 보장해야 합니다.

에러 처리 및 코드
API 요청 중 발생할 수 있는 일반적인 오류와 속도 제한 문제를 해결하는 방법을 안내합니다. 실패한 요청은 요금이 부과되지 않습니다.
개발 시 에러 코드를 적절히 처리하여 서비스의 안정성을 높이고, 요청 제한에 따른 대기 시간을 효율적으로 관리하세요.
일반 에러 코드
잘못된 API 키나 유효하지 않은 모델 이름 사용 시 401 또는 400 에러가 발생합니다. 텍스트가 4096자를 초과하거나 지원되지 않는 형식일 경우에도 오류가 반환되며, 이 경우 생성된 오디오는 없으므로 요금이 청구되지 않습니다.
rate limit 에러
1분에 60회 요청을 초과하면 429 에러가 발생합니다. 첫 충전 전에는 1분당 10회 제한이 적용됩니다. 서버가 바쁠 경우 요청이 큐에 쌓일 수 있으니, 적절한 재시도 로직을 구현하는 것이 좋습니다.
검토 예제
에러 응답 본문에는 상세한 설명이 포함되므로 이를 로그로 기록하여 원인을 빠르게 파악하세요. 실패 시 요금이 반환되므로, 비즈니스 로직에서 오류 상태 코드를 구분하여 처리하는 것이 중요합니다.
속도 제한 (Rate Limits)
API 키당 분당 60회 요청이 허용됩니다. 한 번의 요청이 완료될 때까지 순차적으로 처리되므로, 대용량 교육 콘텐츠 생성 시 대기열이 발생할 수 있습니다. 짧은 문장은 몇 초, 긴 텍스트는 실시간 속도에 가깝게 생성되지만 시스템 부하 시 지연이 생길 수 있습니다.
1분당 60회 요청
계정당 분당 최대 60개의 요청을 보낼 수 있습니다. 이는 단일 키 기준이며, 동시 병렬 처리가 아닌 순차 큐 처리 방식입니다. 따라서 대용량 HR 자료나 교육 콘텐츠를 일괄 변환할 때는 요청 간격을 고려해야 합니다.
첫 충전 전 제한
초기 무료 체험 크레딧($0.50) 사용 중이거나 첫 충전이 완료되기 전까지는 분당 요청 수가 10회로 제한됩니다. 충전이 완료되면 즉시 60회 제한으로 상향 조정되므로, 대용량 작업은 충전 후 진행하는 것이 효율적입니다.
큐 시스템 동작
요청은 순서대로 처리되며, 이전 요청이 완료되지 않으면 이후 요청은 큐에 대기합니다. 100만 문자당 $10의 과금이 발생합니다. 효율적인 사용을 위해 텍스트는 4096자 단위로 나누어 전송하세요.
데이터 및 메타데이터
API는 요청에 대한 정확한 시간, 처리된 문자 수, 그리고 응답 상태 코드를 저장합니다. 이 데이터는 과금 계산과 서비스 상태 추적에 사용되며, 생성된 오디오 파일 자체는 저장되지 않습니다.
입력 텍스트는 오디오 생성 전용으로 사용되며 학습 데이터로 활용되지 않습니다. 요청 메타데이터는 오직 청구 검증과 로그 목적으로만 유지됩니다.
요청 시간 기록
각 API 호출의 정확한 시작 및 종료 시간을 기록합니다.
문자 수 기록
요청 본문에 포함된 전체 문자 수를 저장합니다. 공백과 구두점도 포함됩니다. 이 수치는 과금 기준이 되며, 100만 문자당 $10의 요금이 부과됩니다.
- 요청당 최대 4,096자 제한 기록
상태 코드 저장
각 요청의 성공 또는 실패 여부를 기록합니다. 합성 실패 시 요금이 반환되므로, 실패 요청의 코드도 명확히 추적됩니다.
- 성공, 실패 상태 기록
8개 음성 듣기
아래의 각 샘플은 동일한 문장을 이 API로 생성한 것입니다. 특정 언어가 지원되지 않는 경우(베트남어, 태국어, 인도네시아어, 우크라이나어 등) 명확히 구분하여 불필요한 호환성 문제를 방지합니다.
23개 언어
모든 음성은 이 언어들을 구사합니다.
