---
title: "Compose Text To Speech"
method: POST
path: "/v1/text-to-speech/compose"
tags: ["Text-to-Speech"]
---

# Compose Text To Speech

`POST /v1/text-to-speech/compose`

## Request

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

Generate multiple speech segments and pauses as one audio file. Add `tts` and `pause` objects to `segments` in the order they should appear. Each `tts` segment accepts the same voice, model, prompt, and output settings as `POST /v1/text-to-speech`; voices and models may differ between segments.

**Limits**
- Up to 50 total segments, with at least one `tts` segment
- Up to 2,000 characters across all `tts` segments
- Up to 10 seconds per pause and 60 seconds across all pauses
- All `tts` segments must use the same `audio_format`

Credits are charged only for the combined text length; pauses are free. Segments are synthesized in parallel and returned in input order. If any segment fails, the entire request fails and no credits are charged.

**Response**
A successful request returns the composed audio directly as binary data, not JSON. The response `Content-Type` is `audio/wav` or `audio/mpeg`, based on the `audio_format` requested by the segments.

## Request body

- object: A sequence of speech and pause segments returned as one audio file.
  - `segments` union[], required: Speech and pause segments in output order. Provide 1–50 segments with at least one `tts` segment.
    - union
      - object: A speech segment with the same synthesis options as a standard text-to-speech request.
        - `text` string, required: Text to synthesize. The combined text across all `tts` segments may not exceed 2,000 characters.
        - `type` 'tts', required: Segment discriminator. Always `tts`.
        - `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: Audio settings for this segment. All segments must use the same `audio_format`. Use `remove_silence_ms` (integer, 0–1000 ms) to shorten detected silence.
          - `volume` integer, nullable: Adjusts 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. - **Note:** This parameter cannot be used simultaneously with the `target_lufs` parameter. Required range: 0 <= x <= 200
          - `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 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. - Required range: -70 <= x <= 0 - Recommended values: -14 (common streaming standard), -23 (broadcast standard) - **Note:** This parameter cannot be used simultaneously with the `volume` parameter. Use `target_lufs` for consistent absolute loudness across different clips, or use `volume` for traditional relative scaling.
          - `audio_format` 'wav' | 'mp3': Output audio format. **WAV format:** - Uncompressed PCM audio - 16-bit depth, mono channel, 44100 Hz sample rate - Higher quality, larger file size - Recommended for professional audio production **MP3 format:** - Compressed MPEG Layer III audio - 320 kbps bitrate, 44100 Hz sample rate - Smaller file size - Recommended for web streaming and distribution
          - `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 context settings for this segment.
          - 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: ISO 639-3 language code. If omitted, the language is detected from the text.
        - `voice_id` string, required: Built-in (`tc_`) or custom (`uc_`) Typecast voice identifier.
      - PauseComposeSegment: A silent interval inserted without consuming credits.
        - `type` 'pause', required: Segment discriminator. Always `pause`.
        - `duration_seconds` number, required: Pause duration in seconds. Each pause may be up to 10 seconds; all pauses combined may be up to 60 seconds.

## Response `200`

Binary composed audio. The media type matches the requested `audio_format`.

## Other responses

- `401`: Unauthorized - Authentication failed
- `402`: Insufficient credits for the combined text length
- `422`: Invalid segments, compose limits exceeded, or input text cannot be synthesized
- `500`: Unexpected server error while synthesizing one or more segments

---

[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)