> ## Documentation Index
> Fetch the complete documentation index at: https://developers.heygen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice in avatar videos

> How voice works when you create an avatar video with POST /v3/videos: pick a voice, check the language and accent, name the engine and model, then set how the script is spoken.

When you send a `script` to [`POST /v3/videos`](https://developers.heygen.com/reference/create-video), HeyGen turns it into speech before it renders the video. Four choices decide how that speech sounds. You make them in this order.

| Choice | What it is | Where you set it |
| - | - | - |
| Voice | Who speaks | `voice_id` |
| Engine | What turns the script into audio | `voice_settings.engine_settings.engine_type` |
| Model | A version of an engine. Two models of one engine sound slightly different. | `voice_settings.engine_settings.model` |
| Settings | Accent, speed, volume, and the controls each engine has | `voice_settings` |

`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](https://developers.heygen.com/audio-to-video.md).

## Step 1: Pick a voice

You can use a public voice or a voice of your own. Either way, you pass its `voice_id`.

* **A public voice** comes from HeyGen's library. List them with [`GET /v3/models/audio/voices?type=public`](https://developers.heygen.com/reference/list-audio-voices). See [Voice library](https://developers.heygen.com/docs/voices/overview.md).
* **Your own voice** is an [instant voice clone](https://developers.heygen.com/docs/voices/heygen-voice-instant-clone.md), a [professional voice clone](https://developers.heygen.com/docs/voices/professional-voice-clone.md) or a voice design. List them with [`GET /v3/models/audio/voices?type=private`](https://developers.heygen.com/reference/list-audio-voices).

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`](https://developers.heygen.com/reference/get-video-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.

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/videos/voice-capabilities" \
  -H "x-api-key: YOUR_API_KEY"
```

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`.

| Engine | What it is | `engine_type` | Models |
| - | - | - | - |
| HeyGen Voice | Highest voice similarity. Closest match to the selected voice, with consistent quality across long, multi-scene scripts. | `heygen_voice` | `heygen-voice-1` (default). Every voice takes it except a professional voice clone, which takes no model. |
| ElevenLabs | Clean, professional audio quality. | `elevenlabs` | `eleven_multilingual_v2`, `eleven_turbo_v2_5`, `eleven_v3`, `eleven_v4` |
| Fish | Captures fine voice detail with strong accent preservation. | `fish` | `s2.1-pro` (default), `s2-pro` |
| Cartesia | Fastest generation. Natural-sounding output with the lowest latency. | `cartesia` | `sonic-3.6`, `sonic-3.5` |
| Starfish | Tuned for Asian languages. Strong voice similarity and accent fidelity. | `starfish` | No model to choose |
| Mockingbird | Specialized for accents. Preserves regional pronunciation and accent-specific delivery. | `mockingbird` | No model to choose. It needs a regional accent in `voice_settings.locale`. |

The engines a voice can use also depend on its type.

| Voice type | Engines it can use |
| - | - |
| Public voice | All |
| Instant voice clone | All |
| Voice design | All |
| Professional voice clone | HeyGen Voice only. Leave `model` out: a professional voice clone takes no model. |

> [!WARNING]
>
> 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.

| Field | What it does | Values |
| - | - | - |
| `voice_settings.speed` | How fast the voice speaks | 0.5 to 1.5, default 1.0 |
| `voice_settings.volume` | How loud the voice is | 0.0 (silent) to 1.0 (full), default 1.0 |

Each engine also has its own controls inside `engine_settings`.

| Engine | Field | Values |
| - | - | - |
| HeyGen Voice | `similarity` | `medium`, `high`, `extra_high`, `max`. Instant voice clones only. |
| HeyGen Voice | `expressiveness` | 0 to 1 |
| HeyGen Voice | `pitch` | -4 to 4 semitones, in steps of 0.5 |
| HeyGen Voice | `inflection` | 0.5 to 2.0 |
| ElevenLabs | `stability` | 0 to 1 |
| ElevenLabs | `similarity_boost`, `style` | 0 to 1. Only for `eleven_multilingual_v2` and `eleven_turbo_v2_5`. |
| ElevenLabs | `use_speaker_boost` | `true` or `false`. Only for `eleven_multilingual_v2` and `eleven_turbo_v2_5`. |
| Fish | `stability`, `similarity` | 0 to 1 |

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:

```bash cURL theme={null}
curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_LOOK_ID",
    "script": "Welcome to the tour. Let me show you around.",
    "voice_id": "YOUR_VOICE_ID",
    "voice_settings": {
      "speed": 1.0,
      "engine_settings": {
        "engine_type": "heygen_voice",
        "model": "heygen-voice-1",
        "expressiveness": 0.5
      }
    }
  }'
```

```python Python theme={null}
import requests

url = "https://api.heygen.com/v3/videos"

payload = {
    "type": "avatar",
    "avatar_id": "YOUR_AVATAR_LOOK_ID",
    "script": "Welcome to the tour. Let me show you around.",
    "voice_id": "YOUR_VOICE_ID",
    "voice_settings": {
        "speed": 1.0,
        "engine_settings": {
            "engine_type": "heygen_voice",
            "model": "heygen-voice-1",
            "expressiveness": 0.5,
        },
    },
}
headers = {"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

```javascript JavaScript theme={null}
const options = {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'avatar',
    avatar_id: 'YOUR_AVATAR_LOOK_ID',
    script: 'Welcome to the tour. Let me show you around.',
    voice_id: 'YOUR_VOICE_ID',
    voice_settings: {
      speed: 1.0,
      engine_settings: {
        engine_type: 'heygen_voice',
        model: 'heygen-voice-1',
        expressiveness: 0.5
      }
    }
  })
};

