> For the full page index, fetch https://echonova.ai/llms.txt

# List available voices

Lists the EchoNova voice library. Send a voice's id as voiceId when you generate speech.

## Endpoint

`GET https://api.echonova.ai/v1/text-to-speech/voices`

## Authentication

Keys are created in the portal under Developers, sent as `Authorization: Bearer YOUR_API_KEY`. See [Get an API key](/docs/developers/get-an-api-key).

## Request

_No parameters._

## Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | OK                    |
| 401    | Unauthorized          |
| 403    | Forbidden             |
| 429    | Too Many Requests     |
| 500    | Internal Server Error |
| 503    | Service Unavailable   |
| 504    | Gateway Timeout       |

## Response

A success answers 200 with the envelope `{ data, success, statusCode, errorMessage }`. The `data` fields:

| Field             | Type             | Description                                                   |
| ----------------- | ---------------- | ------------------------------------------------------------- |
| items             | array of objects | The items on this page.                                       |
| items.id          | string           | The value to send as voiceId.                                 |
| items.name        | string           | Engine identifier, e.g. "ae_ahmed".                           |
| items.displayName | string           | Human label, e.g. "Ahmed". Falls back to name when unset.     |
| items.language    | string           | ar for Arabic voices, en for English voices.                  |
| items.gender      | string           | The gender label, for example Male.                           |
| items.previewUrl  | string           | A link to a short audio sample of the voice, when one exists. |
| total             | number           | The total number of items.                                    |

```json
{
  "data": {
    "items": [
      {
        "id": "66e5ef3a9c1d2b4f8a7e6c01",
        "name": "ae_ahmed",
        "displayName": "Ahmed",
        "language": "ar",
        "gender": "Male",
        "previewUrl": "https://storage.example.com/voices/ae_ahmed-preview.wav"
      }
    ],
    "total": 1
  },
  "success": true,
  "statusCode": 200,
  "errorMessage": null
}
```

## Errors

| Status | errorMessage                                                 | When                                                                                                                                                                                                                                                                                       | Fix                                                                               |
| ------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| 401    | Unauthorized                                                 | The Authorization header is missing or is not Bearer ek\_..., no key matches the token, or the key is deleted, disabled or its account is closed.                                                                                                                                          | Send Authorization: Bearer ek\_... with an enabled key.                           |
| 403    | Subscription not found                                       | The workspace that owns the key has no subscription.                                                                                                                                                                                                                                       | Check the workspace's plan in the portal.                                         |
| 403    | Subscription expired or inactive                             | The subscription is in a state other than active or trial.                                                                                                                                                                                                                                 | Renew the subscription.                                                           |
| 403    | This API key does not have access to Text-to-Speech services | The key is restricted and Text to Speech is not among its services.                                                                                                                                                                                                                        | Edit the key and grant Text to Speech, or use another key.                        |
| 429    | ThrottlerException: Too Many Requests                        | The key made more than 100 requests to one endpoint in 60 seconds, or one IP address made more than 100 requests to one endpoint in 60 seconds (the IP limit is counted before the key is checked, so it can answer with no key at all); a Retry-After header carries the seconds to wait. | Wait Retry-After seconds, then retry.                                             |
| 500    | Something went wrong                                         | An error the API did not classify.                                                                                                                                                                                                                                                         | Check the request, then retry after a short wait; contact support if it persists. |
| 503    | Database unavailable                                         | A transient outage inside the API.                                                                                                                                                                                                                                                         | Retry after a short wait.                                                         |
| 504    | Database timed out                                           | A transient timeout inside the API.                                                                                                                                                                                                                                                        | Retry after a short wait.                                                         |

## Code samples

:::tabs

```bash title="cURL"
curl "https://api.echonova.ai/v1/text-to-speech/voices" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import requests

response = requests.get(
    "https://api.echonova.ai/v1/text-to-speech/voices",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript
const response = await fetch('https://api.echonova.ai/v1/text-to-speech/voices', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
console.log(await response.json());
```

:::