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, Design Voices, and Text to Speech.

Step 1: Browse Available Voices

Use GET /v3/voices to list available voices with cursor-based pagination. Filter by language, gender, type, or engine.

curl

curl -X GET "https://api.heygen.com/v3/voices?language=English&gender=female" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

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

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

Response

{
  "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 or POST /v3/video-agents. Inspect a single voice with GET /v3/voices/{voice_id}.
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".

Each voice includes a preview_audio_url — play these to audition voices before using one in your video.

Step 2: Design a Custom Voice (Optional)

If none of the pre-built voices fit, use POST /v3/voices 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. To clone an existing speaker from audio samples instead, use POST /v3/voices/clone.

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

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

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

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 (POST /v3/voices/speech).

With Video Agent

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:

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, you can fine-tune playback via voice_settings:

{
  "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.