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.
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: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 intype=private once they are ACTIVE.
Design a voice
To create a new voice from a description, callPOST /v3/models/audio/voices with mode: design, a name, a language, and a description of the voice’s age, tone, accent, and speaking style:
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 thevoice_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 thevoice_id to Text to Speech (POST /v3/models/audio/tts). To direct the delivery, add Audio Tags.
