빠르게 시작하기
수퍼톤 API를 사용하여 고품질 AI 음성을 생성하는 방법을 단계별로 안내해드립니다.
수퍼톤 API는 3단계를 거쳐 빠르게 연동해 사용하실 수 있습니다.
인증
수퍼톤 API는 HTTP 요청 헤더를 통한 키 인증 방식을 사용합니다. API Key는 개발자 콘솔 페이지에서 발급받아 사용하실 수 있습니다.
보이스 아이디 선택
Get Voices API를 호출하여 사용할 수 있는 보이스를 확인하세요. Supertone Play에서 콘텐츠를 제작하며 다양한 보이스를 탐색한 뒤 선택할 수도 있습니다.
API 호출
선택한 보이스 아이디로 텍스트를 음성으로 변환하는 API를 호출할 수 있습니다.
1. 인증
모든 API 요청에는 인증이 필요합니다. API 키를 발급받아 HTTP 헤더에 포함하여 요청하세요.
API 키 발급
수퍼톤 API 키는 클로즈드 베타 서비스 승인 후 콘솔 페이지에서 직접 발급받으실 수 있습니다.
발급 정책
- 계정당 한 번에 최대 3개의 API 키 발급 가능
- 개발 환경별로 구분하여 사용하는 것을 권장합니다(ex.
Dev
,Stage
,Production
)
- 개발 환경별로 구분하여 사용하는 것을 권장합니다(ex.
- 언제든지 키 폐기 및 재발급 가능
- 보안상의 이유로 키 교체가 필요한 경우
- 키 유출이 의심되는 경우
- 프로젝트 단위로 키를 구분하고 싶은 경우
발급 절차
- 콘솔 페이지 로그인
- 사이드바 > API Keys 메뉴 접속
- ‘Create API Key’ 버튼을 클릭하여 키 발급 완료
API 인증
수퍼톤 API는 HTTP 요청 헤더를 통한 API 키 인증 방식을 사용합니다.
헤더 구성
- 키:
x-sup-api-key
- 값: 발급받은 API 키
- Base URL:
https://supertoneapi.com
모든 API 요청에는 반드시 이 인증 헤더가 포함되어야 합니다. 헤더가 누락되거나 잘못된 API 키가 제공될 경우 401 Unauthorized 응답이 반환됩니다.
인증 코드 예제
각 프로그래밍 언어별 인증 구현 예제입니다.
주의사항
- API 키는 노출되지 않도록 환경 변수나 설정 파일에 별도로 보관하여 관리하시기 바랍니다.
- API 키가 노출된 경우 즉시 콘솔에서 해당 키를 폐기하고 새로운 키를 발급받으세요.
- 모든 API 통신은 HTTPS를 통해 이루어지므로, SSL/TLS 인증서 관련 이슈가 없는지 확인하세요.
- 401 오류가 발생하는 경우 API 키가 올바른지, 헤더 이름이 정확한지 확인하세요.
2. 보이스 아이디 가져오기
음성 생성을 위해서는 보이스 아이디를 지정해야 합니다. Get Voices API, Search Voices API를 호출하여 사용 가능한 보이스들을 확인하실 수 있습니다.
Get Voices API를 호출해 확인
Get Voices API를 호출하여 사용 가능한 보이스 목록을 확인할 수 있습니다. API는 다음과 같은 형식의 JSON 응답을 반환합니다. JSON 응답 내 포함된 voice_id
를 API 호출 시 파라미터로 입력합니다.
Search Voices API를 호출해 확인
Search Voices API를 호출하여 다양한 키워드와 필터를 사용해 보이스를 검색할 수 있습니다. API는 다음과 같은 형식의 JSON 응답을 반환합니다. JSON 응답 내 포함된 voice_id
를 API 호출 시 파라미터로 입력합니다.
3. 음성 합성(Text-to-speech)
선택한 보이스 아이디로 텍스트를 음성으로 변환합니다.
기본 요청 예시
파일 형식 지정
지원 형식
output_format
쿼리 파라미터로 파일 형식을 지정할 수 있습니다.
- wav:
?output_format=wav
- mp3:
?output_format=mp3