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

# Design a Voice

> Generate a brand new custom voice from a natural-language description using the HeyGen Design a Voice API. No source audio needed; describe the voice you want.

Full schema: [`POST /v3/voices`](/reference/design-a-voice). To browse the existing catalog instead, see [Browse Voices](/docs/voices/search-voices). To clone an existing speaker from audio, see [`POST /v3/voices/clone`](/reference/clone-a-voice).

## Quick Example

<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}
  import requests

  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. 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. Same prompt + seed always returns the same voices. |

## Response Fields

| Field    | Type    | Description                                                                                                                                                                                                                                   |
| -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `voices` | array   | Up to 3 matching voices, ordered by relevance. Each has the same shape as voices returned by [`GET /v3/voices`](/reference/list-voices). Use `voice_id` directly in [`POST /v3/voices/speech`](/reference/generate-speech) or video creation. |
| `seed`   | integer | The seed used for this request. Increment to get a different batch of voices.                                                                                                                                                                 |

## Getting Different Results

If the returned voices don't fit, increment `seed` to get the next batch — same prompt, different voices:

```bash 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.",
    "gender": "male",
    "seed": 1
  }'
```

<Tip>
  **Prompting tips:**

  * Specify gender and 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"`)
</Tip>