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.

One recording in, a voice out. POST /v3/models/audio/voices with "mode": "instant" returns a voice_id that is usually ACTIVE within seconds. No training and no voice clone slot.

1. Create the voice
2. Wait until it is ACTIVE
3. Generate speech

Set up with an agent

Not technical? Paste this into Claude Code, Codex, or Cursor and it walks you through every step on this page in your own terminal.

Prompt for your agent

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://app.heygen.com/developers/api 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): only the first 3 minutes are used, so 1 to 3 minutes of clear speech is ideal. 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 and their language, then call POST /v3/models/audio/tts with model heygen-voice-1, the voice_id, text and language. Download the WAV and open it so I can listen. Show me how to change the text and run it again. Never send seed, speed or pitch for an instant voice.

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 and pass its asset_id, or send a public HTTPS URL or base64 audio. The call returns 202 Accepted.

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

Response

{
  "data": {
    "voice_id": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234"
  }
}

Field	Type	Required	Description
mode	string	Yes	instant, lowercase.
name	string	Yes	Display name, 1–64 characters.
audio	array	Yes	Exactly one recording: { "type": "asset_id", "asset_id" }, { "type": "url", "url" }, or { "type": "base64", "media_type", "data" }.
language	string	No	Language code of the recording, such as en. See Languages. Detected from the recording when omitted.
similarity	string	No	How closely the voice follows the recording: medium, high, extra_high, or max. Default extra_high.
remove_background_noise	boolean	No	Clean the recording before cloning. Default true.
gender	string	No	male or female. Detected when omitted.
age	string	No	young or old. Detected when omitted.

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: only its 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.

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} until status is ACTIVE or FAILED.

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

Response

{
  "data": {
    "voice_id": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234",
    "mode": "instant",
    "name": "Customer narrator",
    "language": "en",
    "status": "ACTIVE",
    "created_at": 1791565200
  }
}

Status	Meaning
PENDING	HeyGen is checking and cleaning the recording.
ACTIVE	The voice can speak.
FAILED	Final. 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. POST /v3/models/audio/tts returns one 44.1 kHz WAV; POST /v3/models/audio/tts/stream streams audio parts over Server-Sent Events from the same body.

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": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234",
    "text": "Hello from my instant voice.",
    "language": "en"
  }'

An instant voice takes model, voice_id, text, language, and expressiveness_boost (0.0–1.0, default 1.0), plus with_timestamps on the stream. seed, speed, pitch_shift, pitch_variance, and <break> tags work with professional voices only and return 400 invalid_parameter for an instant voice.

Languages

Supported base language codes for cloning and speech are: ar, be, bg, ca, cs, da, de, el, en, es, fa, fi, fr, he, hi, hr, hu, id, it, ja, ko, mk, ms, nl, pl, pt, ro, ru, sk, sl, sr, sv, ta, th, tl, tr, uk, vi, zh. Speech also accepts regional tags such as en-US and fr-CA, which normalize to en and fr. A regional tag does not select a regional accent. Unsupported base languages, such as xx, return 400 invalid_parameter.

Manage voices

GET /v3/models/audio/voices lists the workspace’s instant and professional voices, newest first; mode tells them apart. Set limit from 1 to 100 (default 10) and pass next_token as token while has_more is true.

DELETE /v3/models/audio/voices/{voice_id} deletes a voice. Deleting an instant voice that is still PENDING cancels it.

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

Errors

HTTP status	Error code	Meaning
400	invalid_parameter	A missing, unknown, or invalid field, more than one audio item, or an unsupported language.
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. The full catalog is in Error Codes.