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

# Instant Voice Clone

> Clone a voice from one recording on the HeyGen Voice model with POST /v3/models/audio/voices, 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)

One recording in, a voice out. [`POST /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/create-or-retrain-an-audio-voice) with `"mode": "instant"` returns a `voice_id` that is usually `ACTIVE` within seconds. No training and no voice clone slot.

1. [Create the voice](#1-create-the-voice)
2. [Wait until it is `ACTIVE`](#2-wait-until-it-is-active)
3. [Generate speech](#3-generate-speech)

## Set up with an agent

Not technical? 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 in your own terminal.

```text Prompt for your agent wrap theme={null}
I want to make a HeyGen instant voice clone from one recording of my 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/heygen-voice-instant-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.
2. Recording. Ask me for one audio file of my voice. Check it with ffprobe (install it if needed): about 1 minute of clear speech is ideal, and only the first 3 minutes are used. Warn me about long silence or background noise. Upload it with POST /v3/assets and keep the asset_id.
3. Clone. Ask me for a display name, then call POST /v3/models/audio/voices with mode instant, the asset_id and an Idempotency-Key. Poll GET /v3/models/audio/voices/{voice_id} until status is ACTIVE. If it is FAILED, explain failure_reason and what to change.
4. Speak. Ask me for a few sentences, then call POST /v3/models/audio/tts with model heygen-voice-1, the voice_id and text. Send language only if I told you the language; otherwise leave it out so HeyGen detects it. Download the WAV and open it so I can listen. 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.
```

## 1. Create the voice

[Upload the recording](https://heygen-1fa696a7.mintlify.site/docs/upload-assets.md) and pass its `asset_id`, or send a public HTTPS URL or base64 audio. The call returns `202 Accepted`. Free-plan workspaces can make 20 clone calls per rolling 24 hours by default, shared by all members.

```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-instant-voice-2026-10-09" \
  -d '{
    "mode": "instant",
    "name": "Customer narrator",
    "language": "en",
    "audio": [
      { "type": "asset_id", "asset_id": "'"$ASSET_ID"'" }
    ]
  }'
```

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). Fields worth knowing:

* `audio` takes exactly one recording. `name` is 1–64 characters, and `language` is detected from the recording when omitted (see [Languages](#languages)).
* `similarity` sets how closely the voice follows the recording: `medium`, `high`, `extra_high` (default) or `max`.
* `remove_background_noise` (default `true`) removes background noise, not room echo.
* `image` is a JPEG, PNG or WebP of the speaker in their setting, and the voice takes on the ambience of its background: a quiet room keeps it clean, and a busy street adds matching background sound. Send it without `gender` or `age`, which are otherwise detected from the recording.

Use MP3 or WAV for uploaded assets and inline base64, with `audio/mpeg` or `audio/wav` for inline data. OGG is supported through a public audio URL; `audio/ogg` inline data and OGG assets are not accepted.

About the recording: about 1 minute of clear speech gives the best voice, and only the first 3 minutes are used. A file can be up to 100 MiB, or 16 MB after decoding for inline base64. A URL must point at the audio file itself and download within 30 seconds; HeyGen fetches it after returning `202`, and a fetch failure ends the voice `FAILED` with `INVALID_AUDIO`. A silent recording fails. Record in a quiet room without echo: the voice keeps the room sound of the recording, and keeps more of it at `extra_high` and `max` than at `medium`.

An instant voice cannot be retrained. To change it, create a new one.

`Idempotency-Key` is optional. Reusing a key within 24 hours returns the first response, and a duplicate that arrives while the first is still being accepted returns `409 request_in_progress`. Without the header, each retry creates a new voice.

## 2. Wait until it is ACTIVE

Poll [`GET /v3/models/audio/voices/{voice_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-an-audio-voice) until `status` is `ACTIVE` or `FAILED`. `PENDING` means HeyGen is checking and cleaning the recording. `FAILED` is final, and `failure_reason` says why:

| `failure_reason` | Meaning |
| - | - |
| `INVALID_AUDIO` | The recording could not be fetched or read. |
| `PREPROCESSING_FAILED` | The recording did not pass the checks. Without `language`, it can also mean the language could not be detected. Send `language` to rule that out. |
| `DESIGN_FAILED` | The recording passed the checks, but no voice could be made from it. |
| `INTERNAL_ERROR` | Something failed on HeyGen's side. Try again. |

A voice created without `language` has no `language` field until HeyGen detects it. A failed voice stays in the list as `FAILED` until you delete it.

Wait for `ACTIVE` before you generate speech. A speech request for a `PENDING` voice returns `409 voice_not_ready`: keep polling, and send it once the voice is `ACTIVE`.

## 3. Generate speech

Once the voice is `ACTIVE`, pass it to [Text to Speech](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md). [`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) returns one 44.1 kHz WAV; [`POST /v3/models/audio/tts/stream`](https://heygen-1fa696a7.mintlify.site/reference/stream-speech) streams audio parts over Server-Sent Events from the same body. To speak a recording again in the voice instead, use [Speech to Speech](https://heygen-1fa696a7.mintlify.site/docs/voices/speech-to-speech.md).

An instant voice takes `expressiveness_boost` and [audio tags](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-audio-tags.md); `seed`, `speed`, `pitch_shift` and `pitch_variance` apply too, and a `<break>` tag returns `400 invalid_parameter`. See [request fields](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md#request-fields).

## Languages

Cloning and speech support the same languages. See [Supported languages](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md#supported-languages).

## Manage voices

[`GET /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices) lists the workspace's instant and professional voices, newest first; `mode` tells them apart. Paging and `type=public` are on [Voices](https://heygen-1fa696a7.mintlify.site/docs/voices/overview.md). Any workspace can read and speak a public voice, but not delete it.

Each `ACTIVE` voice in the list and in [`GET /v3/models/audio/voices/{voice_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-an-audio-voice) has a `preview_audio_url`: a WAV of the voice reading a short fixed preview script in its language, about 15 seconds. The URL can expire, so read the voice again rather than storing it. It is `null` while a voice is not `ACTIVE`.

[`DELETE /v3/models/audio/voices/{voice_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-an-audio-voice) deletes a voice. Deleting an instant voice that is still `PENDING` cancels it.

## Errors

| HTTP status | Error code | Meaning |
| - | - | - |
| `400` | `invalid_parameter` | A missing, unknown, or invalid field, more than one `audio` item, an unsupported `language`, or `image` sent together with `gender` or `age`. |
| `403` | `resource_access_denied` | The workspace is not allowed to create voice clones. |
| `409` | `request_in_progress` | The same `Idempotency-Key` is still being accepted. Retry with backoff. |
| `429` | `rate_limit_exceeded` | Retry after the seconds in `Retry-After`. |

Speech errors are 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.