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

1

인증

수퍼톤 API는 HTTP 요청 헤더를 통한 키 인증 방식을 사용합니다. API Key는 개발자 콘솔 페이지에서 발급받아 사용하실 수 있습니다.

2

보이스 아이디 선택

Get Voices API를 호출하여 사용할 수 있는 보이스를 확인하세요. Supertone Play에서 콘텐츠를 제작하며 다양한 보이스를 탐색한 뒤 선택할 수도 있습니다.

3

API 호출

선택한 보이스 아이디로 텍스트를 음성으로 변환하는 API를 호출할 수 있습니다.

​
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

인증 코드 예제

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

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

주의사항

  • 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 호출 시 파라미터로 입력합니다.

{
    "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"
        }
    ]
}

Search Voices API를 호출해 확인

Search Voices API를 호출하여 다양한 키워드와 필터를 사용해 보이스를 검색할 수 있습니다. API는 다음과 같은 형식의 JSON 응답을 반환합니다. JSON 응답 내 포함된 voice_id를 API 호출 시 파라미터로 입력합니다.

{
  "voices": [
    {
      "voice_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "age": "<string>",
      "gender": "<string>",
      "use_case": "<string>",
      "language": "<string>",
      "style": "<string>"
    }
  ],
  "total": 123,
  "page": 123,
  "page_size": 123,
  "total_pages": 123
}

​
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