# client.voices

> The voices methods of the morevoice Python SDK: Voices assistants can speak with.

Voices assistants can speak with. These methods are on `client.voices`, where `client` is a `MoreVoice` client (see [the Python SDK](https://docs.morevoice.ai/sdk/python/#connect)). On `AsyncMoreVoice` the same methods are awaited. Each one returns the response object and raises an exception when the API answers with an error.

## `list()`

**List voices.** The voices assistants can speak with: your custom voices first, then the provider's library by name (the dashboard's order).

```python
# client.voices
def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, type_: _m.VoicesListType | Unset = UNSET, language: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.Voice]
```

`client.voices.list()` · `await async_client.voices.list()` · `GET /voices` · [API reference](https://docs.morevoice.ai/api/operations/voices_list/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |
| `type` | `"prebuilt" \| "custom"` | no | Only prebuilt or only custom voices. |
| `language` | `string` | no | Only voices listing this language (`en` matches `en-US`). |

### Returns

A page of results (`VoiceList`): `data`, `has_more` and `next_cursor`.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for voice in client.voices.list():
    print(voice)
```

## `preview()`

**Preview a voice.** Speaks up to 300 characters in a voice and returns a WAV file. Test-mode keys get a synthetic tone of the same length instead, and no speech provider is called; the `Audio-Source` response header says which you got (`speech` or `synthetic`).

```python
# client.voices
def preview(self, body: _m.VoicesPreviewBody | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> bytes
```

`client.voices.preview()` · `await async_client.voices.preview()` · `POST /voices/preview` · [API reference](https://docs.morevoice.ai/api/operations/voices_preview/)

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `voice_id` | `string` | yes | The voice to hear (`voice_id` from `GET /v1/voices`). |
| `language` | `string` | no | The language of `text` (default `he`). |
| `model` | `string` | no | The TTS model (default: the assistants' default). |
| `style` | `string` | no | Delivery direction, e.g. `calm and reassuring`. |
| `text` | `string` | no | What to say, up to 300 characters (default: a short greeting in `language`). |

### Returns

Nothing, on success.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

data = client.voices.preview({
    "language": "he",
    "style": "warm and friendly",
    "text": "שלום! ככה אני נשמעת.",
    "voice_id": "Kore",
})
print(len(data), "bytes")
```