fetch('https://api.heygen.com/v3/videos', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php PHP theme={null}
<?php

$payload = [
  'type' => 'avatar',
  'avatar_id' => 'YOUR_AVATAR_LOOK_ID',
  'script' => 'Welcome to the tour. Let me show you around.',
  'voice_id' => 'YOUR_VOICE_ID',
  'voice_settings' => [
    'speed' => 1.0,
    'engine_settings' => [
      'engine_type' => 'heygen_voice',
      'model' => 'heygen-voice-1',
      'expressiveness' => 0.5
    ]
  ]
];

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/videos",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: YOUR_API_KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.heygen.com/v3/videos"

	payload := strings.NewReader(`{
  "type": "avatar",
  "avatar_id": "YOUR_AVATAR_LOOK_ID",
  "script": "Welcome to the tour. Let me show you around.",
  "voice_id": "YOUR_VOICE_ID",
  "voice_settings": {
    "speed": 1.0,
    "engine_settings": {
      "engine_type": "heygen_voice",
      "model": "heygen-voice-1",
      "expressiveness": 0.5
    }
  }
}`)

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("x-api-key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CreateVideo {
    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "type": "avatar",
              "avatar_id": "YOUR_AVATAR_LOOK_ID",
              "script": "Welcome to the tour. Let me show you around.",
              "voice_id": "YOUR_VOICE_ID",
              "voice_settings": {
                "speed": 1.0,
                "engine_settings": {
                  "engine_type": "heygen_voice",
                  "model": "heygen-voice-1",
                  "expressiveness": 0.5
                }
              }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.heygen.com/v3/videos"))
            .header("x-api-key", "YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
```

```ruby Ruby theme={null}
require 'uri'
require 'net/http'
require 'json'

url = URI("https://api.heygen.com/v3/videos")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = 'YOUR_API_KEY'
request["Content-Type"] = 'application/json'
request.body = {
  type: "avatar",
  avatar_id: "YOUR_AVATAR_LOOK_ID",
  script: "Welcome to the tour. Let me show you around.",
  voice_id: "YOUR_VOICE_ID",
  voice_settings: {
    speed: 1.0,
    engine_settings: {
      engine_type: "heygen_voice",
      model: "heygen-voice-1",
      expressiveness: 0.5
    }
  }
}.to_json

response = http.request(request)
puts response.read_body
```

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:

```json theme={null}
"voice_settings": {
  "locale": "en-GB",
  "engine_settings": {
    "engine_type": "mockingbird"
  }
}
```

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](https://developers.heygen.com/reference/create-video.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.