Voices

Browse and filter available voices for text-to-speech and video creation.

• Endpoint: GET https://api.heygen.com/v3/voices
• Purpose: List available voices with filtering and cursor-based pagination. Use a voice_id from this endpoint when creating speech or videos.

Authentication

Header	Value
X-Api-Key	Your HeyGen API key
Authorization	Bearer YOUR_ACCESS_TOKEN (OAuth)

Quick Example

curl

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

Query Parameters

Parameter	Type	Required	Default	Description
type	string	No	"public"	"public" for the shared library or "private" for your cloned voices.
engine	string	No	—	Filter by voice engine (e.g. "starfish"). Only voices compatible with that engine are returned.
language	string	No	—	Filter by language (e.g. "English", "Spanish").
gender	string	No	—	Filter by gender: "male" or "female".
limit	integer	No	20	Results per page (1–100).
token	string	No	—	Opaque cursor token for the next page (from a previous response’s next_token).

Response Fields

Each voice object in the data array contains:

Field	Type	Description
voice_id	string	Unique identifier. Pass this to POST /v3/voices/speech or video creation endpoints.
name	string	Display name of the voice.
language	string	Primary language (e.g. "English").
gender	string	"male" or "female".
type	string	"public" (shared library) or "private" (your cloned voice).
preview_audio_url	string or null	URL to a short audio preview.
support_pause	boolean	Whether the voice supports SSML pause/break tags.
support_locale	boolean	Whether the voice supports locale variants (e.g. en-US vs en-GB).

Pagination

The endpoint uses cursor-based pagination. If has_more is true, pass the next_token value as the token query parameter in your next request to fetch the next page.

curl

# Fetch the next page
curl -X GET "https://api.heygen.com/v3/voices?token=eyJsYXN0X2lkIjoiMTIzIn0" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Filtering for TTS-Compatible Voices

To get only voices that work with the text-to-speech endpoint (POST /v3/voices/speech), filter by the starfish engine:

curl

curl -X GET "https://api.heygen.com/v3/voices?engine=starfish" \
  -H "X-Api-Key: $HEYGEN_API_KEY"