자주 묻는 질문
API 키는 어디서 찾을 수 있나요?
API 키는 /get-api-key/ 페이지에서 확인할 수 있습니다. Google 또는 이메일로 가입한 후 대시보드에서 키를 생성하거나 확인하세요. 계당 활성 키는 하나만 유지되며, 필요 시 새 키를 발급할 수 있습니다.
OpenAI SDK를 사용하려면 어떻게 설정하나요?
OpenAI SDK의 base_url을 https://api.playmb99.com/v1로 변경하고 API 키를 설정하면 됩니다. 요청 형식은 OpenAI 스피치 엔드포인트와 동일하므로, 기존 코드를 그대로 사용하거나 base_url만 수정하여 연동할 수 있습니다.
curl 명령어 예제는 어디에서 확인하나요?
준비된 curl 예제는 /get-api-key/ 페이지에서 확인할 수 있습니다. API 키와 함께 제공되는 예제를 복사하여 바로 테스트하거나, 문서의 코드 블록을 참조하여 요청을 구성할 수 있습니다.
지원되는 오디오 형식은 무엇인가요?
mp3, wav, opus, flac, pcm 형식을 지원합니다. response_format 필드에 원하는 형식을 지정하여 요청하면 해당 형식의 오디오 파일을 응답으로 받습니다. 각 형식은 용량과 품질 요구사항에 따라 선택하여 사용하세요.
API 요청 속도 제한은 어떻게 되나요?
키당 분당 60회 요청이 허용됩니다. 첫 충전 전에는 분당 10회로 제한됩니다. 이 제한을 초과하면 요청이 지연되거나 거부될 수 있으므로, 대량 처리 시 큐 대기 시간을 고려하여 요청을 전송하세요.
오류가 발생하면 어떻게 처리하나요?
합성 실패 시 요금이 전액 환불됩니다. 오류 응답 코드를 확인하고, 텍스트 길이나 형식 오류를 교정한 후 재시도하세요. 실패한 요청은 비용이 발생하지 않으므로 안전합니다.
4096자를 초과하는 텍스트는 어떻게 처리하나요?
4096자를 초과하는 텍스트는 여러 부분으로 나누어 각 부분별로 API 요청을 전송해야 합니다. 생성된 오디오 파일들을 클라이언트 측에서 연결하여 긴 텍스트의 음성을 완성할 수 있습니다.
언어 코드를 명시하지 않으면 어떻게 되나요?
언어 코드를 지정하지 않으면 시스템이 텍스트의 문자를 분석하여 언어를 자동 감지합니다. 비영어권 라틴 문자 텍스트의 경우 명확한 인식을 위해 language 필드에 ISO 코드를 명시하는 것이 좋습니다.
API 키를 재생성하면 기존 키는 어떻게 되나요?
새로운 API 키를 발급하면 기존 키는 즉시 비활성화됩니다. 동시에 두 키가 유효하지 않으므로, 재생성 전까지 새 키를 설정한 후 기존 키를 폐기해야 합니다.
응답 파일은 어떻게 저장하나요?
API 응답에서 반환된 오디오 파일은 서버에 저장되지 않고 클라이언트로 직접 전송됩니다. 따라서 수신된 파일을 로컬 스토리지나 클라우드 저장소에 직접 저장해야 하며, 서버 측 보관은 제공되지 않습니다.
속도 조절은 어떻게 적용되나요?
speed 파라미터를 0.25에서 4.0 사이로 설정하여 음성 속도를 조절할 수 있습니다. 기본값은 1.0이며, 값을 높이면 음성이 빨라지고 낮으면 느려집니다. 이는 생성된 오디오의 재생 속도에 영향을 줍니다.
오디오 파일의 품질은 어떤가요?
tts-1-hd 모델을 사용하면 더 높은 품질의 음성을 생성할 수 있습니다. 모든 모델은 동일한 엔진과 가격을 사용합니다. 모델 선택은 가격 차이 없이 동일합니다.
에러 코드 401의 의미는 무엇인가요?
401 오류는 인증 실패를 의미합니다. API 키가 잘못되었거나 만료되었을 수 있습니다. /get-api-key/ 페이지에서 올바른 키를 확인하고, Authorization 헤더에 Bearer 토큰 형식으로 정확히 입력했는지 다시 확인하세요.
API 키의 보안은 어떻게 유지하나요?
계정당 하나의 활성 키를 유지하며, 필요 시 새 키를 발급하여 기존 키를 즉시 무효화할 수 있습니다. 키를 안전하게 보관하고, 공개된 소스에 노출되지 않도록 주의하세요. 키 재생성 시 이전 키는 즉시 정지됩니다.
첫 번째 요청
curl
curl https://api.playmb99.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.playmb99.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.playmb99.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 | 中文 |
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 키 발급 및 계정 설정
playmb99.com의 /get-api-key/ 페이지에서 Google 또는 이메일로 계정을 생성합니다. Google 로그인 시 $0.50(약 50,000자)의 무료 체험 크레딧이 7일 동안 부여되며, 이메일 가입은 크레딧 없이 시작됩니다.
대시보드에서 API 키를 확인하고 복사합니다. 유튜브 콘텐츠 제작 및 에이전시 워크플로우에 필요한 기본 연결 설정을 완료합니다.
Google 또는 이메일로 로그인
계정 생성은 사이트별로 독립적으로 관리됩니다. Google 로그인은 빠른 진입과 초기 크레딧 제공을, 이메일/비밀번호는 표준 계정 관리를 제공합니다.
- Google 로그인: 7일 동안 $0.50 무료 크레딧 제공
- 이메일/비밀번호: 크레딧 없이 바로 시작
- 계정은 사이트별 독립 관리
API 키 확인 및 복사
발급된 키는 tts-로 시작하며, 인증 헤더에 Bearer와 함께 사용됩니다. 현재 잔액, 사용량, 남은 문자 수를 대시보드에서 실시간으로 확인할 수 있습니다.
- 키 형식: tts-... (Bearer 인증)
- 실시간 잔액 및 사용량 확인 가능
- 준비된 curl 예제 제공
키 재생성 및 유효 기간
계정에서 새 키를 생성하면 기존 키는 즉시 무효화됩니다. 보안을 위해 주기적인 키 교체나 분실 시 재생성이 가능합니다. 키는 제한 없이 생성할 수 있습니다.
- 새 키 생성 시 기존 키 즉시 정지
- 무제한 키 재생성 가능
- 보안 유지 권장
첫 API 호출 (curl 예제)
SungVoice API는 POST 엔드포인트를 통해 텍스트를 오디오 파일로 변환합니다. 기본 구조는 OpenAI와 호환되며, API 키를 인증 헤더에 포함해야 합니다.
기본 JSON 요청 구조
요청 본문에는 모델 이름, 입력 텍스트, 음성 선택, 응답 형식, 속도 등의 필드가 필요합니다. JSON 형식으로 데이터를 전송하며, 최대 4096자까지 입력할 수 있습니다.
필수 파라미터 설명
model은 'tts-1' 또는 'tts-1-hd'를 사용합니다. input에는 변환할 텍스트를 입력하고, voice는 8가지 프리셋 중 하나를 선택합니다. response_format은 mp3, wav, opus, flac, pcm 중 하나로 설정합니다.
- 모델: tts-1, tts-1-hd
- 입력: 최대 4096자
- 음성: aria, nova, luna, sage, felix, milo, atlas, orion
- 형식: mp3, wav, opus, flac, pcm
응답 예시 및 파일 다운로드
성공적인 요청은 오디오 파일을 포함한 응답을 반환합니다. 파일은 자동으로 다운로드되며, 실패한 경우 요금이 청구되지 않습니다. 생성된 파일에는 합성 음성임을 나타내는 무음 워터마크가 포함됩니다.
OpenAI SDK 연동 방법
SungVoice API는 OpenAI의 speech 엔드포인트와 동일한 요청 형식을 사용합니다. 따라서 기존 OpenAI SDK를 그대로 사용하며 base_url과 API 키만 변경하면 바로 연동할 수 있습니다.
base_url 변경 설정
SDK 초기화 시 base_url을 https://api.playmb99.com/v1로 지정하고 Authorization 헤더에 발급된 Bearer 토큰을 설정하세요. 이렇게 하면 표준 OpenAI 호환 SDK를 통해 음성 생성 요청을 보낼 수 있습니다.
- base_url: https://api.playmb99.com/v1
- Auth: Authorization: Bearer tts-...
Python SDK 예제 코드
OpenAI Python 패키지를 사용하여 간단하게 오디오 파일을 생성할 수 있습니다. base_url과 api_key를 설정한 후 speech.create 메서드를 호출하면 mp3 형식의 오디오 데이터를 반환받습니다.
Node.js SDK 예제 코드
Node.js 환경에서도 공식 openai 패키지를 활용하여 동일한 구조로 API를 호출할 수 있습니다. base_url을 SungVoice의 엔드포인트로 변경하면 Python과 동일한 방식으로 오디오 파일을 얻을 수 있습니다.
지원 형식 및 오디오 설정
SungVoice API는 mp3, wav, opus, flac, pcm 등 다양한 오디오 형식을 지원합니다. YouTube 콘텐츠 제작 및 에이전시 워크플로우에 최적화된 형식을 선택하세요.
mp3, wav, opus, flac, pcm 지원
원하는 오디오 형식을 response_format 파라미터에 지정하여 요청하세요. mp3는 일반적인 유틸리티 및 웹 플레이어용, wav는 고품질 편집 및 포맷 변환용, opus와 flac은 대역폭 제한 환경 및 무손실 품질 보관용, pcm은 RAW 오디오 데이터용으로 사용됩니다. pcm은 raw 데이터가 필요할 때 사용합니다.
- mp3: 일반적인 유틸리티 및 웹 플레이어
- wav: 고품질 편집 및 포맷 변환
- opus: 대역폭이 제한된 환경
- flac: 무손실 품질 보관
- pcm: RAW 오디오 데이터
속도 조절 (0.25–4.0)
speed 파라미터를 0.25에서 4.0 사이로 설정하여 음성 속도를 조절할 수 있습니다. 기본값은 1.0이며, 유튜브 내레이션이나 교육용 콘텐츠에 맞게 빠르게 또는 천천히 조정하세요.
언어 코드 명시 방법
language 파라미터에 ISO 639-1 코드를 명시하여 발음을 정확히 설정하세요. 언어를 지정하지 않으면 라틴 문자는 영어로, 그 외 문자는 해당 스크립트의 기본 언어로 추측됩니다. 한국어, 일본어 등 비라틴 문자 언어는 반드시 언어 코드를 명시해야 합니다.
- ko: 한국어
- ja: 일본어
- zh: 중국어
- en: 영어
- de: 독일어
- fr: 프랑스어
- es: 스페인어
- pt: 포르투갈어
- it: 이탈리아어
- ru: 러시아어
- ar: 아랍어
- hi: 힌디어
- tr: 터키어
- nl: 네덜란드어
- pl: 폴란드어
- sv: 스웨덴어
- da: 덴마크어
- fi: 핀란드어
- no: 노르웨이어
- el: 그리스어
- he: 히브리어
- ms: 말레이어
- sw: 스와힐리어
속도 제한 및 처리 방식
API 키당 분당 60회 요청 제한이 적용됩니다. 초기 계정은 10회/분으로 제한되며, 첫 충전 후 제한이 해제됩니다.
긴 텍스트는 4,096자 단위로 분할하여 생성된 오디오를 연결합니다. 요청은 순차적으로 처리되므로 부하 시 큐 대기 시간이 발생할 수 있습니다.
분당 60회 요청 제한
계정당 분당 최대 60건의 요청이 가능합니다. 이 제한은 API 키 단위이며, 키 생성 시 적용됩니다.
초기 10회/분 제한 조건
초기 상태에서는 분당 10회 제한이 적용됩니다. 첫 USDT 충전이 완료되면 즉시 60회/분 제한으로 상승합니다.
큐 처리 및 대기 시간
요청은 순차적으로 처리됩니다. 서버 부하 시 요청이 큐에 쌓여 대기 시간이 발생할 수 있습니다. 짧은 문장은 수 초, 긴 텍스트는 실시간 생성 속도에 맞춰 처리됩니다.

