Quick Start

You can quickly integrate and use Supertone API in three steps.

​

1. Authentication

All API requests require authentication. Obtain an API key and include it in the HTTP header when making requests.

​

Obtaining API Key

After being approved for the closed beta service, you can obtain your Supertone API key directly from the console page.

Issuance Policy

1. Up to 3 API keys can be issued per account
   • Recommended to use separate keys for different environments (e.g., Dev, Stage, Production)
2. Keys can be revoked and reissued at any time
   • When key rotation is needed for security reasons
   • When key compromise is suspected
   • When you want to separate keys by project

Issuance Process

1. Log in to the console page
2. Access API Keys menu from the sidebar
3. Click ‘Create API Key’ button to complete the issuance

​

API Authentication

Supertone API uses API key authentication through HTTP request headers.

Header Configuration

• Key: x-sup-api-key
• Value: Your issued API key
• Base URL: https://supertoneapi.com

This authentication header must be included in all API requests. Missing headers or incorrect API keys will result in a 401 Unauthorized response.

x-sup-api-key: YOUR_API_KEY

Authentication Code Examples

Here are authentication implementation examples for various programming languages.

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

Important Notes

• Store your API key in environment variables or configuration files to prevent exposure.
• If your API key is exposed, immediately revoke it from the console and obtain a new one.
• All API communications are conducted via HTTPS, so check for any SSL/TLS certificate issues.
• If you receive a 401 error, verify that your API key is correct and the header name is accurate.

​

2. Getting Voice ID

You need to specify a voice ID for voice generation. You can check available voice information by calling Get Vocies API or Search Voices API.

Check by calling the Get Voices API

You can check the list of available voices by calling the Get Voices API. The API returns a JSON response in the following format. Use the voice_id included in the JSON response as a parameter when calling the 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"
        }
    ]
}

Check by calling the Search Voices API

You can search for voices using various keywords and filters by calling the Search Voices API. The API returns a JSON response in the following format. Use the voice_id included in the JSON response as a parameter when calling the 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

Convert text to speech using your selected voice ID.

​

Basic Request Example

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!"
         }'

​

Specifying File Format

Supported Formats

You can specify the file format using the output_format query parameter.

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

# Request WAV format
https://supertoneapi.com/v1/text-to-speech?output_format=wav

# Request MP3 format
https://supertoneapi.com/v1/text-to-speech?output_format=mp3