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 itsvoice_id.
- A public voice comes from HeyGen’s library. List them with
GET /v3/models/audio/voices?type=public. See Voice library. - Your own voice is an instant voice clone, a professional voice clone or a voice design. List them with
GET /v3/models/audio/voices?type=private.
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 asen-USoren-GB. Leavelocaleout to keep the voice’s natural accent, which HeyGen calls Original 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.
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 inengine_type and, where the engine has models, the model in model.
The engines a voice can use also depend on its type.
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 leaveslocale out, so the voice keeps its natural accent:
locale next to engine_settings, using a locale and engine that GET /v3/videos/voice-capabilities lists together for the script’s language:
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.
