Overview

The Clip Combination Endpoint allows you to merge multiple audio clips into a single file, with optional control over the pause duration between each clip. This is ideal for creating seamless audio content such as podcasts, dialogue scenes, announcements, or long-form narratives.

⚠️ You can combine up to 100 clips in a single request.

How It Works

You can provide:

An array of clip_ids to merge, which can be generated using the Asynchronous Clips Endpoint.
A pause_durations array, the pause duration uses seconds and where:
- A single value applies the same pause between all clips
- An array of values allows you to fine-tune each pause between every clip.

⚠️ The number of pause_durations must equal 1 or be exactly one less than the number of clips.

Examples

Uniform Pauses

If you wanted to provide a uniform pause duration between all clips provided, great for books and long articles, then you can provide a single value in the pause_durationsarray

Example with a cURL

curl --request POST \
     --url https://api.wellsaidlabs.com/v1/tts/clips/combine \
     --header 'content-type: application/json' \
     --data '
{
  "clip_ids": [
    "clip_id_1",
    "clip_id_2",
    "clip_id_3"
  ],
  "pause_durations": 0.8
}'

This applies a 0.8-second pause between each of the three clips.

Custom Pauses

If you wanted to provide a custom pause duration between all clips provided, great for courses or videos where dialogue might not occur for set periods, then you can provide a value for the pause_durations between each clip in the array.

Example with a cURL

curl --request POST \
     --url https://api.wellsaidlabs.com/v1/tts/clips/combine \
     --header 'content-type: application/json' \
     --data '
{
  "clip_ids": [
    "clip_id_1",
    "clip_id_2",
    "clip_id_3"
  ],
  "pause_durations": [0.8, 1.2]
}'

This sets:

0.8s between clip 1 and clip 2
1.2s between clip 2 and clip 3

Best Practices

Use uniform pauses for narration, audiobooks, and uninterrupted speeches
Use varied pauses for dialogue, scenes, or learning modules
Ensure the pause_durations array is either:
- A single number (e.g. 0.5)
- An array of size clip_ids.length - 1
Do not exceed 100 clips in a single combination request