> ## 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.

# Lipsyncs

> Submit up to 100 lipsync requests in a single call. Re-sync many videos to new audio tracks together, then poll one batch id for per-item progress.

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

## Overview

Lipsync batches let you submit many lipsync jobs in one request instead of calling [`POST /v3/lipsyncs`](https://heygen-1fa696a7.mintlify.site/reference/create-lipsync) once per job. Each item is a standard lipsync payload, the exact shape that endpoint accepts, so anything you can lipsync on its own can be batched, in either [Speed](https://heygen-1fa696a7.mintlify.site/lipsync-speed.md) or [Precision](https://heygen-1fa696a7.mintlify.site/lipsync-precision.md) mode. Batch mechanics (`202 Accepted`, `title`, `callback_url`, `Idempotency-Key`, the batch read model and pagination) match [video batches](https://heygen-1fa696a7.mintlify.site/batch-videos.md).

> [!NOTE]
>
> A batch holds up to **100** items. Each payload becomes exactly one batch item, and each item is created and processed independently, so one bad source does not fail the rest.

## Create a Batch

[`POST /v3/lipsyncs/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-lipsync-batch) takes 1 to 100 payloads in `lipsyncs`:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/lipsyncs/batches" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Course module redubs",
    "callback_url": "https://example.com/hooks/heygen",
    "lipsyncs": [
      {
        "video": { "type": "url", "url": "https://example.com/module-1.mp4" },
        "audio": { "type": "url", "url": "https://example.com/module-1-v2.mp3" },
        "title": "Module 1, updated narration",
        "mode": "speed"
      },
      {
        "video": { "type": "asset_id", "asset_id": "asset_abc123" },
        "audio": { "type": "asset_id", "asset_id": "asset_def456" },
        "title": "Module 2, updated narration",
        "mode": "precision"
      }
    ]
  }'
```

Each entry takes the full set of lipsync options: `video` and `audio` (each as a `url` or `asset_id`), `mode` (`speed` or `precision`), plus captions, partial-range, and format controls.

## Get a Batch

Poll [`GET /v3/lipsyncs/batches/{batch_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-lipsync-batch). The response shape matches the [video batch](https://heygen-1fa696a7.mintlify.site/batch-videos.md#response-fields).

> [!NOTE]
>
> The batch read model is shared across the batch APIs, so the per-item id field is named `video_id`. For lipsync batches it holds the **lipsync id**. Use it with [`GET /v3/lipsyncs/{lipsync_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-lipsync) for the full record and download URL.

## Bulk Statuses

[`GET /v3/lipsyncs/statuses`](https://heygen-1fa696a7.mintlify.site/reference/bulk-lipsync-statuses) checks up to 100 lipsyncs in one request, across batches or for jobs created individually. Pass comma-separated `lipsync_ids`, or `batch_ids` (each expands to its member lipsyncs). Statuses are `queued`, `processing`, `completed`, or `failed`, plus `not_found` for unknown or unowned ids.

Items surface their lipsync id as soon as the job is created, so you can start fetching finished renders while the rest of the batch is still processing.


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