HEheygen
Lipsync

Create Lipsync

Changed on

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

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v3/lipsyncs
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Headers

Idempotency-Keystring

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.

Request body

titlestring nullable

Title for the lipsync job

mode'speed' | 'precision'
callback_urlstring nullable

Webhook URL for completion notifications

callback_idstring nullable

ID included in webhook payload

enable_captionboolean

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

keep_the_same_formatboolean nullable

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

enable_dynamic_durationboolean

Allow dynamic duration adjustment

disable_music_trackboolean

Remove background music

enable_speech_enhancementboolean

Enhance speech quality

enable_watermarkboolean

Add watermark to output

start_timenumber nullable

Start time in seconds for partial lipsync

end_timenumber nullable

End time in seconds for partial lipsync

fps_modestring nullable

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

folder_idstring nullable

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

Changes

  • 7dfa5e59b4f5Revision changes
    • info

      request property deprecated

    • info

      added asset_id url discriminator mapping keys to the request property

    • info

      added asset_id url discriminator mapping keys to the request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status