Text-to-speech Guide

​

Overview

This document explains how to use Supertone’s Text To Speech API. You can convert text into natural-sounding speech using Supertone’s Text-to-speech technology.

​

Supported Languages

Supertone API provides voice models optimized for each language and currently supports the following languages:

1. Korean(ko)
2. Japanese(ja)
3. English(en)

​

Voice Selection Guide

​

1. Checking Available Voices

You can check available voice information in two ways.

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

Explore voices on Supertone Play

You can explore various voices within the Supertone Play product and copy the settings of voices you like to use them.

​

2. Understanding Voice Properties

Each voice has the following properties:

​

3. Selecting a Voice

1. Filter voices by desired language
2. Select voices with use_case that matches your project purpose
3. Select voices with desired age range and gender
4. Copy the voice_id of the selected voice and use it when calling the API

​

API Call Guide

​

1. Text Input Requirements

• Maximum length: 200 characters including spaces
• Text requirements:
  • Text consisting only of spaces or punctuation marks cannot be used
  • Correct grammar and notation must be used for accurate pronunciation
  • Special characters like “\n” should not be included

​

2. Audio Output Format

• Specified by the query parameter output_format
• Supported formats:
  • wav (default)
  • mp3

​

3. Model Selection

Choose from the following using the body parameter model:

Key Metrics

​

4. Voice Detailed Settings

1. pitch_shift
   • Range: -24 ~ 24 (Default: 0.0)
   • Description:
     • 1 unit = 1 semitone
     • Positive: Pitch increase (e.g., 10 = 5 tones up)
     • Negative: Pitch decrease (e.g., -10 = 5 tones down)
     • ±24 = 2 octave change
2. pitch_variance
   • Range: 0 ~ 2 (Default: 1.0)
   • Description:
     • 0: Minimum variation
     • 2: Maximum variation
     • Higher value means more dynamic voice
3. speed
   • Range: 0.5 ~ 2.0 (Default: 1.0)
   • Description:
     • 1.0: Default speed
     • 2.0: Double speed
     • 0.5: Half speed

​

Generated Results Guide

​

1. File Name Structure

Components

• Generation time: 2024-08-28_05-02-53 (YYYY-MM-DD_HH-mm-ss)
• Voice name: arin
• Language: ko
• Style: happy
• Pitch shift: ps0
• Pitch variance range: pv100 (100 = 1.0)
• Speech speed: s100 (100 = 1.0)
• File format: .mp3

​

2. Notes

Since the generated voice is based on machine learning technology, even with the same settings, the results may not be completely identical, and the quality may not be completely uniform.