오류 처리 및 상태 코드
API 호출 중 발생할 수 있는 오류를 처리하면 안정적인 파이프라인을 구축할 수 있습니다. SungVoice API는 표준 HTTP 상태 코드를 반환하므로, 개발자는 응답 본문과 상태 코드를 조합해 에러 유형을 판별해야 합니다.
실패한 요청은 요금이 부과되지 않습니다. 이는 API 키의 잔액을 불필요하게 소모하지 않도록 보장합니다. 재시도 로직을 구현할 때는 실패 원인에 따라 적절한 지연 시간과 재시도 횟수를 설정하는 것이 중요합니다.
일반 오류 코드 설명
4xx 오류는 주로 요청 형식 오류 또는 인증 실패를 의미합니다. 429 Too Many Requests는 분당 60회 제한을 초과했음을 나타냅니다. 초기 계정에는 분당 10회의 엄격한 제한이 적용되므로, 이를 초과하지 않도록 모니터링해야 합니다.
- 400 Bad Request: JSON 형식 오류 또는 필수 파라미터 누락
- 401 Unauthorized: API 키가 잘못되었거나 비활성화됨
- 429 Too Many Requests: 속도 제한 초과
- 500 Internal Server Error: 서버 내부 오류 (임시적)
실패 시 환불 확인
성공하지 않은 요청에 대해서는 요금이 청구되지 않습니다. API 응답 본문에 오류 코드와 메시지가 포함되며, 이는 실패를 명확히 나타냅니다. 계대 대시보드에서 실패한 요청의 상태와 함께 요금이 반환되었는지 확인할 수 있습니다.
- 실패 요청은 즉시 무료 처리됨
- 계정 대시보드에서 실패 이력 확인 가능
- 잔액 변동 내역에서 환불 확인
재시도 로직 구현
네트워크 불안정이나 일시적 서버 오류로 인한 실패에 대비해 재시도 로직을 구현해야 합니다. 지수 백오프(Exponential Backoff) 전략을 사용하여 재시도 간격을 점차 늘리면 서버 부하를 줄일 수 있습니다. 429 오류 발생 시, 현재 분당 요청 수를 모니터링하며 제한이 해제될 때까지 기다리는 것이 좋습니다.
- 지수 백오프 전략 권장
- 429 오류 시 대기 시간 증가
- 최대 재시도 횟수 설정 권장
오디오 파일 생성 및 처리
4096자를 초과하는 긴 텍스트는 여러 작은 조각으로 자동 분할되어 각각 음성 파일로 생성됩니다. 생성된 오디오 파일은 연결되어 하나의 긴 음성처럼 재생됩니다.
4096자 초과 텍스트 분할
요청 텍스트가 4096자를 넘으면 API가 자동으로 여러 청크로 나눕니다. 각 청크는 독립적으로 음성으로 변환되며, 클라이언트 측에서 파일들을 순서대로 이어 붙여야 합니다.
파일 연결 및 재생
분할된 오디오 파일들은 일관된 음성과 속도를 유지합니다. Python의 pydub나 Node.js의 fluent-ffmpeg를 사용해 MP3 또는 WAV 파일을 병렬로 다운로드한 후 연결하면 됩니다.
워터마크 확인 방법
모든 생성 파일에는 무음 워터마크가 내장되어 있습니다. 이는 일반 청취 시 인지되지 않지만, 기술적 검증을 통해 합성 음성임을 식별할 수 있습니다.
에이전시를 위한 확장 팁
에이전시 워크플로우에서는 효율적인 리소스 관리가 중요합니다. 여러 크리에이터의 병렬 요청을 처리하려면 API 키 회전과 적절한 로깅이 필수적입니다.
이 섹션에서는 대용량 배치 생성 시 성능을 최적화하는 실용적인 팁을 제공합니다.
병렬 처리 전략
동시 요청 수를 분당 60회 제한 내에 맞추세요. 단일 키로는 병렬 처리에 한계가 있으므로, 프로젝트별 전용 키를 발급받아 분산 처리하세요.
대용량 텍스트는 4096자 단위로 분할하여 비동기식으로 요청하고, 생성된 오디오 파일을 서버 측에서 연결하세요. 이는 대기 시간을 줄이는 핵심 전략입니다.
- 프로젝트별 전용 API 키 발급
- 비동기식 분할 요청 처리
- 서버 측 오디오 파일 연결
API 키 회전 정책
계정당 유효한 키는 하나만 유지됩니다. 새 키를 발급하면 이전 키는 즉시 무효화되므로, 모든 클라이언트 앱의 base_url을 업데이트해야 합니다.
보안 강화 위해 정기적으로 새 키를 발급하고, 이전 키의 사용 정지 시간을 확인하세요.
- 단일 활성 키 유지 원칙
- 발급 시 이전 키 즉시 정지
- 클라이언트 설정 동시 업데이트
로깅 및 모니터링
요청 시간, 문자 수, 상태 코드를 기록하여 비용과 성능을 추적하세요. 실패 시 환불이 발생하므로, 실패 로직을 명확히 로깅하세요.
OpenAI SDK의 로그 기능을 활용하여 지연 시간과 오류율을 모니터링할 수 있습니다.
데이터는 청구 목적으로만 유지되므로, 민감한 콘텐츠 정보는 별도로 관리하세요.
- 요청 메타데이터 로깅
- 실패 시 환불 확인 로그
- OpenAI SDK 로그 기능 활용
8개 음성 듣기
아래의 각 샘플은 동일한 문장을 이 API로 생성한 것입니다. 이 정보는 청구 내역 검증 및 기술적 문제 해결에만 사용되며, 실제 텍스트 내용이나 오디오 파일과는 분리되어 관리됩니다.
23개 언어
모든 음성은 이 언어들을 구사합니다.
