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

# List voices

> List all available voices based on the provided filter.
> 
> > **⚠️ Deprecation Notice**: This endpoint is deprecated and may be removed in a future release. Use the [Voices API's List Voices](../../../api-reference/voiceAPI/voiceservice/list-voices) instead for new features and better performance.


## API reference

**Endpoint:** `GET https://api.inworld.ai/tts/v1/voices`

### Authorization

- `Authorization` (string; required) — Your [authentication](../../../api-reference/introduction) credentials. For Basic authentication, please populate `Basic $INWORLD_API_KEY`. You can create a key in one command with the [Inworld CLI](../../../developer-tools/inworld-cli): `inworld workspace add-key`.

### Query parameters

- `filter` (string) — A filter expression to filter the voices. Currently, only the following filter is supported:
  - `language`: Expects an ISO 639-1 language code. For example, `language=en`.

### Response

Status: `200`. Content type: `application/json`.

- `voices` (object[]) — The list of voices.
  - `languages` (string[]) — The language of the original voice audio. 
    
    Speech synthesis will work best when the text matches the language of the original voice audio.
  - `voiceId` (string) — The ID of the voice.
  - `displayName` (string) — The display name of the voice.
  - `description` (string) — The description of the voice.
  - `tags` (string[]) — Tags associated with the voice.
  - `isCustom` (boolean) — Whether this voice is a custom voice created in your workspace (for example, a cloned voice).

### Response examples

#### 200: successful_response

```json
{
  "voices": [
    {
      "languages": [
        "en"
      ],
      "voiceId": "Alex",
      "displayName": "Alex",
      "isCustom": false,
      "description": "Energetic and expressive mid-range male voice, with a mildly nasal quality",
      "tags": [
        "male",
        "energetic",
        "expressive",
        "mid-range"
      ]
    },
    {
      "languages": [
        "en"
      ],
      "voiceId": "Ashley",
      "displayName": "Ashley",
      "isCustom": false,
      "description": "A warm, natural female voice",
      "tags": [
        "female",
        "warm",
        "natural"
      ]
    },
    {
      "languages": [
        "en"
      ],
      "voiceId": "Dennis",
      "displayName": "Dennis",
      "isCustom": false,
      "description": "Middle-aged man with a smooth, calm and friendly voice",
      "tags": [
        "male",
        "middle-aged",
        "smooth",
        "calm",
        "friendly"
      ]
    }
  ]
}
```

#### 4XX: default_response

```json
{
  "code": 3,
  "message": "Invalid language code: 'English'. Must be a 2-letter ISO 639-1 code (e.g., 'en', 'es', 'fr')",
  "details": []
}
```

### Code examples

#### cURL

```bash
curl --location 'https://api.inworld.ai/tts/v1/voices?filter=language%3Den' \
--header "Authorization: Basic $INWORLD_API_KEY"
```

#### Python

```python
import requests

url = "https://api.inworld.ai/tts/v1/voices"
headers = {
    "Authorization": "Basic <api-key>"
}
params = {
    "filter": "language=en"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

#### JavaScript

```javascript
const url = 'https://api.inworld.ai/tts/v1/voices?filter=language%3Den';

const response = await fetch(url, {
  headers: {
    'Authorization': 'Basic <api-key>',
  },
});

const data = await response.json();
console.log(data);
```

#### Inworld CLI

```bash
inworld tts list-voices --json
```