Instant Voice Clone

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.

Create the voice
Wait until it is ACTIVE
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://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. 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. Free-plan workspaces can make 20 clone calls per rolling 24 hours by default, shared by all members.

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

audio takes exactly one recording. name is 1–64 characters, and language is detected from the recording when omitted (see 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} 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. 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. To speak a recording again in the voice instead, use Speech to Speech. An instant voice takes expressiveness_boost and audio tags; it ignores the professional-only seed, speed, pitch_shift and pitch_variance, and a <break> tag returns 400 invalid_parameter. See request fields.

Languages

Cloning and speech support the same languages. See Supported languages.

Manage voices

GET /v3/models/audio/voices lists the workspace’s instant and professional voices, newest first; mode tells them apart. Paging and type=public are on Voices. 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} 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} 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. The full catalog is in Error Codes.

Get started

Video

Avatar

Voice

Audio

Image

Decision

Video editing

Brand

Platform