Skip to main content
Every voice is a HeyGen Voice: the public voices HeyGen provides, and the instant and professional voices your workspace clones. List them with GET /v3/models/audio/voices, then pass the voice_id to a video or to Text to Speech.

List voices

type=public lists the voices HeyGen provides to every workspace. type=private, the default, lists the voices your workspace created.
Each voice carries its voice_id, mode (instant or professional), name, language code, status (ACTIVE when ready to use, PENDING while a new clone is being made) and a preview_audio_url to audition it. Public voices also carry gender when it is known. If has_more is true, pass next_token as token to get the next page. To read one voice, use GET /v3/models/audio/voices/{voice_id}.

Find a public voice

The public list comes in the same order as the voice library in the HeyGen app. Narrow it with any of these filters:
A public page holds up to 50 voices. A next_token works with the same filters that returned it, so keep them on every page. The filters apply to type=public; with type=private, or with an unknown language code, the request returns 400.

Clone a voice

To use a specific speaker, make an Instant Voice Clone from one recording, or a Professional Voice Clone trained on 20+ minutes of recordings. Both appear in type=private once they are ACTIVE.

Design a voice

To create a new voice from a description, call POST /v3/models/audio/voices with mode: design, a name, a language, and a description of the voice’s age, tone, accent, and speaking style:
The request returns voice_id with HTTP 202. The voice is ready once it is ACTIVE and has a preview_audio_url. Free-plan workspaces can make 20 voice-design calls per rolling 24 hours by default, shared by all members.

Use a voice

In a video

Pass the voice_id with your avatar and script to POST /v3/videos; POST /v3/video-agents takes the same voice_id for narration. To adjust delivery in a video, set voice_settings: speed (0.5–1.5), pitch (-50 to +50 semitones) and locale (a BCP-47 accent hint for multilingual voices).

As speech audio

For standalone audio, send the voice_id to Text to Speech (POST /v3/models/audio/tts). To direct the delivery, add Audio Tags.