Skip to main content
  • 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

HeaderValue
X-Api-KeyYour HeyGen API key
AuthorizationBearer YOUR_ACCESS_TOKEN (OAuth)

​
Quick Example

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

​
Query Parameters

ParameterTypeRequiredDefaultDescription
typestringNo"public""public" for the shared library or "private" for your cloned voices.
enginestringNo—Filter by voice engine (e.g. "starfish"). Only voices compatible with that engine are returned.
languagestringNo—Filter by language (e.g. "English", "Spanish").
genderstringNo—Filter by gender: "male" or "female".
limitintegerNo20Results per page (1–100).
tokenstringNo—Opaque cursor token for the next page (from a previous response’s next_token).

​
Response Fields

Each voice object in the data array contains:
FieldTypeDescription
voice_idstringUnique identifier. Pass this to POST /v3/voices/speech or video creation endpoints.
namestringDisplay name of the voice.
languagestringPrimary language (e.g. "English").
genderstring"male" or "female".
typestring"public" (shared library) or "private" (your cloned voice).
preview_audio_urlstring or nullURL to a short audio preview.
support_pausebooleanWhether the voice supports SSML pause/break tags.
support_localebooleanWhether 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. 
# 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 -X GET "https://api.heygen.com/v3/voices?engine=starfish" \
  -H "X-Api-Key: $HEYGEN_API_KEY"