# List voices

> POST /api/v1/voices/ returns the voices an API key can use, with their ids, sample URLs, fees, badges and engine, in the language you choose (English fallback).

## Endpoint

`POST https://moknah.io/api/v1/voices/`

Returns every voice the authenticated key may use. The method is POST; a GET request is answered with `405`.

## Authentication

`Authorization: Bearer YOUR_API_KEY`. Both a dashboard API key and a company key (used by Article to Speech) are accepted.

## Request body

The body is optional.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `engine` | string | no | `standard` or `advanced`. A key lists the voices of its own voice type only, so this field may only repeat the key's type. Any other value, or the other engine, returns `400 INVALID_REQUEST`. |
| `language` | string | no | Language for `voice_name` and the `voice_badges` values, for example `ar`, `fr` or `zh-hans` (regional forms such as `fr-FR` are accepted). Can also be sent as the `?language=` query parameter. Default `en`. |

### Language and fallback

- A voice with no text in the requested language shows its English name and badges. Badge values that are standard terms (gender, age, language, use case) are still translated when we have the term.
- A missing or unsupported code returns English. It is never an error.
- The `Content-Language` response header says which language was used.
- Badge keys (`gender`, `age`, `language`, `tone`, `use_case`) are always English, so you can filter on them in any language.

## Response

`200` with a JSON array. Each item:

| Field | Type | Description |
| --- | --- | --- |
| `voice_id` | integer | Id to pass as `voice_id` to text to speech. |
| `voice_name` | string | Display name. |
| `voice_sample_url` | string or null | URL of a sample clip. |
| `voice_fees` | number | Fee of the voice. `0` means the voice adds no surcharge. See [Pricing](../pricing/index.md). |
| `voice_badges` | object | Descriptive metadata such as language, gender, age and use case. Keys vary by voice. |
| `voice_engine` | string | `standard` or `advanced`. Decides which voice settings apply. |

```json
[
  {
    "voice_id": 1328,
    "voice_name": "Adnan",
    "voice_sample_url": "https://storage.moknah.io/media/voice_samples/Adnan.mp3",
    "voice_fees": 0.0,
    "voice_badges": {
      "language": "Arabic",
      "gender": "Male",
      "age": "Young Adult",
      "use_case": "Documentary, Audiobook, Article"
    },
    "voice_engine": "standard"
  }
]
```

The values above are an example. Voice ids differ per account: always read them from this endpoint and never guess one.

## Examples

```bash
curl -X POST "https://moknah.io/api/v1/voices/" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Names and badges in Arabic (English where a voice has no Arabic text)
curl -X POST "https://moknah.io/api/v1/voices/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "ar"}'
```

```python
import requests

response = requests.post(
    "https://moknah.io/api/v1/voices/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
for voice in response.json():
    print(voice["voice_id"], voice["voice_name"], voice["voice_engine"])
```

```javascript
const response = await fetch("https://moknah.io/api/v1/voices/", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const voices = await response.json();
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | `engine` is not `standard` or `advanced`, or is not the key's voice type. |
| 401 | `authentication_failed` | Missing, invalid or inactive key, or a caller outside the key's IP allowlist. |
| 405 | `method_not_allowed` | The request was not a POST. |
| 500 | `INTERNAL_SERVER_ERROR` | Unexpected failure. |

See [Errors](../errors/index.md).

## Credits

Listing voices is free.
