Lipsync - Precision - HeyGen Documentation

Endpoint: POST /v3/lipsyncs
Purpose: Dub or replace audio on a video with high-accuracy lip-sync. The job runs asynchronously — poll via Get Lipsync or use a callback_url (Webhooks).
For faster, lower-fidelity lipsync, see Speed mode. For many videos in one job, see Lipsync batches.

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` — see Upload 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 /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 /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 /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 /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 (see Upload Assets):

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

​Quick Example

​Request Body

​Response

​Get Lipsync Details

​Quick Example

​Path Parameters

​Response

​Response Fields

​List Lipsyncs

​Quick Example

​Query Parameters

​Response

​Update Lipsync

​Quick Example

​Request Body

​Delete Lipsync

​Quick Example

​Response

​CLI Usage

​Polling Pattern

​Asset Inputs

Quick Example

Request Body

Response

Get Lipsync Details

Quick Example

Path Parameters

Response

Response Fields

List Lipsyncs

Quick Example

Query Parameters

Response

Update Lipsync

Quick Example

Request Body

Delete Lipsync

Quick Example

Response

CLI Usage

Polling Pattern

Asset Inputs