이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.
API 시작하기
API Key는 어디서 발급받나요?
API Key는 어디서 발급받나요?
개발자 콘솔에 가입하고 새 키를 생성하세요. 계정당 최대 3개의 키를 발급할 수 있으며, 언제든지 폐기하거나 재발급할 수 있습니다.
요청은 어떻게 인증하나요?
요청은 어떻게 인증하나요?
모든 요청에
x-sup-api-key: [YOUR_API_KEY] 헤더를 포함하세요. 두 SDK 모두 생성자를 통해 키를 받습니다 — 인증을 참고해 주세요.Play 계정과 별도로 가입해야 하나요?
Play 계정과 별도로 가입해야 하나요?
아니요. API와 Supertone Play는 동일한 계정, 크레딧 잔액, 보이스 라이브러리를 공유합니다.
공식적으로 지원되는 SDK는 무엇인가요?
공식적으로 지원되는 SDK는 무엇인가요?
두 SDK가 공식 지원됩니다. Python(PyPI의
supertone)과 TypeScript(npm의 @supertone/supertone)입니다. 다른 언어에서는 REST API를 직접 호출하시기 바랍니다.보이스와 TTS 호출
보이스 ID는 어떻게 찾나요?
보이스 ID는 어떻게 찾나요?
세 가지 방법이 있습니다. (1) Supertone Play의 보이스 카드에서 복사, (2)
GET /v1/voices 호출, (3) GET /v1/voices/search로 필터 검색. 자세한 내용은 보이스를 참고해 주세요.Play에서 만든 클론드 보이스를 API에서 사용할 수 있나요?
Play에서 만든 클론드 보이스를 API에서 사용할 수 있나요?
네. Play에서 클로닝한 보이스는 동일 계정의 API에서 즉시 사용할 수 있습니다. 마찬가지로
POST /v1/custom-voices/cloned-voice를 통해 생성한 보이스도 Play에서 바로 확인할 수 있습니다. 별도의 동기화 과정은 필요하지 않습니다.존재하는 보이스인데도 403이 발생합니다. 왜 그런가요?
존재하는 보이스인데도 403이 발생합니다. 왜 그런가요?
커스텀(클론드) 보이스는 해당 보이스를 생성한 계정에서만 호출할 수 있습니다. 다른 계정의 키를 사용하면 API는
403 Forbidden을 반환합니다.보이스가 지원하는 언어/스타일/모델 조합은 어디서 확인하나요?
보이스가 지원하는 언어/스타일/모델 조합은 어디서 확인하나요?
보이스 객체의
samples 필드에 지원되는 모든 (language, style, model) 조합과 각 조합의 미리듣기 URL이 포함되어 있습니다. TTS 요청을 보내기 전에 확인하세요.style은 필수 입력인가요?
style은 필수 입력인가요?
아니요.
style을 생략하면 해당 보이스의 styles 배열의 첫 번째 값이 기본값으로 사용됩니다.피치나 속도를 조정할 수 있나요?
피치나 속도를 조정할 수 있나요?
네 — Voice settings를 참고해 주세요. 모델마다 지원하는 파라미터가 다르며, 지원되지 않는 설정은 조용히 무시됩니다.
텍스트는 얼마나 길게 입력할 수 있나요?
텍스트는 얼마나 길게 입력할 수 있나요?
raw API는
text를 300자로 제한합니다. Python과 TypeScript SDK는 더 긴 텍스트를 자동으로 청크 분할한 뒤 오디오를 병합합니다. 자세한 내용은 장문 처리를 참고해 주세요.`predict_duration`은 어떤 용도인가요?
`predict_duration`은 어떤 용도인가요?
주어진 텍스트의 생성 오디오 예상 길이를 반환합니다 — 크레딧이 차감되지 않습니다. 비용 미리보기와 UI 힌트에 유용합니다. Predict duration을 참고해 주세요.
크레딧과 요금제
API는 어떻게 과금되나요?
API는 어떻게 과금되나요?
생성된 오디오의 초 단위로 크레딧이 차감됩니다. Play와 동일한 크레딧 시스템을 사용하며, Play 구독 페이지에서 크레딧을 구매할 수 있습니다.
크레딧 잔액은 어떻게 확인하나요?
크레딧 잔액은 어떻게 확인하나요?
두 가지 방법이 있습니다. (1)
GET /v1/credits를 호출(또는 SDK의 get_credit_balance 사용), (2) 콘솔 또는 Play의 대시보드 확인.크레딧은 Play와 API 간에 공유되나요?
크레딧은 Play와 API 간에 공유되나요?
네. 동일한 잔액이 양쪽에 적용됩니다. 클론드 보이스 호출도 프리셋 보이스와 동일한 방식으로 크레딧을 차감합니다.
오류와 트러블슈팅
가장 흔한 오류는 무엇인가요?
가장 흔한 오류는 무엇인가요?
- 401 — API Key 누락 또는 잘못된 키
- 402 — 크레딧 부족
- 403 — 이 계정 소유가 아닌 보이스
- 400 — 요청 본문 문제(필드 누락, 잘못된 enum, raw API에서 300자 초과 등)
- 429 — 요청 수 제한 도달
호출이 계속 실패합니다. 어디부터 확인해야 하나요?
호출이 계속 실패합니다. 어디부터 확인해야 하나요?
다음 순서로 확인하세요.
x-sup-api-key헤더가 앞뒤 공백 없이 설정되어 있는지.- POST 요청에
Content-Type: application/json이 설정되어 있는지. voice_id가 이 계정의 실제 ID인지(GET /v1/voices또는GET /v1/custom-voices로 확인).text,language,style이 해당 보이스가 지원하는 값과 일치하는지.
요청 수 제한은 어떻게 되나요?
요청 수 제한은 어떻게 되나요?
기본값은 티어에 따라 분당 20 / 30 / 60회입니다. 보이스 클로닝은 분당 10회입니다. 자세한 내용은 요청 수 제한을 참고해 주세요.
운영
누구나 API를 사용할 수 있나요?
누구나 API를 사용할 수 있나요?
네 — 콘솔에 가입하면 바로 시작할 수 있습니다. 별도의 승인 절차는 없습니다.
엔터프라이즈 플랜도 있나요?
엔터프라이즈 플랜도 있나요?
네. 팀 단위 사용, 상향된 요청 제한, 하위 사용자 계정, 전용 처리 용량이 필요한 경우 엔터프라이즈 문의를 통해 신청해 주세요.
버그를 보고하거나 도움을 받으려면 어디로 문의하나요?
버그를 보고하거나 도움을 받으려면 어디로 문의하나요?
고객 지원 페이지에서 1:1 문의를 남겨주세요. 요청 페이로드, 헤더, 타임스탬프를 함께 전달해 주시면 더 빠르게 해결해 드릴 수 있습니다.