Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.heygen.com/llms.txt

Use this file to discover all available pages before exploring further.

HeyGen provides 300+ pre-built voices across dozens of languages, plus the ability to generate custom AI voices from a text description. This guide walks through the full workflow: browse → design → use.

​
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 -X GET "https://api.heygen.com/v3/voices?language=English&gender=female" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
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

ParameterTypeDescription
typestring"public" for the shared library or "private" for your cloned voices. Defaults to "public".
enginestringFilter by voice engine (e.g. "starfish"). Only voices compatible with that engine are returned.
languagestringFilter by language name (e.g. "English", "Spanish", "Japanese").
genderstringFilter by "male" or "female".
limitintegerResults per page (1–100). Defaults to 20.
tokenstringOpaque cursor token for the next page.

​
Response Fields

FieldTypeDescription
voice_idstringPass this as voice_id to video creation endpoints.
namestringDisplay name of the voice.
languagestringPrimary language.
genderstringGender of the voice.
preview_audio_urlstring or nullURL to a short audio preview — play to audition the voice.
support_pausebooleanWhether the voice supports SSML pause/break tags.
support_localebooleanWhether the voice supports locale variants.
typestring"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. 
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"
  }'
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

ParameterTypeRequiredDescription
promptstringYesText description of the desired voice — accent, tone, pace, gender, personality. Max 1000 characters.
genderstringNoFilter results by "male" or "female".
localestringNoBCP-47 locale tag to filter by (e.g. "en-US", "pt-BR").
seedintegerNoControls 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.

​
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"
  }
}
FieldTypeRangeDescription
speednumber0.5 – 1.5Playback speed multiplier. 1.0 is normal speed.
pitchnumber-50 – +50Pitch adjustment in semitones.
localestringBCP-47Locale/accent hint for multi-lingual voices.