빠르게 시작하기

수퍼톤 API는 3단계를 거쳐 빠르게 연동해 사용하실 수 있습니다.

​

1. 인증

모든 API 요청에는 인증이 필요합니다. API 키를 발급받아 HTTP 헤더에 포함하여 요청하세요.

​

API 키 발급

수퍼톤 API 키는 클로즈드 베타 서비스 승인 후 콘솔 페이지에서 직접 발급받으실 수 있습니다.

발급 정책

1. 계정당 한 번에 최대 3개의 API 키 발급 가능
   • 개발 환경별로 구분하여 사용하는 것을 권장합니다(ex. Dev, Stage, Production)
2. 언제든지 키 폐기 및 재발급 가능
   • 보안상의 이유로 키 교체가 필요한 경우
   • 키 유출이 의심되는 경우
   • 프로젝트 단위로 키를 구분하고 싶은 경우

발급 절차

1. 콘솔 페이지 로그인
2. 사이드바 > API Keys 메뉴 접속
3. ‘Create API Key’ 버튼을 클릭하여 키 발급 완료

​

API 인증

수퍼톤 API는 HTTP 요청 헤더를 통한 API 키 인증 방식을 사용합니다.

헤더 구성

• 키: x-sup-api-key
• 값: 발급받은 API 키
• Base URL: https://supertoneapi.com

모든 API 요청에는 반드시 이 인증 헤더가 포함되어야 합니다. 헤더가 누락되거나 잘못된 API 키가 제공될 경우 401 Unauthorized 응답이 반환됩니다.

x-sup-api-key: YOUR_API_KEY

인증 코드 예제

각 프로그래밍 언어별 인증 구현 예제입니다.

주의사항

• API 키는 노출되지 않도록 환경 변수나 설정 파일에 별도로 보관하여 관리하시기 바랍니다.
• API 키가 노출된 경우 즉시 콘솔에서 해당 키를 폐기하고 새로운 키를 발급받으세요.
• 모든 API 통신은 HTTPS를 통해 이루어지므로, SSL/TLS 인증서 관련 이슈가 없는지 확인하세요.
• 401 오류가 발생하는 경우 API 키가 올바른지, 헤더 이름이 정확한지 확인하세요.

​

2. 보이스 아이디 가져오기

음성 생성을 위해서는 보이스 아이디를 지정해야 합니다. 보이스 아이디는 다음 두 가지 방법으로 확인하실 수 있습니다.

​

Get Voices 활용

API를 호출하여 사용 가능한 보이스 목록을 조회합니다.

curl -X GET "https://supertoneapi.com/v1/voices" \
     -H "x-sup-api-key: YOUR_API_KEY"

응답 예시

{
	"voices": [
		{
	    "voice_id": "54CyP2zU9HCeLVCpzDRFPi",
	    "name": "Yoonho",
	    "description": "Yoonho is a sarcastic and indifferent teenager. He doesn't express his emotions well. ",
	    "age": "young-adult",
	    "gender": "male",
	    "use_case": "game",
	    "language": "ko",
	    "style": "blank_high"
	  }
	]
}

​

Supertone Play 활용

Supertone Play에서 직접 음성을 테스트해보고 원하는 보이스를 선택할 수 있습니다.

• 2주간 무료로 모든 보이스 테스트 가능
• 실제 음성을 들어보고 선택 가능
• 생성된 음성의 보이스 아이디와 설정을 그대로 API에서 사용 가능

​

3. 음성 합성(Text-to-speech)

선택한 보이스 아이디로 텍스트를 음성으로 변환합니다.

​

기본 요청 예시

curl -X POST "https://supertoneapi.com/v1/text-to-speech?output_format=wav" \
     -H "x-sup-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "voice_id": "54CyP2zU9HCeLVCpzDRFPi",
           "language": "en",
           "text": "Good morning. Rise and shine!"
         }'

​

파일 형식 지정

지원 형식

output_format 쿼리 파라미터로 파일 형식을 지정할 수 있습니다.

• wav: ?output_format=wav
• mp3: ?output_format=mp3

# WAV 형식 요청
https://supertoneapi.com/v1/text-to-speech?output_format=wav

# MP3 형식 요청
https://supertoneapi.com/v1/text-to-speech?output_format=mp3