Skip to main content
POST
/
v1
/
text-to-speech
/
{voice_id}
Convert text to speech
curl --request POST \
  --url https://supertoneapi.com/v1/text-to-speech/{voice_id} \
  --header 'Content-Type: application/json' \
  --header 'x-sup-api-key: <api-key>' \
  --data '
{
  "text": "<string>",
  "language": "en",
  "style": "<string>",
  "model": "sona_speech_1",
  "output_format": "wav",
  "voice_settings": {
    "pitch_shift": 0,
    "pitch_variance": 1,
    "speed": 1,
    "duration": 0,
    "similarity": 3,
    "text_guidance": 1,
    "subharmonic_amplitude_control": 1
  },
  "include_phonemes": false
}
'
"<string>"

​
Endpoint

https://supertoneapi.com/v1/text-to-speech/{voice_id}

​
Path Parameters

NameRequiredDescription
voice_idYesThe ID of the target voice.

​
Request Body

Note on Supported Languages by Model The set of supported input languages varies depending on the TTS model:
  • sona_speech_1 — en, ko, ja
  • supertonic_api_1 — en, ko, ja, es, pt
  • sona_speech_2 — en, ko, ja, bg, cs, da, el, es, et, fi, hu, it, nl, pl, pt, ro, ar, de, fr, hi, id, ru, vi
NameRequiredDescription
textYesThe text to convert (max 300 characters).
languageYesLanguage code. Supported: en, ko, ja, bg, cs, da, el, es, et, fi, hu, it, nl, pl, pt, ro, ar, de, fr, hi, id, ru, vi
styleNoEmotional style. E.g., neutral, happy, sad, etc. If not specified, the character’s default style is applied
modelNoTTS model. Default: sona_speech_1.
output_formatNoOutput format. Options: wav, mp3. Default: wav.
voice_settingsNoAdvanced voice parameters (see below).
include_phonemesNoIf true, returns phoneme timing data along with audio (Base64-encoded). Default: false.

​
Voice Settings (optional)

Note on Voice Settings by Model The available Voice Settings vary depending on the TTS model:
  • sona_speech_1 — Supports all Voice Settings listed below.
  • supertonic_api_1 — Supports only the speed setting; all other settings are ignored.
  • sona_speech_2 — Supports only the following Voice Settings: pitch_shift, pitch_variance, speed.
NameRangeDefaultDescription
pitch_shift-24 → 240Pitch adjustment in semitones.
pitch_variance0 → 21Degree of pitch variation.
speed0.5 → 21Adjusts the generated audio uniformly faster or slower. (ratio)
duration0 → 600When provided, speech is generated to match the given duration (seconds)
similarity1 → 53Controls how closely the generated speech matches the original character voice.
text_guidance0 → 41Controls how sensitively speech characteristics adapt to the input text content.
subharmonic_amplitude_control0 → 21Controls the amount of subharmonic amplitude of the generated speech.

​
Response

Depending on include_phonemes, returns: Binary Audio
(Default & when include_phonemes=false)
audio/wav – Raw WAV file.
audio/mpeg – Raw MP3 file. JSON with Phoneme Data
(when include_phonemes=true) 
{
  "audio_base64": "UklGRnoGAABXQVZF...",
  "phonemes": {
    "symbols": ["", "h", "ɐ", "ɡ", "ʌ", ""],
    "start_times_seconds": [0, 0.092, 0.197, 0.255, 0.29, 0.58],
    "durations_seconds": [0.092, 0.104, 0.058, 0.034, 0.29, 0.162]
  }
}

​
Headers:

X-Audio-Length (number) – Duration of the audio in seconds.

​
Notes

  • A 400 error will occur if the text length exceeds 300 characters.
  • speed is applied after duration. (Example: duration=5seconds, speed=2times → final audio ≈ 10seconds)
  • Calls are possible even without style, but default styles may vary by character, so please call Get Voices API to check the default style (the first value in the styles array is the default).
  • The audio file in the response can be directly saved or played (appropriate handling required depending on client).

Authorizations

​
x-sup-api-key
string
header
required

Path Parameters

​
voice_id
string
required

Body

application/json
​
text
string
required

The text to convert to speech

Maximum string length: 300
​
language
enum<string>
required

The language code of the text

Available options:
en,
ko,
ja,
bg,
cs,
da,
el,
es,
et,
fi,
hu,
it,
nl,
pl,
pt,
ro,
ar,
de,
fr,
hi,
id,
ru,
vi
​
style
string

The style of character to use for the text-to-speech conversion

​
model
enum<string>
default:sona_speech_1

The model type to use for the text-to-speech conversion

Available options:
sona_speech_1,
sona_speech_2,
supertonic_api_1
​
output_format
enum<string>
default:wav

The desired output format of the audio file (wav, mp3). Default is wav.

Available options:
wav,
mp3
​
voice_settings
object
​
include_phonemes
boolean
default:false

Return phoneme timing data with the audio

Response

Returns either binary audio or JSON with phoneme data based on include_phonemes parameter

Binary audio file (when include_phonemes=false or omitted)