> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Lipsync - Speed

> Run the HeyGen Lipsync API in speed mode for rapid lipsync drafts. Ideal for previewing edits, batch processing, and iterating on content before final render.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-6.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=9594373cd1f749008d16bd6e93f0f76b)

* Endpoint: [`POST /v3/lipsyncs`](https://heygen-1fa696a7.mintlify.site/reference/create-lipsync)
* Purpose: Dub or replace audio on a video. The job runs asynchronously: poll via [Get Lipsync](https://heygen-1fa696a7.mintlify.site/reference/get-lipsync.md) or use a `callback_url` ([Webhooks](https://heygen-1fa696a7.mintlify.site/docs/webhooks.md)).
* For higher fidelity, see [Precision mode](https://heygen-1fa696a7.mintlify.site/lipsync-precision.md). For many videos in one job, see [Lipsync batches](https://heygen-1fa696a7.mintlify.site/batch-lipsyncs.md).

Lipsync and [Video Translation](https://heygen-1fa696a7.mintlify.site/docs/video-translate.md) share **one lip sync engine** with Speed and Precision modes. Lipsync is the engine on its own: you bring the video *and* your own audio, and the engine redraws the mouth to match (dialogue replacement only). Video Translation generates translated audio first and optionally runs the engine after; see [how they relate](https://heygen-1fa696a7.mintlify.site/docs/video-translate.md#how-lip-sync-and-video-translation-relate).

### Quick Example

```bash theme={null}
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": "speed"
  }'
```

Both `video` and `audio` accept a publicly accessible HTTPS link (`{ "type": "url", "url": "..." }`) or a file uploaded via [`POST /v3/assets`](https://heygen-1fa696a7.mintlify.site/reference/upload-asset) (`{ "type": "asset_id", "asset_id": "..." }`, see [Upload Assets](https://heygen-1fa696a7.mintlify.site/docs/upload-assets.md)). The response returns a `lipsync_id`.

Optional fields cover captions, music stripping, speech enhancement, watermarking, partial lipsync with `start_time` and `end_time`, `keep_the_same_format` (preserve source resolution and bitrate), `fps_mode` (`"vfr"`, `"cfr"` or `"passthrough"`), `folder_id`, and `callback_url` / `callback_id`. `enable_dynamic_duration` (default `true`) lets output duration adjust to the new audio length. See the [create reference](https://heygen-1fa696a7.mintlify.site/reference/create-lipsync.md) for the full list.

## Manage Lipsyncs

* **Get:** [`GET /v3/lipsyncs/{lipsync_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-lipsync). `status` moves `pending` → `running` → `completed` | `failed`. The presigned `video_url` and `duration` appear on `completed`; `failure_message` appears on `failed`.
* **List:** [`GET /v3/lipsyncs`](https://heygen-1fa696a7.mintlify.site/reference/list-lipsyncs) with `limit` (1–100, default `10`) and the `token` cursor, paged with `has_more` and `next_token`.
* **Update:** [`PATCH /v3/lipsyncs/{lipsync_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-lipsync) changes the `title`.
* **Delete:** [`DELETE /v3/lipsyncs/{lipsync_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-lipsync) permanently deletes a lipsync.

## CLI Usage

The CLI wraps every call and can poll for you with `--wait`:

```bash theme={null}
# Create with speed mode and wait for the result
heygen lipsync create -d '{
  "video": {"type": "url", "url": "https://example.com/source.mp4"},
  "audio": {"type": "url", "url": "https://example.com/new-audio.mp3"},
  "mode": "speed"
}' --wait --timeout 30m

heygen lipsync get <lipsync-id>
heygen lipsync list --limit 10
heygen lipsync update <lipsync-id> --title "Updated Title"
heygen lipsync delete <lipsync-id> --force

# See all request fields without needing auth
heygen lipsync create --request-schema
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.