Clone a Voice

POST

voices

clone

Clone a Voice

curl --request POST \
  --url https://api.heygen.com/v3/voices/clone \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "audio": {
    "type": "<string>",
    "url": "<string>"
  },
  "voice_name": "<string>",
  "language": "<string>",
  "remove_background_noise": true
}
'

import requests

url = "https://api.heygen.com/v3/voices/clone"

payload = {
    "audio": {
        "type": "<string>",
        "url": "<string>"
    },
    "voice_name": "<string>",
    "language": "<string>",
    "remove_background_noise": True
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    audio: {type: '<string>', url: '<string>'},
    voice_name: '<string>',
    language: '<string>',
    remove_background_noise: true
  })
};

fetch('https://api.heygen.com/v3/voices/clone', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/voices/clone",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'audio' => [
        'type' => '<string>',
        'url' => '<string>'
    ],
    'voice_name' => '<string>',
    'language' => '<string>',
    'remove_background_noise' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heygen.com/v3/voices/clone"

	payload := strings.NewReader("{\n  \"audio\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"voice_name\": \"<string>\",\n  \"language\": \"<string>\",\n  \"remove_background_noise\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.heygen.com/v3/voices/clone")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"audio\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"voice_name\": \"<string>\",\n  \"language\": \"<string>\",\n  \"remove_background_noise\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/voices/clone")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"audio\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"voice_name\": \"<string>\",\n  \"language\": \"<string>\",\n  \"remove_background_noise\": true\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "voice_clone_id": "<string>"
  }
}

{
  "error": {
    "code": "resource_limit_reached",
    "message": "Voice clone limit reached (10). Delete unused clones or contact support to increase your limit."
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or expired API key. Verify your x-api-key header.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "plan_upgrade_required",
    "message": "Voice cloning is not available on the free tier. Please upgrade your plan."
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the duration specified in the Retry-After header.",
    "param": null,
    "doc_url": null
  }
}

Authorizations

x-api-key

string

header

required

HeyGen API key. Obtain from your HeyGen dashboard.

Body

application/json

Request body for POST /v3/voices/clone.

audio

AssetUrl · object

required

Asset input via publicly accessible HTTPS URL.

AssetUrl
AssetId
AssetBase64

Show child attributes

voice_name

string

required

Display name for the cloned voice.

Required string length: 1 - 100

language

string | null

Language hint for the voice (e.g., 'en', 'es'). Auto-detected if omitted.

remove_background_noise

boolean

default:true

Remove background noise from the audio before cloning.

Response

Successful response

data

VoiceCloneCreateV3Response · object

Response for POST /v3/voices/clone.

Show child attributes

⌘I

Clone a Voice

curl --request POST \
  --url https://api.heygen.com/v3/voices/clone \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "audio": {
    "type": "<string>",
    "url": "<string>"
  },
  "voice_name": "<string>",
  "language": "<string>",
  "remove_background_noise": true
}
'

import requests

url = "https://api.heygen.com/v3/voices/clone"

payload = {
    "audio": {
        "type": "<string>",
        "url": "<string>"
    },
    "voice_name": "<string>",
    "language": "<string>",
    "remove_background_noise": True
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    audio: {type: '<string>', url: '<string>'},
    voice_name: '<string>',
    language: '<string>',
    remove_background_noise: true
  })
};

fetch('https://api.heygen.com/v3/voices/clone', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.heygen.com/v3/voices/clone",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'audio' => [
        'type' => '<string>',
        'url' => '<string>'
    ],
    'voice_name' => '<string>',
    'language' => '<string>',
    'remove_background_noise' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.heygen.com/v3/voices/clone"

	payload := strings.NewReader("{\n  \"audio\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"voice_name\": \"<string>\",\n  \"language\": \"<string>\",\n  \"remove_background_noise\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.heygen.com/v3/voices/clone")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"audio\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"voice_name\": \"<string>\",\n  \"language\": \"<string>\",\n  \"remove_background_noise\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/voices/clone")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"audio\": {\n    \"type\": \"<string>\",\n    \"url\": \"<string>\"\n  },\n  \"voice_name\": \"<string>\",\n  \"language\": \"<string>\",\n  \"remove_background_noise\": true\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "voice_clone_id": "<string>"
  }
}

{
  "error": {
    "code": "resource_limit_reached",
    "message": "Voice clone limit reached (10). Delete unused clones or contact support to increase your limit."
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or expired API key. Verify your x-api-key header.",
    "param": null,
    "doc_url": null
  }
}

{
  "error": {
    "code": "plan_upgrade_required",
    "message": "Voice cloning is not available on the free tier. Please upgrade your plan."
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the duration specified in the Retry-After header.",
    "param": null,
    "doc_url": null
  }
}

Video Agent

Brand

Avatars

Audio

Voices

Videos

Templates

Video Translate

Lipsync

HyperFrames

User

Webhooks

Assets

AI Clipping

Filler Word Removal

Batches

Video Translation Batches

Lipsync Batches

Asset Batches

Authorizations

Body

Response