이 페이지는 Supertone API를 처음 사용해보는 분들이
빠르게 음성 합성 흐름을 체험해볼 수 있도록 구성되어 있습니다. 아래 순서를 따라 직접 호출까지 완료해보세요.

​
1. API Key를 발급받고 인증 준비하기

수퍼톤 API는 API Key 기반 인증을 사용합니다.
콘솔에 가입하고, 새로운 서비스를 생성하면 바로 API Key를 발급받을 수 있습니다.
  • 콘솔 주소: https://console.supertoneapi.com
  • 하나의 계정당 최대 3개의 API Key를 발급받을 수 있으며, 필요 시 폐기 및 재발급도 가능합니다.
  • API 호출 시에는 x-sup-api-key 헤더에 발급받은 키를 넣어주세요.
x-sup-api-key: [YOUR_API_KEY]

​
2. 사용할 수 있는 보이스 ID 확인하기

보이스 ID는 텍스트를 어떤 목소리로 읽을지 결정하는 키입니다. 현재 계정에서 사용 가능한 보이스는 다음 세 가지 방법으로 확인할 수 있습니다

​
2.1 Supertone Play에서 복사하기

가장 손쉽게 보이스 ID를 확인하는 방법은 Supertone Play의 보이스 라이브러리에서 복사하는 것입니다. 아래 예시 이미지에서처럼, 각 보이스 내의 ‘Copy voice ID’ 버튼을 클릭하면 해당 보이스의 voice_id가 클립보드에 복사됩니다.
클론드 보이스 역시 같은 방법으로 voice_id를 복사할 수 있습니다.
복사한 ID는 콘솔이나 API에서 바로 사용할 수 있습니다.

​
2.2 모든 보이스 한 번에 확인하기

GET /voices 엔드포인트를 사용하면, 조건 없이 사용 가능한 전체 보이스 목록을 받아올 수 있습니다. 
GET /v1/voices

​
2.3 조건에 맞는 보이스 찾기

GET /v1/voices/search에서는 언어, 스타일 등을 기준으로 보이스를 필터링할 수 있습니다.
  • 예: 한국어 보이스 중 스타일이 ‘happy’인 경우만 조회
GET /v1/voices/search?language=ko&style=happy
각 보이스의 id 필드를 확인해 실제 호출에 사용할 수 있습니다.

​
3. 음성 생성하기

보이스 ID를 확인했다면, 이제 실제로 텍스트를 음성으로 변환해볼 수 있습니다. 아래는 기본적인 호출 예시입니다: 
POST /v1/text-to-speech/e5f6fb1a53d0add87afb4f
Content-Type: application/json
x-sup-api-key: [YOUR_API_KEY]

{
  "text": "안녕하세요, 수퍼톤 API입니다.",
  "language": "ko",
  "style": "neutral",
  "model": "sona_speech_1"
}
응답은 오디오 파일 스트림 형식(WAV)으로 반환되며, 헤더의 X-Audio-Length 값을 통해 생성된 음성의 길이를 확인할 수 있습니다. 이제 수퍼톤 API를 연동할 준비가 완료되었습니다. 이제 다음 단계로 넘어가, 더 다양한 설정과 고급 사용법을 확인해보세요.