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

# Voices

# Voices

Manage voice configurations and imports from providers (e.g. ElevenLabs). Voices are assigned to agents and determine how the agent sounds on calls.

For UUID / phone / datetime formats used below, see [Data formats](/api-reference/introduction#data-formats).

## List Voices

<Endpoint method="GET" path="/api/public/v1/voices" />

Returns all voices available to your organization (both system voices and custom/cloned voices).

### cURL

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/voices" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

`data` (array of voice objects), `meta`.

```json theme={null}
{
  "data": [
    {
      "id": "a7f2ec82-f533-4f41-a8de-0e4351bd2ec5",
      "name": "Support Voice",
      "provider": "elevenlabs",
      "type": "reference",
      "language": "en-US",
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "request_id": "f98eb11f-9f34-4d13-9075-0e29f106f37d",
    "ts": "2024-01-01T00:00:00Z"
  }
}
```

## Get Voice

<Endpoint method="GET" path="/api/public/v1/voices/{voice_id}" />

### cURL

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/voices/a7f2ec82-f533-4f41-a8de-0e4351bd2ec5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Import Voice from Provider

<Endpoint method="POST" path="/api/public/v1/voices" />

Import an existing voice from ElevenLabs (or another provider) into your organization. Use this when you already have a voice ID from a provider and want to use it with your agents.

### Request Body

| Field               | Type   | Required | Description                                                |
| ------------------- | ------ | -------- | ---------------------------------------------------------- |
| `name`              | string | Yes      | Display name for the voice in your dashboard               |
| `provider`          | string | No       | Voice provider. Default: `elevenlabs`                      |
| `provider_voice_id` | string | Yes      | The voice ID from your provider (e.g. ElevenLabs voice ID) |

### Example

```json theme={null}
{
  "name": "Support Voice",
  "provider": "elevenlabs",
  "provider_voice_id": "21m00Tcm4TlvDq8ikWAM"
}
```

### cURL

```bash theme={null}
curl -X POST "https://api.truedy.ai/api/public/v1/voices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Voice",
    "provider": "elevenlabs",
    "provider_voice_id": "21m00Tcm4TlvDq8ikWAM"
  }'
```

**Response:** 201 Created with `data` (voice object) and `meta`. May return **422** or **502** if the provider rejects the request (e.g. invalid voice ID or quota exceeded).

## Clone Voice from Audio

<Endpoint method="POST" path="/api/public/v1/voices/clone" />

Create a voice clone from your own audio samples. Upload one or more audio files (base64-encoded), and the system will clone the voice via ElevenLabs and import it to Ultravox for use with agents. **Requires credits on your account.**

### Request Body

| Field                  | Type      | Required | Description                                                                                       |
| ---------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------- |
| `name`                 | string    | Yes      | Display name for the cloned voice (max 40 characters)                                             |
| `files`                | object\[] | Yes      | One or more audio files. Each file is `{ filename, data, content_type }`                          |
| `files[].filename`     | string    | Yes      | File name including extension (e.g. `sample.mp3`)                                                 |
| `files[].data`         | string    | Yes      | Base64-encoded audio file content                                                                 |
| `files[].content_type` | string    | No       | MIME type. Default: `audio/mpeg`. Supports: `audio/mpeg`, `audio/wav`, `audio/mp4`, `audio/x-m4a` |

**Tips for best results:**

* Use 1–5 minutes of clear, noise-free audio
* Avoid music or background noise
* MP3 or WAV at 44.1kHz works best

### Example

```json theme={null}
{
  "name": "My Custom Voice",
  "files": [
    {
      "filename": "sample.mp3",
      "data": "<base64-encoded audio bytes>",
      "content_type": "audio/mpeg"
    }
  ]
}
```

### cURL

```bash theme={null}
# Encode your audio file to base64 first:
# base64 -i sample.mp3 > sample_b64.txt

curl -X POST "https://api.truedy.ai/api/public/v1/voices/clone" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Voice",
    "files": [
      {
        "filename": "sample.mp3",
        "data": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAAAAAAAAAAAAAA...",
        "content_type": "audio/mpeg"
      }
    ]
  }'
```

**Response:** 201 Created with `data` (voice object with `status: "active"`) and `meta`. The voice is immediately ready for use. Returns **422** if name exceeds 40 characters or no files are provided. Returns **402** if your account lacks sufficient credits.

## Update Voice

<Endpoint method="PATCH" path="/api/public/v1/voices/{voice_id}" />

Update the display name of a voice. The `name` is passed as a **query parameter**.

### Parameters

**Query parameters:**

| Parameter | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| `name`    | string | Yes      | New display name for the voice |

### cURL

```bash theme={null}
curl -X PATCH "https://api.truedy.ai/api/public/v1/voices/a7f2ec82-f533-4f41-a8de-0e4351bd2ec5?name=Support+Voice+V2" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Delete Voice

<Endpoint method="DELETE" path="/api/public/v1/voices/{voice_id}" />

Deletes the voice from your organization. Agents using this voice will need to be updated.

### cURL

```bash theme={null}
curl -X DELETE "https://api.truedy.ai/api/public/v1/voices/a7f2ec82-f533-4f41-a8de-0e4351bd2ec5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Sync Voice

<Endpoint method="POST" path="/api/public/v1/voices/{voice_id}/sync" />

Re-syncs a voice with Ultravox (the underlying AI platform). Use this if a voice shows as inactive or if you encounter sync errors. May return **422** if the sync fails (e.g. provider error).

### cURL

```bash theme={null}
curl -X POST "https://api.truedy.ai/api/public/v1/voices/a7f2ec82-f533-4f41-a8de-0e4351bd2ec5/sync" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Preview Voice

<Endpoint method="GET" path="/api/public/v1/voices/{voice_id}/preview" />

Generate a short audio preview of the voice speaking a given text. Returns raw WAV audio bytes.

### Parameters

**Query parameters:**

| Parameter | Type   | Description                                                              |
| --------- | ------ | ------------------------------------------------------------------------ |
| `text`    | string | Text for the voice to speak. Defaults to a standard greeting if omitted. |

### cURL

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/voices/a7f2ec82-f533-4f41-a8de-0e4351bd2ec5/preview?text=Hello%20from%20Truedy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o preview.wav
```

Returns raw WAV audio. May return **422** or **502** if the provider fails.

## Voice Object

| Field        | Type     | Description                                         |
| ------------ | -------- | --------------------------------------------------- |
| `id`         | UUID     | Voice ID                                            |
| `name`       | string   | Display name                                        |
| `provider`   | string   | Provider: `elevenlabs`, `google`, `azure`, `openai` |
| `type`       | string   | `reference` (imported) or `custom` (cloned)         |
| `language`   | string   | Language code (e.g. `en-US`)                        |
| `status`     | string   | `active`, `training`, or `failed`                   |
| `created_at` | datetime | When the voice was added                            |
| `updated_at` | datetime | Last updated                                        |