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

# Voices overview

> Curated TTS voices available for agent speech synthesis.

A **voice** is a TTS (text-to-speech) voice preset that an agent uses to speak. The catalog is a curated snapshot of voices offered by supported providers — there is no API to create, modify, or delete voices.

## Providers and models

`GET /v1/voice-providers` returns every supported TTS provider together with the models it offers and the tunable settings (sliders) that apply to all voices from that provider. Use this endpoint to populate the provider/model selector in the configuration UI and to render per-provider setting knobs.

Each provider entry includes:

| Field             | Description                                                                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | Provider slug used in all TTS configuration fields (e.g. `cartesia`).                                                                    |
| `display_name`    | Human-readable provider name.                                                                                                            |
| `models`          | Available TTS models with an optional editorial badge (e.g. "Fastest").                                                                  |
| `default_model`   | The model pre-selected in the UI.                                                                                                        |
| `settings_schema` | Slider definitions (key, label, min/max/step/default, end labels) for the tunables that apply globally to all voices from this provider. |

## Voice catalog

`GET /v1/voices` returns a paginated list of voices for a single provider. The `provider` query parameter is **required**.

Each voice entry carries:

| Field                                    | Description                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------ |
| `id`                                     | The exact provider voice ID passed to the agent runtime.                       |
| `name`                                   | Display name for the picker.                                                   |
| `provider` / `model`                     | Matches the fields set in `AgentTtsConfig`.                                    |
| `description`                            | Editorial one-liner.                                                           |
| `gender` / `accent` / `age` / `category` | Optional facet labels used for filtering.                                      |
| `preview_url`                            | Optional URL to a sample audio clip (omitted when no verified preview exists). |
| `avatar_url`                             | Picker thumbnail.                                                              |

### Filtering

Pass any combination of `gender`, `accent`, `age`, `category`, or `language` as query parameters to narrow the list. Each filter performs a case-insensitive exact match against the corresponding field. Voices that lack the field are excluded when that filter is active.

The `search` parameter matches against `name` **or** `description` (case-insensitive substring match). It can be combined with facet filters.

### Cursor pagination

The response includes a `next_cursor` field. When it is non-null, pass it as the `cursor` query parameter on the next request to fetch the following page. When `next_cursor` is `null`, there are no more results.

The cursor is an opaque base64-encoded offset — treat it as an opaque string; do not parse or construct it.

```
GET /v1/voices?provider=elevenlabs&limit=10
→ { voices: [...10 items...], next_cursor: "MTA=" }

GET /v1/voices?provider=elevenlabs&limit=10&cursor=MTA=
→ { voices: [...10 items...], next_cursor: "MjA=" }

GET /v1/voices?provider=elevenlabs&limit=10&cursor=MjA=
→ { voices: [...1 item...], next_cursor: null }
```

`limit` defaults to 30 and is capped at 100.