HeyGen Documentation

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.

Example Request

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

Example 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 video creation endpoints.
`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".

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.

Example Request

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

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

Step 3: Use a Voice in Video Creation

Once you have a voice_id, pass it when creating a video.

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

Example Request with Direct Video Creation

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.