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

# Voices

> List HeyGen voices and your own voice clones with GET /v3/models/audio/voices, then use a voice_id in a video or in Text to Speech.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-2.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=d6ee10585b27ddaf8137d6ed67791708)

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`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices), then pass the `voice_id` to a video or to [Text to Speech](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md).

## List voices

`type=public` lists the voices HeyGen provides to every workspace. `type=private`, the default, lists the voices your workspace created.

```bash theme={null}
curl "https://api.heygen.com/v3/models/audio/voices?type=public&limit=20" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

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}`](https://heygen-1fa696a7.mintlify.site/reference/get-an-audio-voice).

### 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:

| Filter | Values |
| - | - |
| `language` | A language code, such as `en`. Voices that speak many languages also match, unless you add `query` or `age`. |
| `gender` | `male` or `female` |
| `age` | `young`, `middle_aged`, or `old` |
| `query` | Free text matched against voice names and descriptions, such as `warm narrator` (up to 256 characters). Results are ordered by relevance. |

```bash theme={null}
curl "https://api.heygen.com/v3/models/audio/voices?type=public&language=en&gender=female&query=calm%20narrator" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

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](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-instant-clone.md) from one recording, or a [Professional Voice Clone](https://heygen-1fa696a7.mintlify.site/docs/voices/professional-voice-clone.md) 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`](https://heygen-1fa696a7.mintlify.site/reference/create-or-retrain-an-audio-voice) with `mode: design`, a `name`, a `language`, and a `description` of the voice's age, tone, accent, and speaking style:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/models/audio/voices" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "design",
    "name": "Narrator",
    "language": "en",
    "description": "A warm, confident male voice in his 40s with a slight British accent, measured pace."
  }'
```

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`](https://heygen-1fa696a7.mintlify.site/reference/create-video); [`POST /v3/video-agents`](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session) 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](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md) (`POST /v3/models/audio/tts`). To direct the delivery, add [Audio Tags](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-audio-tags.md).


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