Models

Convert Speech

Convert a recording into an ACTIVE instant voice in your workspace. Professional voice clones are not supported. The words and timing stay the same. The response contains one WAV URL and its duration in seconds.

Use an API key with voices:write or an OAuth bearer token. OAuth requires a paid plan. The limit is 30 requests per minute per workspace member.

The source can contain up to 300 seconds of audio. Use a public HTTPS URL, an uploaded asset, or base64 audio. URL downloads must finish within 60 seconds. Set a client timeout of at least 160 seconds.

The optional model_id defaults to heygen-voice-sts-0. The optional seed requests best-effort repeatable generation. Set remove_background_noise to true to clean the source before conversion. This adds latency.

Send Idempotency-Key for safe retries. The same key and body replay the completed result without another charge for 24 hours. Keys are scoped to the workspace and this endpoint. A running request returns 409 request_in_progress. A different body with the same key returns 409 conflict. A keyed request continues after a client disconnect and can still be charged. Without a key, a disconnect before the charge cancels the request without a charge. After a timeout, wait before retrying with the same key. The conversion can still be running.

POST

models

audio

sts

Convert Speech

curl --request POST \
  --url https://api.heygen.com/v3/models/audio/sts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "voice_id": "<string>",
  "audio": {
    "type": "url",
    "url": "<string>"
  },
  "remove_background_noise": false,
  "seed": 2147483647,
  "model_id": "heygen-voice-sts-0"
}
'

import requests

url = "https://api.heygen.com/v3/models/audio/sts"

payload = {
    "voice_id": "<string>",
    "audio": {
        "type": "url",
        "url": "<string>"
    },
    "remove_background_noise": False,
    "seed": 2147483647,
    "model_id": "heygen-voice-sts-0"
}
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({
    voice_id: '<string>',
    audio: {type: 'url', url: '<string>'},
    remove_background_noise: false,
    seed: 2147483647,
    model_id: 'heygen-voice-sts-0'
  })
};

fetch('https://api.heygen.com/v3/models/audio/sts', 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/models/audio/sts",
  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([
    'voice_id' => '<string>',
    'audio' => [
        'type' => 'url',
        'url' => '<string>'
    ],
    'remove_background_noise' => false,
    'seed' => 2147483647,
    'model_id' => 'heygen-voice-sts-0'
  ]),
  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/models/audio/sts"

	payload := strings.NewReader("{\n  \"voice_id\": \"<string>\",\n  \"audio\": {\n    \"type\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"remove_background_noise\": false,\n  \"seed\": 2147483647,\n  \"model_id\": \"heygen-voice-sts-0\"\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/models/audio/sts")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"voice_id\": \"<string>\",\n  \"audio\": {\n    \"type\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"remove_background_noise\": false,\n  \"seed\": 2147483647,\n  \"model_id\": \"heygen-voice-sts-0\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/models/audio/sts")

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  \"voice_id\": \"<string>\",\n  \"audio\": {\n    \"type\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"remove_background_noise\": false,\n  \"seed\": 2147483647,\n  \"model_id\": \"heygen-voice-sts-0\"\n}"

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

{
  "data": {
    "audio_url": "<string>",
    "duration": 1
  }
}

Authorizations

x-api-key

string

header

required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

Idempotency-Key

string

Optional key, scoped to the workspace and this endpoint. The same key and body replay the result for 24 hours without another charge. A different body returns 409 conflict. A running request returns 409 request_in_progress.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body

application/json

voice_id

string

required

Identifier of the voice to speak in: a voice clone the caller's workspace owns.

Required string length: 1 - 256

audio

AssetUrl · object

required

Asset input via publicly accessible HTTPS URL.

AssetUrl
AssetId
AssetBase64

Show child attributes

remove_background_noise

boolean

default:false

Remove background noise from the source before converting it. This adds latency.

seed

integer | null

Optional best-effort deterministic generation seed.

Required range: 0 <= x <= 4294967295

model_id

enum<string> | null

The speech-to-speech model. heygen-voice-sts-0 is the only one, and the default.

Available options:

heygen-voice-sts-0

Response

Converted speech. The audio_url points to a WAV. Duration is in seconds and matches the source.

data

CreateSpeechConversionResponseData · object

Show child attributes

⌘I

Convert Speech

curl --request POST \
  --url https://api.heygen.com/v3/models/audio/sts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "voice_id": "<string>",
  "audio": {
    "type": "url",
    "url": "<string>"
  },
  "remove_background_noise": false,
  "seed": 2147483647,
  "model_id": "heygen-voice-sts-0"
}
'

import requests

url = "https://api.heygen.com/v3/models/audio/sts"

payload = {
    "voice_id": "<string>",
    "audio": {
        "type": "url",
        "url": "<string>"
    },
    "remove_background_noise": False,
    "seed": 2147483647,
    "model_id": "heygen-voice-sts-0"
}
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({
    voice_id: '<string>',
    audio: {type: 'url', url: '<string>'},
    remove_background_noise: false,
    seed: 2147483647,
    model_id: 'heygen-voice-sts-0'
  })
};

fetch('https://api.heygen.com/v3/models/audio/sts', 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/models/audio/sts",
  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([
    'voice_id' => '<string>',
    'audio' => [
        'type' => 'url',
        'url' => '<string>'
    ],
    'remove_background_noise' => false,
    'seed' => 2147483647,
    'model_id' => 'heygen-voice-sts-0'
  ]),
  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/models/audio/sts"

	payload := strings.NewReader("{\n  \"voice_id\": \"<string>\",\n  \"audio\": {\n    \"type\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"remove_background_noise\": false,\n  \"seed\": 2147483647,\n  \"model_id\": \"heygen-voice-sts-0\"\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/models/audio/sts")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"voice_id\": \"<string>\",\n  \"audio\": {\n    \"type\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"remove_background_noise\": false,\n  \"seed\": 2147483647,\n  \"model_id\": \"heygen-voice-sts-0\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/models/audio/sts")

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  \"voice_id\": \"<string>\",\n  \"audio\": {\n    \"type\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"remove_background_noise\": false,\n  \"seed\": 2147483647,\n  \"model_id\": \"heygen-voice-sts-0\"\n}"

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

{
  "data": {
    "audio_url": "<string>",
    "duration": 1
  }
}

Video Agent

Brand

Avatars

Audio

Voices

Models

Videos

Templates

Video Translate

Lipsync

HyperFrames

User

API Keys

Webhooks

Folders

Assets

AI Clipping

Filler Word Removal

Batches

Video Translation Batches

Lipsync Batches

Asset Batches

Convert Speech

Authorizations

Headers

Body

Response