Skip to main content
POST
/
v3
/
lipsyncs
Create Lipsync
curl --request POST \
  --url https://api.heygen.com/v3/lipsyncs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "video": {
    "type": "<string>",
    "url": "<string>"
  },
  "audio": {
    "type": "<string>",
    "url": "<string>"
  },
  "title": "<string>",
  "mode": "speed",
  "callback_url": "<string>",
  "callback_id": "<string>",
  "enable_caption": false,
  "keep_the_same_format": true,
  "enable_dynamic_duration": true,
  "disable_music_track": false,
  "enable_speech_enhancement": false,
  "enable_watermark": false,
  "start_time": 123,
  "end_time": 123,
  "fps_mode": "<string>",
  "folder_id": "<string>"
}
'
import requests

url = "https://api.heygen.com/v3/lipsyncs"

payload = {
"video": {
"type": "<string>",
"url": "<string>"
},
"audio": {
"type": "<string>",
"url": "<string>"
},
"title": "<string>",
"mode": "speed",
"callback_url": "<string>",
"callback_id": "<string>",
"enable_caption": False,
"keep_the_same_format": True,
"enable_dynamic_duration": True,
"disable_music_track": False,
"enable_speech_enhancement": False,
"enable_watermark": False,
"start_time": 123,
"end_time": 123,
"fps_mode": "<string>",
"folder_id": "<string>"
}
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({
video: {type: '<string>', url: '<string>'},
audio: {type: '<string>', url: '<string>'},
title: '<string>',
mode: 'speed',
callback_url: '<string>',
callback_id: '<string>',
enable_caption: false,
keep_the_same_format: true,
enable_dynamic_duration: true,
disable_music_track: false,
enable_speech_enhancement: false,
enable_watermark: false,
start_time: 123,
end_time: 123,
fps_mode: '<string>',
folder_id: '<string>'
})
};

fetch('https://api.heygen.com/v3/lipsyncs', 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/lipsyncs",
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([
'video' => [
'type' => '<string>',
'url' => '<string>'
],
'audio' => [
'type' => '<string>',
'url' => '<string>'
],
'title' => '<string>',
'mode' => 'speed',
'callback_url' => '<string>',
'callback_id' => '<string>',
'enable_caption' => false,
'keep_the_same_format' => true,
'enable_dynamic_duration' => true,
'disable_music_track' => false,
'enable_speech_enhancement' => false,
'enable_watermark' => false,
'start_time' => 123,
'end_time' => 123,
'fps_mode' => '<string>',
'folder_id' => '<string>'
]),
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/lipsyncs"

payload := strings.NewReader("{\n \"video\": {\n \"type\": \"<string>\",\n \"url\": \"<string>\"\n },\n \"audio\": {\n \"type\": \"<string>\",\n \"url\": \"<string>\"\n },\n \"title\": \"<string>\",\n \"mode\": \"speed\",\n \"callback_url\": \"<string>\",\n \"callback_id\": \"<string>\",\n \"enable_caption\": false,\n \"keep_the_same_format\": true,\n \"enable_dynamic_duration\": true,\n \"disable_music_track\": false,\n \"enable_speech_enhancement\": false,\n \"enable_watermark\": false,\n \"start_time\": 123,\n \"end_time\": 123,\n \"fps_mode\": \"<string>\",\n \"folder_id\": \"<string>\"\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/lipsyncs")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"video\": {\n \"type\": \"<string>\",\n \"url\": \"<string>\"\n },\n \"audio\": {\n \"type\": \"<string>\",\n \"url\": \"<string>\"\n },\n \"title\": \"<string>\",\n \"mode\": \"speed\",\n \"callback_url\": \"<string>\",\n \"callback_id\": \"<string>\",\n \"enable_caption\": false,\n \"keep_the_same_format\": true,\n \"enable_dynamic_duration\": true,\n \"disable_music_track\": false,\n \"enable_speech_enhancement\": false,\n \"enable_watermark\": false,\n \"start_time\": 123,\n \"end_time\": 123,\n \"fps_mode\": \"<string>\",\n \"folder_id\": \"<string>\"\n}")
.asString();
require 'uri'
require 'net/http'

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

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 \"video\": {\n \"type\": \"<string>\",\n \"url\": \"<string>\"\n },\n \"audio\": {\n \"type\": \"<string>\",\n \"url\": \"<string>\"\n },\n \"title\": \"<string>\",\n \"mode\": \"speed\",\n \"callback_url\": \"<string>\",\n \"callback_id\": \"<string>\",\n \"enable_caption\": false,\n \"keep_the_same_format\": true,\n \"enable_dynamic_duration\": true,\n \"disable_music_track\": false,\n \"enable_speech_enhancement\": false,\n \"enable_watermark\": false,\n \"start_time\": 123,\n \"end_time\": 123,\n \"fps_mode\": \"<string>\",\n \"folder_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body
{
  "data": {
    "lipsync_id": "<string>"
  }
}
{
"error": {
"code": "invalid_parameter",
"message": "'video_url' is required.",
"param": "video_url",
"doc_url": null
}
}
{
"error": {
"code": "authentication_failed",
"message": "Invalid or expired API key. Verify your x-api-key header.",
"param": null,
"doc_url": null
}
}
{
"error": {
"code": "request_in_progress",
"message": "A request with this Idempotency-Key is already in progress. Retry shortly.",
"param": null,
"doc_url": null
}
}
{
"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.

Headers

Idempotency-Key
string

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

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

Body

application/json

Request body for POST /v3/lipsyncs.

video
AssetUrl · object
required

Asset input via publicly accessible HTTPS URL.

audio
AssetUrl · object
required

Asset input via publicly accessible HTTPS URL.

title
string | null

Title for the lipsync job

mode
enum<string>
default:speed

Quality mode: 'speed' (faster) or 'precision' (higher quality, uses avatar inference)

Available options:
speed,
precision
callback_url
string | null

Webhook URL for completion notifications

callback_id
string | null

ID included in webhook payload

enable_caption
boolean
default:false

Generate captions for the output video

keep_the_same_format
boolean | null

Preserve the source video's encoding specs (resolution, bitrate).

enable_dynamic_duration
boolean
default:true

Allow dynamic duration adjustment

disable_music_track
boolean
default:false

Remove background music

enable_speech_enhancement
boolean
default:false

Enhance speech quality

enable_watermark
boolean
default:false

Add watermark to output

start_time
number | null

Start time in seconds for partial lipsync

end_time
number | null

End time in seconds for partial lipsync

fps_mode
string | null

Frame rate mode: 'vfr', 'cfr', or 'passthrough'.

folder_id
string | null

Project/folder ID to organize lipsync into

Response

Successful response

data
LipsyncCreateResponse · object

Response for POST /v3/lipsyncs.