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

# Professional Voice Clone

> Train a studio-grade professional voice clone from 20+ minutes of recordings on the HeyGen Voice model, then generate completed or streaming speech.

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

> [!WARNING]
>
> Professional Voice Clone is a **paid feature**. Each voice occupies a purchased professional voice clone slot. Buy slots on the [Usage page](https://platform.heygen.com/usage) before creating a voice; a request with no free slot returns `400 resource_limit_reached`.

A professional clone trains a dedicated [HeyGen Voice](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-voice.md) adapter from one or more recordings of the same speaker. It is the highest-fidelity clone HeyGen offers. To make a voice from one short recording in seconds, use the [Instant Voice Clone](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-instant-clone.md) on the same endpoint with `"mode": "instant"`.

1. [Create a voice](#1-create-a-voice), or retrain an existing one with new recordings.
2. [Poll](#2-poll-training-status) until the voice is `ACTIVE`.
3. [Generate speech](#3-generate-speech), completed or streamed.

## Set up with an agent

Not technical? Let your coding agent do it with you. Paste this into [Claude Code](https://claude.com/claude-code), [Codex](https://openai.com/codex/), or Cursor and it walks you through every step on this page, one at a time, in your own terminal.

```text Prompt for your agent wrap theme={null}
I want to train a HeyGen Professional Voice Clone of my own voice and hear it speak. I am not a developer, so run the commands for me where you can, explain each step in one plain sentence, and when I have to do something myself tell me exactly what and wait for me.

Read these first and follow them exactly:
- https://developers.heygen.com/docs/voices/professional-voice-clone.md
- https://developers.heygen.com/docs/upload-assets.md
- https://developers.heygen.com/docs/voices/heygen-voice-speech.md
- https://developers.heygen.com/docs/for-ai-agents.md (rules for agents)

Then take me through this, checking each step before the next:
1. API key. Look for HEYGEN_API_KEY in my environment. If it is missing, send me to https://platform.heygen.com/api-keys to create one and have me export it in my terminal myself. Never ask me to paste the key into this chat. Confirm it works with GET /v3/users/me and tell me my username.
2. Slot. Ask whether I have bought a professional voice clone slot at https://platform.heygen.com/usage. 400 resource_limit_reached later means there is no free slot.
3. Recordings. Ask me for the folder with my recordings (1 to 10 files, one speaker, at least 20 minutes in total). Check the total duration with ffprobe (install it if needed) and warn me about files with long silence or background noise. Upload each file with POST /v3/assets; use the direct upload flow for any file over 32 MB. Keep the asset_id values.
4. Train. Ask me for a display name, and for the language of the recordings if I know it (otherwise leave language out; training detects it), then call POST /v3/models/audio/voices with mode professional and the asset_ids, using an Idempotency-Key. Poll GET /v3/models/audio/voices/{voice_id} with backoff until status is ACTIVE. If it is FAILED, explain failure_reason and what to change.
5. Speak. Ask me for a few sentences in my language, call POST /v3/models/audio/tts with the voice_id, download the WAV, and open it so I can listen. Then show me how to change the text and run it again.

If a request fails, look the error code up in the Errors tables on those pages and tell me the fix. Never invent keys, IDs, or URLs; if something is missing, ask me for that one thing.
```

## Before you start

### Slots and training allowance

* Voices belong to the workspace of the API key that created them. [Create the key](https://heygen-1fa696a7.mintlify.site/docs/api-key.md) in the workspace that should own the voice.
* One purchased slot per voice. Retraining reuses the voice's slot.
* Each slot provides five pooled trainings per monthly billing period, initial training included. Failed trainings are free.
* If the workspace later exceeds its slot limit, for example when a slot add-on lapses, the surplus voices return `voice_expired` on synthesis until you add a slot or delete another professional voice. The voice and its data stay intact.

### Prepare the recordings

Provide 1–10 recordings of the same speaker totaling at least 20 minutes. Duration is measured including silence, so trim dead air, background noise, and overlapping speech. Upload local files with the [Assets API](https://heygen-1fa696a7.mintlify.site/docs/upload-assets.md) and pass the returned `asset_id` values.

Size limits per recording: 32 MB for a public URL, 16 MB for inline base64 after decoding, 200 MB for a completed `asset_id`. For larger files use the [direct upload flow](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md).

## 1. Create a voice

`POST /v3/models/audio/voices` returns `202 Accepted` while training runs.

```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" \
  -H "Idempotency-Key: customer-voice-2026-08-22" \
  -d '{
    "mode": "professional",
    "name": "Customer narrator",
    "language": "en",
    "audio": [
      { "type": "asset_id", "asset_id": "'"$ASSET_1"'" },
      { "type": "asset_id", "asset_id": "'"$ASSET_2"'" }
    ]
  }'
```

The response carries the new `voice_id`. The full field list is in [the API reference](https://heygen-1fa696a7.mintlify.site/reference/create-or-retrain-an-audio-voice.md). `audio` takes 1–10 recordings and `name` up to 256 characters. Leave `language` out to detect the language of each recording during training; the voice's `language` is then `null` until it is `ACTIVE`.

Every recording is validated and staged before the voice is created, so undecodable audio, an unreachable URL, or fewer than 20 minutes in total returns `400 invalid_parameter` with no `voice_id`.

`Idempotency-Key` is optional. Reusing a key within 24 hours returns the original response; a duplicate that arrives while the original is still being accepted returns `409 request_in_progress`. Without the header, repeated requests create separate voices.

### Retrain a voice

Send `"mode": "professional"`, the `voice_id` of an existing `ACTIVE` voice, and replacement `audio` to the same endpoint. The ID, name, and language are kept. The voice becomes `PENDING` until training completes, and a failed retraining restores the previously active voice.

## 2. Poll training status

Poll [`GET /v3/models/audio/voices/{voice_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-an-audio-voice) with backoff while the voice is `PENDING` (training queued or running). It ends `ACTIVE`, ready for speech, or `FAILED` with a `failure_reason` of `INVALID_AUDIO`, `INSUFFICIENT_AUDIO`, `PREPROCESSING_FAILED`, `TRAINING_FAILED`, `ARTIFACT_VALIDATION_FAILED` or `INTERNAL_ERROR`.

## 3. Generate speech

Pass the `ACTIVE` voice to [Text to Speech](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md): `POST /v3/models/audio/tts` for one completed WAV, or `POST /v3/models/audio/tts/stream` for audio parts as they are generated. Professional voices use `heygen-voice-1`.

## Manage voices

`GET /v3/models/audio/voices` lists the workspace's instant and professional voices, newest first, with `mode` telling them apart; paging is on [Voices](https://heygen-1fa696a7.mintlify.site/docs/voices/overview.md).

An `ACTIVE` professional voice has a `preview_audio_url`, a WAV of the voice reading a short preview script, made right after training. It can be `null` for a few minutes after a voice turns `ACTIVE`, and for a voice whose preview could not be made yet.

`DELETE /v3/models/audio/voices/{voice_id}` removes an `ACTIVE` or `FAILED` voice and frees its slot. Wait for a `PENDING` voice to finish training first.

## Errors

| HTTP status | Error code | Meaning |
| - | - | - |
| `400` | `invalid_parameter` | Invalid request or audio input, or under 20 minutes of recordings. |
| `400` | `resource_limit_reached` | No free voice slot, or the monthly training allowance is used up. |
| `403` | `forbidden` | The account is not enabled for professional voice cloning. Check the plan on the [Usage page](https://platform.heygen.com/usage). |
| `409` | `request_in_progress` | The same `Idempotency-Key` is still being accepted. Retry with backoff. |
| `409` | `resource_not_ready` | The voice is `PENDING`: another training is running, or it was submitted for deletion. |
| `429` | `rate_limit_exceeded` | Retry after the seconds in `Retry-After`. |

Synthesis errors, including `voice_expired`, are listed on [Text to Speech](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md#errors). The full catalog is in [Error Codes](https://heygen-1fa696a7.mintlify.site/docs/error-codes.md).


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