> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Browse Voices

> List and filter HeyGen voices by language, gender, accent, and age. Returns voice IDs ready to use in video generation requests across all HeyGen video APIs.

List voices via [`GET /v3/voices`](/reference/list-voices); inspect one via [`GET /v3/voices/{voice_id}`](/reference/get-voice). To create a new voice instead, see [Design Voices](/docs/voices/design-voices) or [Clone a Voice](/reference/clone-a-voice). For TTS, see [Text to Speech](/docs/voices/speech).

## Quick Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.heygen.com/v3/voices?language=English&gender=female&limit=5" \
    -H "X-Api-Key: $HEYGEN_API_KEY"
  ```

  ```json Response theme={null}
  {
    "data": [
      {
        "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
        "name": "Sara",
        "language": "English",
        "gender": "female",
        "type": "public",
        "preview_audio_url": "https://files.heygen.ai/voice/preview_sara.mp3",
        "support_pause": true,
        "support_locale": true
      }
    ],
    "has_more": true,
    "next_token": "eyJsYXN0X2lkIjoiMTIzIn0"
  }
  ```
</CodeGroup>

## Query Parameters

| Parameter  | Type    | Required | Default    | Description                                                                      |
| ---------- | ------- | -------- | ---------- | -------------------------------------------------------------------------------- |
| `type`     | string  | No       | `"public"` | `"public"` for the shared library or `"private"` for your cloned voices.         |
| `engine`   | string  | No       | —          | Filter by voice engine (e.g. `"starfish"`). Only compatible voices are returned. |
| `language` | string  | No       | —          | Filter by language (e.g. `"English"`, `"Spanish"`).                              |
| `gender`   | string  | No       | —          | Filter by `"male"` or `"female"`.                                                |
| `limit`    | integer | No       | `20`       | Results per page (1–100).                                                        |
| `token`    | string  | No       | —          | Opaque cursor token for the next page (from a previous response's `next_token`). |

## Response Fields

Each voice object in the `data` array contains:

| Field               | Type           | Description                                                                                                                                                                                                |
| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `voice_id`          | string         | Unique identifier. Pass this to [`POST /v3/voices/speech`](/reference/generate-speech), [`POST /v3/videos`](/reference/create-video), or [`POST /v3/video-agents`](/reference/create-video-agent-session). |
| `name`              | string         | Display name of the voice.                                                                                                                                                                                 |
| `language`          | string         | Primary language (e.g. `"English"`).                                                                                                                                                                       |
| `gender`            | string         | `"male"` or `"female"`.                                                                                                                                                                                    |
| `type`              | string         | `"public"` (shared library) or `"private"` (your cloned voice).                                                                                                                                            |
| `preview_audio_url` | string or null | URL to a short audio preview.                                                                                                                                                                              |
| `support_pause`     | boolean        | Whether the voice supports SSML pause/break tags.                                                                                                                                                          |
| `support_locale`    | boolean        | Whether the voice supports locale variants (e.g. `en-US` vs `en-GB`).                                                                                                                                      |

## Filtering Examples

### By Language

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?language=Spanish" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### By Gender

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?gender=male" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Your Private (Cloned) Voices

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?type=private" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### TTS-Compatible Voices Only

To get voices that work with [`POST /v3/voices/speech`](/reference/generate-speech), filter by the `starfish` engine:

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?engine=starfish" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

## Pagination

If `has_more` is `true`, pass the `next_token` value as the `token` query parameter to fetch the next page.

```bash curl theme={null}
curl -X GET "https://api.heygen.com/v3/voices?token=eyJsYXN0X2lkIjoiMTIzIn0" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```