Professional Voice Clone

Professional Voice Clone is a paid feature. Each voice occupies a purchased professional voice clone slot. Buy slots on the Usage page before creating a voice; a request with no free slot returns 400 resource_limit_reached.

A professional clone trains a dedicated HeyGen Voice 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 on the same endpoint with "mode": "instant".

Create a voice, or retrain an existing one with new recordings.
Poll until the voice is ACTIVE.
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, Codex, or Cursor and it walks you through every step on this page, one at a time, in your own terminal.

Prompt for your agent

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 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 and pass the returned asset_id values:

ASSET_1=$(curl -sS -X POST "https://api.heygen.com/v3/assets" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -F "file=@./narrator-part-1.wav" | jq -er '.data.asset_id')

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.

1. Create a voice

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

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"'" }
    ]
  }'

Response

{
  "data": {
    "voice_id": "0f4e5d8c9a1b4d62a914938d06c31234"
  }
}

Field	Type	Required	Description
`mode`	string	Yes	`professional`.
`name`	string	New voices	Display name, up to 256 characters.
`language`	string	No	Primary language code of the recordings, such as `en`. Leave it out to detect the language of each recording during training; the voice’s `language` is `null` until it is `ACTIVE`.
`audio`	array	Yes	1–10 recordings, each `{ "type": "url", "url" }`, `{ "type": "asset_id", "asset_id" }`, or `{ "type": "base64", "media_type", "data" }`.
`voice_id`	string	Retraining	Existing `ACTIVE` voice to retrain. Omit when creating.

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 existing voice_id, and replacement audio. The ID, name, and language are kept. The voice becomes PENDING until training completes, and a failed retraining restores the previously active voice.

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-retrain-2026-09-02" \
  -d '{
    "mode": "professional",
    "voice_id": "0f4e5d8c9a1b4d62a914938d06c31234",
    "audio": [
      { "type": "asset_id", "asset_id": "'"$ASSET_1"'" }
    ]
  }'

2. Poll training status

Poll GET /v3/models/audio/voices/{voice_id} with backoff until the status is terminal.

curl "https://api.heygen.com/v3/models/audio/voices/0f4e5d8c9a1b4d62a914938d06c31234" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Response

{
  "data": {
    "voice_id": "0f4e5d8c9a1b4d62a914938d06c31234",
    "mode": "professional",
    "name": "Customer narrator",
    "language": "en",
    "status": "ACTIVE",
    "created_at": 1787405696
  }
}

Status	Meaning
`PENDING`	Training is queued or running.
`ACTIVE`	Ready for speech generation.
`FAILED`	Training ended. `failure_reason` is one of `INVALID_AUDIO`, `INSUFFICIENT_AUDIO`, `PREPROCESSING_FAILED`, `TRAINING_FAILED`, `ARTIFACT_VALIDATION_FAILED`, `INTERNAL_ERROR`.

created_at is a Unix timestamp in seconds.

3. Generate speech

Pass the ACTIVE voice to Text to Speech: POST /v3/models/audio/tts for one completed WAV, or POST /v3/models/audio/tts/stream for audio parts as they are generated.

curl -X POST "https://api.heygen.com/v3/models/audio/tts" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-voice-1",
    "voice_id": "0f4e5d8c9a1b4d62a914938d06c31234",
    "text": "Hello from my professional voice clone.",
    "language": "en"
  }'

Manage voices

GET /v3/models/audio/voices lists the workspace’s instant and professional voices, newest first, with mode telling them apart, with limit (1–100, default 10) and cursor token. Pass the returned next_token while has_more is true. type=public lists HeyGen’s public voices instead. 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.

curl -X DELETE "https://api.heygen.com/v3/models/audio/voices/0f4e5d8c9a1b4d62a914938d06c31234" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

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.
`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. The full catalog is in Error Codes.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Avatar Management

Voice Management

Video Translation

Lipsync

Tools

Asset Management

Batches

Webhook

Limits

Socials

For Agents

Integrations

Set up with an agent

Before you start

Slots and training allowance

Prepare the recordings

1. Create a voice

Retrain a voice

2. Poll training status

3. Generate speech

Manage voices

Errors

​Set up with an agent

​Before you start

​Slots and training allowance

​Prepare the recordings

​1. Create a voice

​Retrain a voice

​2. Poll training status

​3. Generate speech

​Manage voices

​Errors

Set up with an agent

Before you start

Slots and training allowance

Prepare the recordings

1. Create a voice

Retrain a voice

2. Poll training status

3. Generate speech

Manage voices

Errors