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

# Voices

> List the Plivo Text-to-Speech voices available to your account, or retrieve one voice.

> [!NOTE]
>
> List every voice your account can use, or retrieve one by `voice_id`. Pass the `voice_id` when you generate speech.

A `Voice` object describes one voice. Pass its `voice_id` when you use [batch](https://plivo.com/docs/models/text-to-speech/api/batch.md) or open a [realtime](https://plivo.com/docs/models/text-to-speech/api/realtime.md) reply. See [Voices and languages](https://plivo.com/docs/models/text-to-speech/concepts/voices.md) for the full catalog.

## The Voice Object

### Attributes

**voice\_id** `string`

Unique identifier for the voice.

**name** `string`

Display name.

**gender** `string`

Values: `male`, `female`.

**languages** `array`

Language codes the voice speaks, for example `["en-US"]` or `["hi"]`. Each voice speaks one language today.

**accent\_type** `string`

The voice's accent: `American`, `British`, `Australian` or `Indian`.

**description** `string`

A short description of the voice.

**lexicon** `boolean`

Whether the voice supports [custom pronunciations](https://plivo.com/docs/models/text-to-speech/concepts/pronunciation.md): inline `pronunciations` or a saved lexicon passed as `lexicon_id`. Which rule kinds it accepts (`ipa`, `arpa`, `respell`) depends on the voice; a kind it doesn't take returns `invalid_request`.

**sample\_url** `string`

URL of a short audio sample of the voice.

### Example Voice Object

```json theme={null}
{
  "voice_id": "6uWzc4xFj31t4jNJUaED",
  "name": "Meera",
  "gender": "female",
  "languages": ["hi"],
  "accent_type": "Indian",
  "description": "Female Indian voice. Speaks Hindi.",
  "lexicon": true,
  "sample_url": "https://..."
}
```

***

## List All Voices

List the voices your account can use.

```text theme={null}
GET https://api.plivo.com/v1/Account/{auth_id}/TTS/Voices/
```

### Arguments

No arguments. Query parameters aren't accepted: one returns `422 invalid_request` naming it.

```bash cURL theme={null}
curl "https://api.plivo.com/v1/Account/<auth_id>/TTS/Voices/" \
  -u '<auth_id>:<auth_token>'
```

### Response

**api\_id** `string`

Unique identifier for the request.

**meta** `object`

`limit`, `offset`, `total_count`, `next` and `previous`. All voices come back in one page.

**objects** `array`

[Voice objects](#the-voice-object).

```json theme={null}
{
  "api_id": "148d6af0bee98c09",
  "meta": {"limit": 33, "next": null, "offset": 0, "previous": null, "total_count": 33},
  "objects": [
    {"voice_id": "6uWzc4xFj31t4jNJUaED", "name": "Meera", "gender": "female", "languages": ["hi"], "accent_type": "Indian", "description": "Female Indian voice. Speaks Hindi.", "lexicon": true, "sample_url": "https://..."},
    {"voice_id": "lC7qzMoRE7SSjaNCVeff", "name": "Hailey", "gender": "female", "languages": ["en-US"], "accent_type": "American", "description": "Female voice with an American accent. Speaks English.", "lexicon": true, "sample_url": "https://..."}
  ]
}
```

***

## Retrieve a Voice

Get one voice by its `voice_id`.

```text theme={null}
GET https://api.plivo.com/v1/Account/{auth_id}/TTS/Voices/{voice_id}/
```

### Arguments

No arguments. A `voice_id` that isn't in your list returns `404 voice_not_found`.

```bash cURL theme={null}
curl "https://api.plivo.com/v1/Account/<auth_id>/TTS/Voices/<voice_id>/" \
  -u '<auth_id>:<auth_token>'
```

### Response

The [Voice object](#the-voice-object), with the request's `api_id`.

```json theme={null}
{
  "api_id": "148d6af0bee98c09",
  "voice_id": "6uWzc4xFj31t4jNJUaED",
  "name": "Meera",
  "gender": "female",
  "languages": ["hi"],
  "accent_type": "Indian",
  "description": "Female Indian voice. Speaks Hindi.",
  "lexicon": true,
  "sample_url": "https://..."
}
```
