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

# HeyGen Instant Clone

> Clone a speaker's voice from a single audio recording in minutes with HeyGen's Starfish engine, then use it for text-to-speech and avatar videos.

<img className="w-full h-44 object-cover rounded-xl" src="https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-2.webp?fit=max&auto=format&n=hfMXXwJzjE7vBSYZ&q=85&s=d6ee10585b27ddaf8137d6ed67791708" alt="" noZoom width="1400" height="788" data-path="images/theme/research-2.webp" />

Full schema: [`POST /v3/voices/clone`](/reference/clone-a-voice).

<Warning>
  HeyGen instant clones run on the **Starfish engine only**. The resulting voice works wherever Starfish-compatible voices do — see [Text to Speech](/docs/voices/speech).
</Warning>

Instant voice cloning creates a usable voice from a single recording in minutes. For a studio-grade clone trained on the [HeyGen Voice](/docs/models/heygen-voice) model, see [HeyGen Professional Clone](/docs/voices/professional-voice-clone). Instant cloning on third-party voice engines is coming soon.

## Quick Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.heygen.com/v3/voices/clone" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "voice_name": "Customer narrator",
      "audio": {
        "type": "url",
        "url": "https://example.com/recording.wav"
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.heygen.com/v3/voices/clone",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={
          "voice_name": "Customer narrator",
          "audio": {"type": "url", "url": "https://example.com/recording.wav"},
      },
  )
  voice_clone_id = resp.json()["data"]["voice_clone_id"]
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch("https://api.heygen.com/v3/voices/clone", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      voice_name: "Customer narrator",
      audio: { type: "url", url: "https://example.com/recording.wav" },
    }),
  });
  const { voice_clone_id } = (await resp.json()).data;
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "voice_clone_id": "1bd001e7e50f421d891986aad5c8bbd2"
  }
}
```

## Request fields

| Field                     | Type    | Required | Description                                                     |
| ------------------------- | ------- | -------- | --------------------------------------------------------------- |
| `voice_name`              | string  | Yes      | Display name for the cloned voice, up to 100 characters.        |
| `audio`                   | object  | Yes      | The source recording. Provide one of the three forms below.     |
| `language`                | string  | No       | Language hint such as `en` or `es`. Auto-detected when omitted. |
| `remove_background_noise` | boolean | No       | Clean up background noise before cloning. Defaults to `true`.   |

The `audio` object supports one of these forms:

<CodeGroup>
  ```json Public HTTPS URL theme={null}
  {
    "type": "url",
    "url": "https://example.com/recording.wav"
  }
  ```

  ```json HeyGen asset theme={null}
  {
    "type": "asset_id",
    "asset_id": "your_asset_id"
  }
  ```

  ```json Base64 audio theme={null}
  {
    "type": "base64",
    "media_type": "audio/wav",
    "data": "UklGR..."
  }
  ```
</CodeGroup>

For local files, upload the recording with the [Assets API](/docs/upload-assets) first and pass the returned `asset_id`.

## Poll clone status

Cloning runs asynchronously. Poll [`GET /v3/voices/{voice_clone_id}`](/reference/get-voice) until `status` is `complete`:

```bash theme={null}
curl "https://api.heygen.com/v3/voices/1bd001e7e50f421d891986aad5c8bbd2" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

| Status       | Meaning                                                       |
| ------------ | ------------------------------------------------------------- |
| `processing` | The clone is still being created.                             |
| `complete`   | The voice is ready to use.                                    |
| `failed`     | Cloning ended unsuccessfully. Retry with a cleaner recording. |

## Use the voice

Once `complete`, the `voice_clone_id` works anywhere a `voice_id` does: pass it to [Text to Speech](/docs/voices/speech) for standalone audio, or to [`POST /v3/videos`](/reference/create-video) to narrate an avatar video. Cloned voices appear in [`GET /v3/voices`](/reference/list-voices) with `type=private` — see [Browse Voices](/docs/voices/search-voices).