Lipsync - Precision

Replace or dub audio on an existing video with high-accuracy avatar-inference lip-sync.

• Endpoint: POST https://api.heygen.com/v3/lipsyncs
• Purpose: Dub or replace audio on a video with high-accuracy lip-sync. The job runs asynchronously — poll status via the Get Lipsync Details endpoint.

Quick Example

curl -X POST "https://api.heygen.com/v3/lipsyncs" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": { "type": "url", "url": "https://example.com/source.mp4" },
    "audio": { "type": "url", "url": "https://example.com/new-audio.mp3" },
    "mode": "precision"
  }'

Request Body

Parameter	Type	Required	Default	Description
video	object	Yes	—	Source video. Provide as { "type": "url", "url": "https://..." } or { "type": "asset_id", "asset_id": "..." } (from POST /v3/assets).
audio	object	Yes	—	Replacement audio. Same format options as video.
mode	string	No	—	Set to "precision" for avatar-inference lip-sync.
title	string	No	—	Display title for the lipsync in the HeyGen dashboard.
enable_caption	boolean	No	false	Generate captions for the output video.
enable_dynamic_duration	boolean	No	true	Allow output duration to adjust to match the new audio length.
disable_music_track	boolean	No	false	Strip background music from the source video.
enable_speech_enhancement	boolean	No	false	Enhance speech quality in the output.
enable_watermark	boolean	No	false	Add a watermark to the output.
start_time	number	No	—	Start time in seconds for partial lipsync.
end_time	number	No	—	End time in seconds for partial lipsync.
keep_the_same_format	boolean	No	—	Preserve the source video’s resolution and bitrate.
fps_mode	string	No	—	Frame rate mode: "vfr", "cfr", or "passthrough".
callback_url	string	No	—	Webhook URL — receives a POST when the job completes or fails.
callback_id	string	No	—	Arbitrary ID echoed back in the webhook payload.
folder_id	string	No	—	Organize the lipsync into a specific project folder.

Response

{
  "data": {
    "lipsync_id": "ls_abc123"
  }
}

Field	Type	Description
lipsync_id	string	Unique identifier. Use with GET /v3/lipsyncs/{lipsync_id} to poll status.

Get Lipsync Details

• Endpoint: GET https://api.heygen.com/v3/lipsyncs/{lipsync_id}
• Purpose: Get detailed information about a lipsync including status, download URL, and metadata.

Quick Example

curl -X GET "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Path Parameters

Parameter	Type	Required	Description
lipsync_id	string	Yes	Unique lipsync identifier.

Response

{
  "data": {
    "id": "ls_abc123",
    "title": "My Lipsync",
    "status": "completed",
    "duration": 42.5,
    "video_url": "https://files.heygen.ai/...",
    "callback_id": null,
    "created_at": 1717000000,
    "failure_message": null
  }
}

Response Fields

Field	Type	Description
id	string	Unique lipsync identifier.
title	string or null	Display title.
status	string	Current status: "pending", "running", "completed", or "failed".
duration	number or null	Video duration in seconds. Present when completed.
video_url	string or null	Presigned download URL for the output video. Only present when status is "completed".
callback_id	string or null	Client-provided callback ID.
created_at	integer or null	Unix timestamp of creation.
failure_message	string or null	Error description. Only present when status is "failed".

List Lipsyncs

• Endpoint: GET https://api.heygen.com/v3/lipsyncs
• Purpose: List lipsyncs with cursor-based pagination.

Quick Example

curl -X GET "https://api.heygen.com/v3/lipsyncs?limit=10" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Query Parameters

Parameter	Type	Required	Default	Description
limit	integer	No	10	Results per page (1–100).
token	string	No	—	Opaque cursor token for the next page.

Response

{
  "data": [
    {
      "id": "ls_abc123",
      "title": "My Lipsync",
      "status": "completed",
      "duration": 42.5,
      "video_url": "https://files.heygen.ai/...",
      "created_at": 1717000000
    }
  ],
  "has_more": false,
  "next_token": null
}

Update Lipsync

• Endpoint: PATCH https://api.heygen.com/v3/lipsyncs/{lipsync_id}
• Purpose: Update a lipsync’s title.

Quick Example

curl -X PATCH "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Title" }'

Request Body

Parameter	Type	Required	Description
title	string	Yes	New title for the lipsync.

Delete Lipsync

• Endpoint: DELETE https://api.heygen.com/v3/lipsyncs/{lipsync_id}
• Purpose: Permanently delete a lipsync.

Quick Example

curl -X DELETE "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Response

{
  "data": {
    "id": "ls_abc123"
  }
}

CLI Usage

# Create with precision mode
heygen lipsync create -d '{
  "video": {"type": "url", "url": "https://example.com/source.mp4"},
  "audio": {"type": "url", "url": "https://example.com/new-audio.mp3"},
  "mode": "precision"
}' --wait

# Poll status manually
heygen lipsync get <lipsync-id>

# List lipsyncs
heygen lipsync list --limit 10

# Update title
heygen lipsync update <lipsync-id> --title "Updated Title"

# Delete
heygen lipsync delete <lipsync-id> --force

Use --request-schema to see all available request fields without needing auth:

heygen lipsync create --request-schema

Polling Pattern

Lipsyncs are processed asynchronously. Poll until status reaches "completed" or "failed".

Status transitions: pending → running → completed | failed

while true; do
  STATUS=$(curl -s "https://api.heygen.com/v3/lipsyncs/ls_abc123" \
    -H "X-Api-Key: $HEYGEN_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 10
done

Or let the CLI handle polling for you:

heygen lipsync create -d '...' --wait --timeout 30m

Asset Inputs

Both video and audio fields accept two input formats:

By URL — any publicly accessible HTTPS link:

{ "type": "url", "url": "https://example.com/file.mp4" }

By asset ID — reference a file previously uploaded via POST /v3/assets:

{ "type": "asset_id", "asset_id": "asset_xyz789" }