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

# Voices

> List, inspect, clone, and delete the voices used by the Text to Speech API.

A **voice** is the speaker used by the [Text to Speech](/docs/text-to-speech) API. You can list the
voices available to your account, retrieve a single one, clone your own from audio samples, and
delete clones you've created.

## Authentication

All Speech endpoints are served from `https://platform.perso.ai` and authenticate with your API
key. Send it as either header:

* `PersoPlatform-APIKey: <YOUR-KEY>` — the standard Perso Platform key.
* `xi-api-key: <YOUR-KEY>` — the same key, for ElevenLabs-compatible SDKs.

## List voices

```shellscript theme={null}
curl 'https://platform.perso.ai/api/speech/v2/voices' \
  -H 'PersoPlatform-APIKey: <YOUR-KEY>'
```

The response is paginated:

```json theme={null}
{
  "voices": [
    { "voice_id": "...", "name": "...", "...": "..." }
  ],
  "has_more": false,
  "total_count": 12,
  "next_page_token": null
}
```

Refine the list with query parameters: `search`, `voice_ids`, `sort`, `sort_direction`,
`page_size`, `next_page_token`, and `include_total_count`.

## Retrieve a voice

```shellscript theme={null}
curl 'https://platform.perso.ai/api/speech/v1/voices/<VOICE_ID>' \
  -H 'PersoPlatform-APIKey: <YOUR-KEY>'
```

## Clone a voice

Create a new voice from one or more audio samples. Cloning is asynchronous — the request returns
`202 Accepted` and the voice becomes usable once processing finishes.

```shellscript theme={null}
curl -X POST 'https://platform.perso.ai/api/speech/v1/voices/add' \
  -H 'PersoPlatform-APIKey: <YOUR-KEY>' \
  -F 'name=My Narrator' \
  -F 'files=@sample1.wav' \
  -F 'files=@sample2.wav' \
  -F 'remove_background_noise=true'
```

| Field                     | Required | Description                                             |
| ------------------------- | -------- | ------------------------------------------------------- |
| `name`                    | yes      | Display name for the voice.                             |
| `files`                   | yes      | One or more audio sample files to clone from.           |
| `description`             | no       | Optional notes about the voice.                         |
| `remove_background_noise` | no       | Denoise the samples before training (default `false`).  |
| `prompt_text`             | no       | Transcript of the sample audio; improves clone quality. |

## Delete a voice

```shellscript theme={null}
curl -X DELETE 'https://platform.perso.ai/api/speech/v1/voices/<VOICE_ID>' \
  -H 'PersoPlatform-APIKey: <YOUR-KEY>'
```

<Note>
  For full request and response schemas, see the endpoints under the **Speech API** tab.
</Note>