> ## Documentation Index > Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Compose Text To Speech > 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. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/text-to-speech/compose openapi: 3.1.0 info: title: Typecast API version: 0.1.2 x-logo: url: https://typecast.ai/docs/logo/light.svg servers: - url: https://api.typecast.ai description: Production server security: - ApiKeyAuth: [] paths: /v1/text-to-speech/compose: post: tags: - Text-to-Speech summary: Compose Text To Speech description: >- 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. operationId: text_to_speech_compose_v1_text_to_speech_compose_post requestBody: content: application/json: schema: $ref: '#/components/schemas/ComposeRequest' example: segments: - type: tts voice_id: tc_672c5f5ce59fac2a48faeaee text: Welcome to today's update. model: ssfm-v30 language: eng output: audio_format: wav - type: pause duration_seconds: 1.5 - type: tts voice_id: tc_66aca22c7d31e45ff05ff418 text: Here is the first story. model: ssfm-v30 language: eng output: audio_format: wav required: true responses: '200': description: >- Binary composed audio. The media type matches the requested `audio_format`. content: audio/wav: schema: type: string format: binary example: '[Binary audio data - WAV file content]' audio/mpeg: schema: type: string format: binary example: '[Binary audio data - MP3 file content]' '401': description: Unauthorized - Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Invalid API key '402': description: Insufficient credits for the combined text length content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Insufficient credit '422': description: Invalid segments or compose limits exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Invalid request format '500': description: One or more segments failed to synthesize content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: An unexpected error occurred x-codeSamples: - lang: cURL label: cURL (save to file) source: | curl --request POST \ --url https://api.typecast.ai/v1/text-to-speech/compose \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: ' \ --output output.wav \ --data @- <"}, json={ "segments": [ { "type": "tts", "voice_id": "tc_672c5f5ce59fac2a48faeaee", "text": "Welcome to today's update.", "model": "ssfm-v30", "language": "eng", "output": {"audio_format": "wav"}, }, {"type": "pause", "duration_seconds": 1.5}, { "type": "tts", "voice_id": "tc_66aca22c7d31e45ff05ff418", "text": "Here is the first story.", "model": "ssfm-v30", "language": "eng", "output": {"audio_format": "wav"}, }, ] }, timeout=120, ) response.raise_for_status() with open("output.wav", "wb") as audio_file: audio_file.write(response.content) components: schemas: ComposeRequest: type: object properties: segments: type: array items: oneOf: - $ref: '#/components/schemas/TTSComposeSegment' - $ref: '#/components/schemas/PauseComposeSegment' discriminator: propertyName: type mapping: pause: $ref: '#/components/schemas/PauseComposeSegment' tts: $ref: '#/components/schemas/TTSComposeSegment' title: Segments description: >- Speech and pause segments in output order. Provide 1–50 segments with at least one `tts` segment. minItems: 1 maxItems: 50 required: - segments title: ComposeRequest description: A sequence of speech and pause segments returned as one audio file. ErrorResponse: type: object properties: detail: type: string description: Error message describing the issue required: - detail example: detail: An error occurred processing the request TTSComposeSegment: type: object properties: voice_id: type: string title: Voice Id description: Built-in (`tc_`) or custom (`uc_`) Typecast voice identifier. example: tc_672c5f5ce59fac2a48faeaee text: type: string title: Text description: >- Text to synthesize. The combined text across all `tts` segments may not exceed 2,000 characters. example: Welcome to today's update. maxLength: 2000 minLength: 1 model: $ref: '#/components/schemas/TTSModel' description: >- Voice model used for this segment. Models may differ between segments. example: ssfm-v30 language: type: string title: Language description: >- ISO 639-3 language code. If omitted, the language is detected from the text. example: eng prompt: title: Prompt description: Emotion and context settings for this segment. oneOf: - $ref: '#/components/schemas/SmartPrompt' - $ref: '#/components/schemas/PresetPrompt' - $ref: '#/components/schemas/Prompt' output: $ref: '#/components/schemas/Output' description: >- Audio settings for this segment. All segments must use the same `audio_format`. seed: title: Seed description: Optional unsigned integer seed for reproducible synthesis. example: 42 anyOf: - type: integer maximum: 4294967295 minimum: 0 - type: 'null' type: type: string title: Type description: Segment discriminator. Always `tts`. default: tts const: tts required: - type - voice_id - text - model title: TTSComposeSegment description: >- A speech segment with the same synthesis options as a standard text-to-speech request. examples: - type: tts voice_id: tc_672c5f5ce59fac2a48faeaee text: Welcome to today's update. model: ssfm-v30 language: eng output: audio_format: wav PauseComposeSegment: type: object properties: type: type: string title: Type description: Segment discriminator. Always `pause`. default: pause const: pause duration_seconds: type: number maximum: 10 title: Duration Seconds description: >- Pause duration in seconds. Each pause may be up to 10 seconds; all pauses combined may be up to 60 seconds. example: 1.5 exclusiveMinimum: 0 required: - type - duration_seconds title: PauseComposeSegment description: A silent interval inserted without consuming credits. additionalProperties: false examples: - type: pause duration_seconds: 1.5 TTSModel: type: string enum: - ssfm-v30 - ssfm-v21 title: TTSModel description: > 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 SmartPrompt: type: object properties: emotion_type: type: string title: Emotion Type description: > Discriminator field to identify the prompt type. Must be set to "smart" for context-aware emotion inference. default: smart const: smart previous_text: type: string title: Previous Text description: > 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 default: '' example: I feel like I'm walking on air and I just want to scream with joy! next_text: type: string title: Next Text description: > 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 default: '' example: >- I am literally bursting with happiness and I never want this feeling to end! title: SmartPrompt (ssfm-v30) description: Emotion and style settings for the generated speech. example: emotion_type: smart previous_text: I feel like I'm walking on air and I just want to scream with joy! next_text: >- I am literally bursting with happiness and I never want this feeling to end! additionalProperties: false PresetPrompt: type: object properties: emotion_type: type: string title: Emotion Type description: > Discriminator field to identify the prompt type. Must be set to "preset" for preset-based emotion control. default: preset const: preset emotion_preset: $ref: '#/components/schemas/EmotionEnum' description: > Emotion 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. default: normal example: normal emotion_intensity: type: number maximum: 2 minimum: 0 title: Emotion Intensity description: > 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 default: 1 example: 1 title: PresetPrompt (ssfm-v30) description: Emotion and style settings for the generated speech. additionalProperties: false Prompt: properties: emotion_preset: description: | Emotion preset to apply. Supported emotions for ssfm-v21: normal, happy, sad, angry Check available emotions for each voice through the /v2/voices API. example: normal emotion_intensity: description: | Controls the strength of emotional expression (0.0 to 2.0). - 0.0: Completely neutral - 1.0: Standard expression (default) - 2.0: Maximum intensity example: 1 title: Prompt (ssfm-v21) description: Emotion and style settings for the generated speech. Output: type: object properties: target_lufs: type: number title: Target Lufs description: > 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. example: -14 anyOf: - type: number maximum: 0 minimum: -70 - type: 'null' volume: title: Volume description: > 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 example: 100 anyOf: - type: integer maximum: 200 minimum: 0 - type: 'null' audio_pitch: type: integer maximum: 12 minimum: -12 title: Audio Pitch description: >- 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) default: 0 example: 0 audio_tempo: type: number maximum: 2 minimum: 0.5 title: Audio Tempo description: >- 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) default: 1 example: 1 audio_format: type: string enum: - wav - mp3 title: Audio Format description: | 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 default: wav example: wav title: Output description: Audio output settings for controlling the final audio characteristics EmotionEnum: type: string enum: - normal - sad - happy - angry - whisper - toneup - tonedown title: EmotionEnum description: > 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 through the /v2/voices API response. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: >- API key for authentication. You can obtain an API key from the Typecast API Console. ````