> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifically.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Text-to-Speech

> Generate speech with ElevenLabs TTS, including custom cloned voices and timestamps

Generate high-quality speech audio from text using ElevenLabs models — with premade voices, your own custom cloned voices, or one-off voice cloning from sample URLs.

## Model

```
elevenlabs/text-to-speech
```

## Parameters

| Parameter         | Type            | Required | Default             | Description                                                                                |
| ----------------- | --------------- | -------- | ------------------- | ------------------------------------------------------------------------------------------ |
| `text`            | string          | Yes      | -                   | Text to convert to speech. Character limits depend on `model_id` (see models below)        |
| `voice`           | string or array | Yes      | -                   | Voice to use — see [Voice Options](#voice-options)                                         |
| `model_id`        | string          | No       | `eleven_flash_v2_5` | TTS model (see models below)                                                               |
| `with_timestamps` | boolean         | No       | `false`             | Return character/word timing data alongside the audio                                      |
| `speed`           | number          | No       | `1.0`               | Speech speed. Below `1.0` slower, above `1.0` faster. Shorthand for `voice_settings.speed` |
| `voice_settings`  | object          | No       | -                   | Fine-tune voice behavior (see below)                                                       |
| `output_format`   | string          | No       | `mp3_44100_128`     | Audio output format (see formats below)                                                    |
| `language_code`   | string          | No       | `auto`              | ISO 639-1 language code to force language (e.g. `en`, `es`)                                |
| `seed`            | integer         | No       | -                   | Seed for reproducible generation (0–4294967295)                                            |

## Voice Options

The `voice` parameter accepts two forms:

| Form        | Example                                               | Meaning                                                                                                                                             |
| ----------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Voice ID    | `"voice": "21m00Tcm4TlvDq8ikWAM"`                     | A premade voice (from [`GET /v1/resources/elevenlabs/voices`](/api-reference/resources)) or a custom `voice_id` you created. Both work identically. |
| Sample URLs | `"voice": ["https://.../a.mp3", "https://.../b.mp3"]` | One-off clone for this request only; nothing is stored. Same rules as custom-voice samples.                                                         |

### Custom Voices

Clone a voice from sample recordings and get back a permanent `voice_id`:

```
POST /v1/resources/elevenlabs/voices
```

| Field     | Type             | Required | Description                                                                                                                             |
| --------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `samples` | array of strings | Yes      | URLs of audio recordings of **one speaker**. More recordings of the same person produce a better voice. Max 25 samples, max 25 MB each. |
| `name`    | string           | No       | A label for your own reference. Not an identifier.                                                                                      |

```bash theme={null}
curl -X POST https://api.unifically.com/v1/resources/elevenlabs/voices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "samples": [
      "https://cdn.example.com/recording1.mp3",
      "https://cdn.example.com/recording2.wav"
    ],
    "name": "Podcast Talker"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "voice_id": "NLQzxuY9B0rsgFcPKVW4",
    "name": "Podcast Talker",
    "samples": ["https://cdn.example.com/recording1.mp3", "https://cdn.example.com/recording2.wav"]
  }
}
```

<Warning>
  **Store the `voice_id`.** It is returned only once — there is no endpoint that lists custom voices, by design (voice IDs are private to whoever holds them).
</Warning>

* The voice is **permanent**: we keep our own copy of your samples, so it keeps working even after your original URLs go offline.
* Sample URLs must be **direct downloads** — redirects and link shorteners are rejected.
* Supported audio formats: mp3, wav, ogg, opus, m4a, flac, webm.
* Voice IDs from your own ElevenLabs account cannot be used here — create the voice through this endpoint instead.

### voice\_settings

| Field               | Type    | Default | Description                                                          |
| ------------------- | ------- | ------- | -------------------------------------------------------------------- |
| `stability`         | number  | `0.5`   | 0–1. Lower = more expressive/variable, higher = more monotone        |
| `similarity_boost`  | number  | `0.75`  | 0–1. How closely the output adheres to the original voice            |
| `style`             | number  | `0`     | 0–1. Style exaggeration. Values other than 0 may add latency         |
| `speed`             | number  | `1.0`   | Speech speed multiplier. Wins over top-level `speed` if both are set |
| `use_speaker_boost` | boolean | `true`  | Boost similarity to the original speaker                             |

## Available Models

| Model                    | Description                                                | Languages | Char Limit |
| ------------------------ | ---------------------------------------------------------- | --------- | ---------- |
| `eleven_flash_v2_5`      | Default. Fastest and cheapest                              | 32        | 40,000     |
| `eleven_multilingual_v2` | Highest quality, most stable on long-form                  | 29        | 10,000     |
| `eleven_v3`              | Most expressive                                            | 70+       | 5,000      |
| `eleven_turbo_v2_5`      | Deprecated by ElevenLabs — use `eleven_flash_v2_5` instead | 32        | 40,000     |

## Output Formats

| Format           | Description                   |
| ---------------- | ----------------------------- |
| `mp3_22050_32`   | MP3 22.05kHz 32kbps           |
| `mp3_44100_64`   | MP3 44.1kHz 64kbps            |
| `mp3_44100_96`   | MP3 44.1kHz 96kbps            |
| `mp3_44100_128`  | MP3 44.1kHz 128kbps (default) |
| `mp3_44100_192`  | MP3 44.1kHz 192kbps           |
| `opus_48000_32`  | Opus 48kHz 32kbps             |
| `opus_48000_64`  | Opus 48kHz 64kbps             |
| `opus_48000_96`  | Opus 48kHz 96kbps             |
| `opus_48000_128` | Opus 48kHz 128kbps            |
| `opus_48000_192` | Opus 48kHz 192kbps            |
| `pcm_16000`      | Raw PCM 16kHz                 |
| `pcm_22050`      | Raw PCM 22.05kHz              |
| `pcm_24000`      | Raw PCM 24kHz                 |
| `pcm_44100`      | Raw PCM 44.1kHz               |
| `pcm_48000`      | Raw PCM 48kHz                 |
| `wav_44100`      | WAV 44.1kHz                   |
| `ulaw_8000`      | μ-law 8kHz (Twilio)           |
| `alaw_8000`      | A-law 8kHz                    |

## Resources

Get available premade voices from the [Resources API](/api-reference/resources):

```
GET /v1/resources/elevenlabs/voices
```

## Example — custom voice with timestamps

```bash theme={null}
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "elevenlabs/text-to-speech",
    "input": {
      "text": "Hello world, this is my cloned voice.",
      "voice": "NLQzxuY9B0rsgFcPKVW4",
      "model_id": "eleven_multilingual_v2",
      "with_timestamps": true,
      "speed": 1.1
    }
  }'
```

## Response

```json theme={null}
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "processing"
  }
}
```

## Completed Response

Poll `GET /v1/tasks/{task_id}` until `status` is `completed`:

```json theme={null}
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "completed",
    "output": {
      "audio_url": "https://files.unifically.com/audio/abc123.mp3",
      "alignment": {
        "characters": ["H", "e", "l", "l", "o"],
        "character_start_times_seconds": [0.0, 0.081, 0.15, 0.21, 0.26],
        "character_end_times_seconds": [0.081, 0.15, 0.21, 0.26, 0.32]
      },
      "normalized_alignment": { "...": "same shape, for the spoken (normalized) text" },
      "words": [
        { "word": "Hello", "start": 0.0, "end": 0.32 },
        { "word": "world,", "start": 0.38, "end": 0.79 }
      ]
    }
  }
}
```

* `alignment` maps **your original text**; `normalized_alignment` maps the text as spoken (numbers and abbreviations expanded).
* `words` is derived from `alignment` — use it directly for captions and audio/video sync. Punctuation stays attached to its word.
* Without `with_timestamps`, the output contains only `audio_url`.