Generate speech from text and return word/character-level timestamps aligned with the audio. Useful for subtitle sync, per-character highlight animation, and speech-region visualization.
The request body matches the standard /v1/text-to-speech endpoint (voice_id, text, model, language, prompt, output, seed). Instead of raw audio bytes, this endpoint returns a JSON object containing base64-encoded audio plus words and characters arrays.
Use the optional granularity query parameter to return only word-level or only character-level timestamps and reduce payload size.
Language note. For languages that do not use whitespace between words - such as Japanese (
jpn) and Chinese (zho) - word-level alignment collapses the entire sentence into a single "word". For those languages, always requestgranularity=charto receive usable per-character timestamps.
See Listing all voices for available voices.
X-API-KEYstringheaderrequiredAPI key for authentication. You can obtain an API key from the Typecast API Console.
granularityword | charFilter for which timestamp arrays to return.
words and characters.word: returns words only (characters is null).char: returns characters only (words is null).Languages without whitespace (e.g., jpn, zho): word alignment yields a single segment covering the whole sentence, so use char to obtain meaningful timestamps.
wordcharText-to-speech request parameters
voice_idstringrequiredVoice identifier. Two prefixes are supported:
tc_ - Built-in Typecast voices (e.g., tc_60e5426de8b95f1d3000d7b5). See Listing all voices for available IDs.uc_ - Custom voices created via Instant cloning (e.g., uc_64a1b2c3d4e5f6a7b8c9d0e1). Only the owner of a cloned voice can use it.Case-sensitive: must use lowercase prefix.
textstringrequiredText to convert to speech. Minimum 1 character, maximum 2000 characters. Credits consumed based on text length. Supports multiple languages including English, Korean, Japanese, and Chinese. Special characters and punctuation are handled automatically.
modelssfm-v30 | ssfm-v21requiredVoice model to use for speech synthesis.
ssfm-v30ssfm-v21languagestringLanguage code following ISO 639-3 standard. Case-insensitive (both "ENG" and "eng" are accepted). If not provided, will be auto-detected based on text content.
| Code | Language |
|---|---|
| ARA | Arabic |
| IND | Indonesian |
| POR | Portuguese |
| BEN | Bengali |
| ITA | Italian |
| RON | Romanian |
| BUL | Bulgarian |
| JPN | Japanese |
| RUS | Russian |
| CES | Czech |
| KOR | Korean |
| SLK | Slovak |
| DAN | Danish |
| MSA | Malay |
| SPA | Spanish |
| DEU | German |
| NAN | Min Nan |
| SWE | Swedish |
| ELL | Greek |
| NLD | Dutch |
| TAM | Tamil |
| ENG | English |
| NOR | Norwegian |
| TGL | Tagalog |
| FIN | Finnish |
| PAN | Punjabi |
| THA | Thai |
| FRA | French |
| POL | Polish |
| TUR | Turkish |
| HIN | Hindi |
| UKR | Ukrainian |
| VIE | Vietnamese |
| HRV | Croatian |
| YUE | Cantonese |
| ZHO | Chinese |
| HUN | Hungarian |
| Code | Language |
|---|---|
| ARA | Arabic |
| IND | Indonesian |
| RON | Romanian |
| BUL | Bulgarian |
| ITA | Italian |
| RUS | Russian |
| CES | Czech |
| JPN | Japanese |
| SLK | Slovak |
| DAN | Danish |
| KOR | Korean |
| SPA | Spanish |
| DEU | German |
| MSA | Malay |
| SWE | Swedish |
| ELL | Greek |
| NLD | Dutch |
| TAM | Tamil |
| ENG | English |
| POL | Polish |
| TGL | Tagalog |
| FIN | Finnish |
| POR | Portuguese |
| UKR | Ukrainian |
| FRA | French |
| HRV | Croatian |
| ZHO | Chinese |
Timestamp endpoint note. For languages without inter-word whitespace - Japanese (
jpn) and Chinese (zho) - word-level alignment collapses the whole sentence into a single segment. Always pair these languages withgranularity=charto receive usable per-character timestamps.
promptPromptEmotion and style settings for the generated speech, including emotion type (happy/sad/angry/normal) and intensity (0.0 to 2.0) to control the emotional expression
emotion_typestringDiscriminator field to identify the prompt type. Must be set to "smart" for context-aware emotion inference.
previous_textstringText that comes BEFORE the text field in TTSRequest. Provides backward context for emotion inference.
The model analyzes the flow: previous_text → text (synthesized) → next_text
next_textstringText that comes AFTER the text field in TTSRequest. Provides forward context for emotion inference.
The model analyzes the flow: previous_text → text (synthesized) → next_text
emotion_typestringDiscriminator field to identify the prompt type. Must be set to "preset" for preset-based emotion control.
emotion_presetnormal | sad | happy | angry | whisper | toneup | tonedownEmotion preset to apply to the generated speech.
Supported emotions: normal, happy, sad, angry, whisper, toneup, tonedown
Check available emotions for each voice through the /v2/voices API.
normalsadhappyangrywhispertoneuptonedownemotion_intensitynumberControls the strength of emotional expression in the generated speech.
emotion_presetobjectEmotion preset to apply.
Supported emotions for ssfm-v21: normal, happy, sad, angry
Check available emotions for each voice through the /v2/voices API.
emotion_intensityobjectControls the strength of emotional expression (0.0 to 2.0).
outputobjectAudio output settings including volume (0-200), pitch (-12 to +12 semitones), tempo (0.5x to 2.0x), and format (wav/mp3) for controlling the final audio characteristics
target_lufsnumberSets the target absolute loudness (LUFS) for the output audio. This normalizes all generated voices to a consistent volume level, regardless of the original source's loudness. Values closer to 0 are louder, while values closer to -70 are quieter.
volume parameter. Use target_lufs for consistent absolute loudness across different clips, or use volume for traditional relative scaling.volumeintegerAdjusts the relative volume of the output audio: 0 (completely silent), 50 (half volume), 100 (standard volume, default), 150 (50% louder than standard), 200 (maximum volume, twice as loud as standard).
Since this only scales the existing volume, using volume can amplify the loudness differences between voices if they have different baseline levels. For consistent output across all clips, use target_lufs instead.
target_lufs parameter.Required range: 0 <= x <= 200
audio_pitchintegerAdjusts the pitch in semitones to affect perceived gender and age: -12 (one octave lower, deeper voice), -6 (half octave lower), 0 (original pitch, default), +6 (half octave higher), +12 (one octave higher, higher voice)
audio_temponumberControls speech speed: 0.5 (half speed, very slow and clear), 0.75 (slightly slower than normal), 1.0 (normal speaking speed, default), 1.5 (50% faster than normal), 2.0 (double speed, very fast speech)
audio_formatwav | mp3Output audio format.
WAV format:
MP3 format:
wavmp3seedintegerUnsigned integer seed for reproducible speech generation. The same seed with the same input parameters will produce identical audio output.
application/jsonaudiostringBase64-encoded audio bytes. Decode and write to a file using the audio_format extension.
audio_formatwav | mp3Audio encoding format of the bytes in audio - either wav or mp3, mirroring the request's output.audio_format.
wavmp3audio_durationnumberLength of the generated audio in seconds.
wordsobject[]Word-level timestamps (with attached punctuation). null when the request uses granularity=char.
textstringThe text fragment from the original transcript (includes any attached punctuation).
startnumberStart time of this segment, in seconds from the beginning of the audio.
endnumberEnd time of this segment, in seconds from the beginning of the audio.
charactersobject[]Character-level timestamps (including punctuation and whitespace). null when the request uses granularity=word.
textstringThe text fragment from the original transcript (includes any attached punctuation and whitespace).
startnumberStart time of this segment, in seconds from the beginning of the audio.
endnumberEnd time of this segment, in seconds from the beginning of the audio.