Create Lipsync

POST

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": "url",
    "url": "<string>"
  },
  "audio": {
    "type": "url",
    "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": "url",
        "url": "<string>"
    },
    "audio": {
        "type": "url",
        "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: 'url', url: '<string>'},
    audio: {type: 'url', 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' => 'url',
        'url' => '<string>'
    ],
    'audio' => [
        'type' => 'url',
        '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\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"audio\": {\n    \"type\": \"url\",\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\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"audio\": {\n    \"type\": \"url\",\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\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"audio\": {\n    \"type\": \"url\",\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": "unauthorized",
    "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.

AssetUrl
AssetId

Show child attributes

audio

AssetUrl · object

required

Asset input via publicly accessible HTTPS URL.

AssetUrl
AssetId

Show child attributes

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

deprecated

Deprecated and ignored: captions are always generated; whether to display them is a download-side choice.

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

Destination folder ID in the caller's workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to. Assets library folders are accepted, but the HeyGen app files only assets in them, so a result placed there may not appear in the Assets library view. An unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created.

Response

Successful response

data

LipsyncCreateResponse · object

Response for POST /v3/lipsyncs.

Show child attributes

⌘I

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": "url",
    "url": "<string>"
  },
  "audio": {
    "type": "url",
    "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": "url",
        "url": "<string>"
    },
    "audio": {
        "type": "url",
        "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: 'url', url: '<string>'},
    audio: {type: 'url', 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' => 'url',
        'url' => '<string>'
    ],
    'audio' => [
        'type' => 'url',
        '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\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"audio\": {\n    \"type\": \"url\",\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\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"audio\": {\n    \"type\": \"url\",\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\": \"url\",\n    \"url\": \"<string>\"\n  },\n  \"audio\": {\n    \"type\": \"url\",\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": "unauthorized",
    "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
  }
}

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

Authorizations

Headers

Body

Response