> ## 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.

# Voices

> Browse, search, and use voices on HeyGen via the Voices API. Covers stock voices, custom voice design, voice cloning, and how to pair voices with avatars.

HeyGen provides 300+ pre-built voices across dozens of languages, plus the ability to generate custom AI voices from a text description, clone an existing speaker, or synthesize speech directly. This guide walks the full **browse → design → use** workflow; deeper guides for each step live at [Browse Voices](/docs/voices/search-voices), [Design Voices](/docs/voices/design-voices), and [Text to Speech](/docs/voices/speech).

## Step 1: Browse Available Voices

Use [`GET /v3/voices`](/reference/list-voices) to list available voices with cursor-based pagination. Filter by language, gender, type, or engine.

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

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.heygen.com/v3/voices",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      params={"language": "English", "gender": "female"},
  )
  data = resp.json()
  voices = data["data"]
  for v in voices[:5]:
      print(f"{v['voice_id']} — {v['name']} ({v['language']})")
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch(
    "https://api.heygen.com/v3/voices?language=English&gender=female",
    { headers: { "X-Api-Key": process.env.HEYGEN_API_KEY } }
  );
  const { data } = await resp.json();
  data.slice(0, 5).forEach((v) =>
    console.log(`${v.voice_id} — ${v.name} (${v.language})`)
  );
  ```
</CodeGroup>

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

### Query Parameters

| Parameter  | Type    | Description                                                                                       |
| ---------- | ------- | ------------------------------------------------------------------------------------------------- |
| `type`     | string  | `"public"` for the shared library or `"private"` for your cloned voices. Defaults to `"public"`.  |
| `engine`   | string  | Filter by voice engine (e.g. `"starfish"`). Only voices compatible with that engine are returned. |
| `language` | string  | Filter by language name (e.g. `"English"`, `"Spanish"`, `"Japanese"`).                            |
| `gender`   | string  | Filter by `"male"` or `"female"`.                                                                 |
| `limit`    | integer | Results per page (1–100). Defaults to `20`.                                                       |
| `token`    | string  | Opaque cursor token for the next page.                                                            |

### Response Fields

| Field               | Type           | Description                                                                                                                                                                                                                   |
| ------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `voice_id`          | string         | Pass this as `voice_id` to [`POST /v3/videos`](/reference/create-video) or [`POST /v3/video-agents`](/reference/create-video-agent-session). Inspect a single voice with [`GET /v3/voices/{voice_id}`](/reference/get-voice). |
| `name`              | string         | Display name of the voice.                                                                                                                                                                                                    |
| `language`          | string         | Primary language.                                                                                                                                                                                                             |
| `gender`            | string         | Gender of the voice.                                                                                                                                                                                                          |
| `preview_audio_url` | string or null | URL to a short audio preview — play to audition the voice.                                                                                                                                                                    |
| `support_pause`     | boolean        | Whether the voice supports SSML pause/break tags.                                                                                                                                                                             |
| `support_locale`    | boolean        | Whether the voice supports locale variants.                                                                                                                                                                                   |
| `type`              | string         | `"public"` or `"private"`.                                                                                                                                                                                                    |

<Tip>
  Each voice includes a `preview_audio_url` — play these to audition voices before using one in your video.
</Tip>

## Step 2: Design a Custom Voice (Optional)

If none of the pre-built voices fit, use [`POST /v3/voices`](/reference/design-a-voice) to generate up to 3 AI voice options from a text description. The endpoint returns a ranked list — pick the one that fits best. For more detail and prompting patterns, see [Design Voices](/docs/voices/design-voices). To clone an existing speaker from audio samples instead, use [`POST /v3/voices/clone`](/reference/clone-a-voice).

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.heygen.com/v3/voices" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.",
      "gender": "male"
    }'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.heygen.com/v3/voices",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={
          "prompt": "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.",
          "gender": "male",
      },
  )
  result = resp.json()["data"]
  for v in result["voices"]:
      print(f"{v['voice_id']} — {v['name']}")
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch("https://api.heygen.com/v3/voices", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "A warm, confident male voice with a slight British accent. Deep baritone, measured pace, suitable for tech product narration.",
      gender: "male",
    }),
  });
  const { data } = await resp.json();
  data.voices.forEach((v) => console.log(`${v.voice_id} — ${v.name}`));
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "voices": [
      {
        "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
        "name": "James",
        "language": "English",
        "gender": "male",
        "preview_audio_url": "https://files.heygen.ai/voice/preview/james.mp3",
        "support_pause": true,
        "support_locale": true,
        "type": "public"
      }
    ],
    "seed": 0
  }
}
```

### Parameters

| Parameter | Type    | Required | Description                                                                                                                                         |
| --------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`  | string  | Yes      | Text description of the desired voice — accent, tone, pace, gender, personality. Max 1000 characters.                                               |
| `gender`  | string  | No       | Filter results by `"male"` or `"female"`.                                                                                                           |
| `locale`  | string  | No       | BCP-47 locale tag to filter by (e.g. `"en-US"`, `"pt-BR"`).                                                                                         |
| `seed`    | integer | No       | Controls which batch of results to return. `0` returns the top matches, `1` the next batch, etc. Same prompt + seed always returns the same voices. |

<Info>
  **Prompting tips for voice design:**

  * Specify gender and approximate age (`"young woman in her 20s"`, `"mature male voice"`)
  * Describe the accent (`"American Midwest"`, `"slight French accent"`)
  * Set the tone (`"warm and friendly"`, `"authoritative"`, `"playful"`)
  * Mention pacing (`"measured and calm"`, `"energetic and fast"`)
  * Reference a use case (`"suitable for corporate training"`, `"good for storytelling"`)
</Info>

## Step 3: Use a Voice in Video Creation

Once you have a `voice_id`, pass it when creating a video. To render speech directly without an avatar, use [Text to Speech](/docs/voices/speech) ([`POST /v3/voices/speech`](/reference/generate-speech)).

### With Video Agent

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 30-second explainer about cloud computing benefits",
    "voice_id": "1bd001e7e50f421d891986aad5c8bbd2"
  }'
```

### With Direct Video Creation

Set the voice alongside your avatar and script:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "your_look_id",
    "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
    "script": "Welcome to our platform. Today I will walk you through the key features."
  }'
```

### Voice Settings

When using [`POST /v3/videos`](/reference/create-video), you can fine-tune playback via `voice_settings`:

```json theme={null}
{
  "type": "avatar",
  "avatar_id": "your_look_id",
  "voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
  "script": "Welcome to our platform.",
  "voice_settings": {
    "speed": 1.1,
    "pitch": 0.0,
    "locale": "en-US"
  }
}
```

| Field    | Type   | Range         | Description                                       |
| -------- | ------ | ------------- | ------------------------------------------------- |
| `speed`  | number | `0.5` – `1.5` | Playback speed multiplier. `1.0` is normal speed. |
| `pitch`  | number | `-50` – `+50` | Pitch adjustment in semitones.                    |
| `locale` | string | BCP-47        | Locale/accent hint for multi-lingual voices.      |