Create Lipsync

Replaces the audio on an existing video and re-animates the speaker’s lip movements to match the new audio. Use mode: ‘speed’ for fast output or ‘precision’ for high-quality lip-sync.

POST /v3/lipsyncs

Create Lipsync

cURL

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>"
}
'

200

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

Authorizations

ApiKeyAuthBearerAuth

x-api-key · string · header · required

HeyGen API key. Obtain from your HeyGen dashboard.

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

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

200

application/json

Successful response

data · LipsyncCreateResponse · object

Response for POST /v3/lipsyncs.

Show child attributes