Text-to-Speech

Text To Speech with Timestamps

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). 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 request granularity=char to receive usable per-character timestamps.

See Listing all voices for available voices.

post/v1/text-to-speech/with-timestamps

Request

Base URL: https://api.typecast.ai
URL: https://api.typecast.ai/v1/text-to-speech/with-timestamps
Auth: API key in header X-API-KEY

Query parameters

granularity'word' | 'char'

Filter for which timestamp arrays to return.

Omitted: returns both 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.

Request body

textstring required

Text 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.

model'ssfm-v30' | 'ssfm-v21' required

TTS model version to use for speech synthesis. Different models offer varying capabilities and quality levels.

Available models:

ssfm-v30: Latest model with improved prosody and additional emotion presets (recommended)
ssfm-v21: Stable production model with proven reliability and consistent quality

languagestring

Language 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.

<details> <summary><strong>ssfm-v30 Supported Languages (37)</strong></summary>

Code	Language	Code	Language	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

</details> <details> <summary><strong>ssfm-v21 Supported Languages (27)</strong></summary>

Code	Language	Code	Language	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

</details>

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 with granularity=char to receive usable per-character timestamps.

voice_idstring required

Voice 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.

Example request

{
  "text": "Everything is so incredibly perfect that I feel like I'm dreaming.",
  "output": {
    "volume": 100,
    "audio_tempo": 1,
    "target_lufs": -14,
    "audio_format": "wav",
    "remove_silence_ms": 100
  },
  "prompt": {
    "next_text": "I am literally bursting with happiness and I never want this feeling to end!",
    "emotion_type": "smart",
    "previous_text": "I feel like I'm walking on air and I just want to scream with joy!"
  },
  "language": "eng",
  "voice_id": "tc_60e5426de8b95f1d3000d7b5"
}

Response

Success - Returns base64 audio and timestamps

audiostring required

Base64-encoded audio bytes. Decode and write to a file using the audio_format extension.

audio_format'wav' | 'mp3' required

Audio encoding format of the bytes in audio — either wav or mp3, mirroring the request's output.audio_format.

audio_durationnumber required

Length of the generated audio in seconds.

Changes

No recorded changes to this operation across all 1 revision of this API.