Skip to main content
When you send a script to POST /v3/videos, HeyGen turns it into speech before it renders the video. Four choices decide how that speech sounds. You make them in this order. voice_settings applies only when you send a script with a voice_id. If you send your own audio with audio_url or audio_asset_id, HeyGen uses that audio as it is. See Avatar video from audio.

Step 1: Pick a voice

You can use a public voice or a voice of your own. Either way, you pass its voice_id. If you send a script and an avatar_id with no voice_id, the avatar’s default voice is used.

Step 2: Check the language and accent

Language and accent are two different things.
  • Language is the language the script is written in, such as English. HeyGen detects it from the script. You do not set it.
  • Accent is how that language is spoken. English can be read with a US, UK or Australian accent. You set it with voice_settings.locale, such as en-US or en-GB. Leave locale out to keep the voice’s natural accent, which HeyGen calls Original Accent.
The engines you can use depend on both the language and the accent. GET /v3/videos/voice-capabilities lists, for each language and accent, the engines offered and the models each engine offers. An entry with a locale of null is Original Accent. An empty model list means there is no model to choose.
Check this list before you create the video, and pick an engine and model from the entry that matches your script’s language and the accent you want. Send a locale only if the list offers it for that language and engine. A regional accent is often offered by fewer engines than Original Accent, so the list may show only one engine for the accent you want.

Step 3: Name the engine and model

Six engines can speak a script. Pass the engine in engine_type and, where the engine has models, the model in model. The engines a voice can use also depend on its type.
Always send engine_settings with the engine, and the model where the engine has one. If you leave engine_settings out, HeyGen picks the engine when the video renders. It may not be the engine you expect, and the video can fail after it is created.
The request is rejected when the voice cannot be used with the engine you name.

Step 4: Set how the script is spoken

Speed and volume are set the same way for every engine. Each engine also has its own controls inside engine_settings. Cartesia, Starfish and Mockingbird have no controls of their own. To change the pitch of HeyGen Voice, use engine_settings.pitch. The older voice_settings.pitch field does not apply to it.

Example

An avatar video that names the voice, engine, model and settings. It leaves locale out, so the voice keeps its natural accent:
To ask for an accent, add locale next to engine_settings, using a locale and engine that GET /v3/videos/voice-capabilities lists together for the script’s language:
A video from an image (type: "image") takes the same voice_id and voice_settings fields. In a studio video (type: "studio") you set them on each scene. A cinematic avatar video takes no script and no voice. Every field is in the Create Video reference.