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. To browse the existing catalog instead, see Browse Voices. To clone an existing speaker from audio, see POST /v3/voices/clone.

Quick Example

curl

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"
  }'

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']}")

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}`));

Response

{
  "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. Use voice_id directly in POST /v3/voices/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:

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
  }'

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")