--- title: "Streaming Text To Speech" method: POST path: "/v1/text-to-speech/stream" tags: ["Text-to-Speech"] --- # Streaming Text To Speech `POST /v1/text-to-speech/stream` ## Request - Base URL: `https://api.typecast.ai` - URL: `https://api.typecast.ai/v1/text-to-speech/stream` - Auth: API key in header `X-API-KEY` Generate speech from text using real-time streaming, allowing audio playback to begin before the entire synthesis is complete. This endpoint streams audio data in chunks, enabling low-latency audio playback for applications requiring immediate feedback. **Streaming Format:** * **WAV format**: First chunk contains WAV header (size\=0xFFFFFFFF for streaming) followed by raw PCM data. Subsequent chunks contain only PCM data. * **MP3 format**: Each chunk contains post-processed MP3 data that can be decoded independently. **Use Cases:** * Conversational AI, chatbots and real-time voice assistants * Interactive applications requiring immediate audio feedback * Long-form content where waiting for full synthesis is impractical **Request Parameters:** Uses the same TTSRequest schema as the standard TTS endpoint. Set `output.audio_format` to "wav" or "mp3" to control the streaming format. ## Request body - object: Text-to-speech streaming request parameters - `text` string, 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 - `output` object: Streaming audio output settings including pitch (-12 to +12 semitones), tempo (0.5x to 2.0x), format (wav/mp3), and target\_lufs (-70 to 0 LUFS). Note: volume is not available in streaming mode. Also supports `remove_silence_ms` (integer, 0–1000 ms) for silence removal. - `audio_pitch` integer: Adjusts 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_tempo` number: Controls 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) - `target_lufs` number, nullable: Sets the target absolute loudness (LUFS) for streaming output audio. This normalizes generated audio to a consistent loudness regardless of the original source. Cannot be used with the `volume` parameter. Recommended values: -14 (common streaming standard), -23 (broadcast standard). - `audio_format` 'wav' | 'mp3': Output audio format for streaming. **WAV format:** - Uncompressed PCM audio - 16-bit depth, mono channel, **32000 Hz** sample rate - Chunked transfer: first chunk contains the WAV header (size = 0xFFFFFFFF), subsequent chunks contain raw PCM data - Recommended when you want to play audio as it arrives **MP3 format:** - Compressed MPEG Layer III audio - 320 kbps bitrate, 44100 Hz sample rate - Chunked transfer: each chunk contains independently decodable MPEG frames - Recommended for bandwidth-constrained clients - `remove_silence_ms` integer, nullable: When enabled, shortens detected silences longer than the specified duration to that duration. The value is in milliseconds (ms). The value is the duration of silence to retain, not the amount to remove. **Accepted values:** - An integer from **0 to 1000**, with a recommended range of 0 to 200. - Omitted or `null`: silence removal is disabled. - `0`: removes detected silence longer than 0 ms. **This does not disable the feature.** - Booleans, strings, fractional values, and out-of-range values are invalid. **Example:** `100` shortens detected silences longer than 100 ms to 100 ms. Lower values include shorter silence segments for removal and leave less silence in each affected segment. - `prompt` union: Emotion 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 - SmartPrompt: Emotion and style settings for the generated speech. - `next_text` string: Text 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` - Maximum 2000 characters - Helps the model anticipate emotional transitions - Leave empty if no following context is available - `emotion_type` 'smart': Discriminator field to identify the prompt type. Must be set to "smart" for context-aware emotion inference. - `previous_text` string: Text 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` - Maximum 2000 characters - Helps the model understand emotional build-up and context - Leave empty if no preceding context is available - PresetPrompt: Emotion and style settings for the generated speech. - `emotion_type` 'preset': Discriminator field to identify the prompt type. Must be set to "preset" for preset-based emotion control. - `emotion_preset` 'normal' | 'sad' | 'happy' | 'angry' | 'whisper' | 'toneup' | 'tonedown': Available emotion presets for speech synthesis. Each emotion affects the tone, pace, and expressiveness of the generated speech. **ssfm-v21 Supported Emotions (4 types):** - normal: Neutral, balanced tone - happy: Bright, cheerful expression - sad: Melancholic, subdued tone - angry: Strong, intense delivery **ssfm-v30 Supported Emotions (7 types):** - normal: Neutral, balanced tone - happy: Bright, cheerful expression - sad: Melancholic, subdued tone - angry: Strong, intense delivery - whisper: Soft, quiet speech - toneup: Higher tonal emphasis - tonedown: Lower tonal emphasis Check available emotions for each voice in the `models` field of the `GET /v3/voices` API response. - `emotion_intensity` number: Controls the strength of emotional expression in the generated speech. - 0.0: Completely neutral, no emotional coloring - 0.5: Subtle emotional hints - 1.0: Standard emotional expression (default) - 1.5: Strong emotional emphasis - 2.0: Maximum intensity, highly expressive - Prompt: Emotion and style settings for the generated speech. - `emotion_preset` string: Emotion preset to apply. Supported emotions for ssfm-v21: normal, happy, sad, angry Check available emotions for each voice in the `models` field of the `GET /v3/voices` API response. - `emotion_intensity` unknown - `language` string: 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.
ssfm-v30 Supported Languages (37) | 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 | | | | |
ssfm-v21 Supported Languages (27) | 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 |
- `voice_id` string, required: Voice identifier. Two prefixes are supported: * `tc_` — Built-in Typecast voices (e.g., `tc_60e5426de8b95f1d3000d7b5`). See [Listing all voices](/docs/api-reference/voices/list-voices) for available IDs. * `uc_` — Custom voices created via [Instant cloning](/docs/api-reference/voices/instant-cloning) (e.g., `uc_64a1b2c3d4e5f6a7b8c9d0e1`). Only the owner of a cloned voice can use it. Case-sensitive: must use lowercase prefix. ## Response `200` Success - Returns streaming audio data in chunks ## Other responses - `400`: Bad Request - Invalid parameters - `401`: Unauthorized - Authentication failed - `402`: Payment Required - Insufficient credits - `404`: Not Found - Voice model not available - `422`: Validation Error - The request is invalid or the input text cannot be synthesized. Input errors detected before streaming starts return `TEXT_NOT_SYNTHESIZABLE`. After the streaming response has started, its HTTP status can no longer be changed. - `429`: Too Many Requests - Rate limit exceeded - `500`: Internal Server Error - Server processing failed --- [API](https://skmtc.dev/typecast/apis/typecast-api.md) · [All operations](https://skmtc.dev/typecast/apis/typecast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/typecast/apis/typecast-api/revisions/41605154de82?raw)