---
title: "Create Lipsync Batch"
method: POST
path: "/v3/lipsyncs/batches"
tags: ["Lipsync Batches"]
---

# Create Lipsync Batch

`POST /v3/lipsyncs/batches`

Submit up to 100 lipsync payloads as a single batch. Each payload becomes one batch item, created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/lipsyncs/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch.

## Headers

- `Idempotency-Key` string

## Request body

- CreateLipsyncBatchRequest
  - `title` string, nullable — Display name for the batch, shown in the HeyGen app.
  - `callback_url` string, nullable — Webhook URL invoked once when every item in the batch reaches a terminal state.
  - `lipsyncs` CreateLipsyncRequest[], required — Lipsync payloads, identical in shape to POST /v3/lipsyncs. Each entry becomes exactly one batch item (no expansion); the item count is capped at 100.
    - `video` union, required — Source video — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}
      - AssetUrl — Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required — Input type discriminator
        - `url` string, required — Publicly accessible HTTPS URL for the asset
      - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required — Input type discriminator
        - `asset_id` string, required — HeyGen asset ID from the asset upload endpoint
    - `audio` union, required — Replacement audio — provide as {type: 'url', url: '...'} or {type: 'asset_id', asset_id: '...'}
      - AssetUrl — Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required — Input type discriminator
        - `url` string, required — Publicly accessible HTTPS URL for the asset
      - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required — Input type discriminator
        - `asset_id` string, required — HeyGen asset ID from the asset upload endpoint
    - `title` string, nullable — Title for the lipsync job
    - `mode` 'speed' | 'precision'
    - `callback_url` string, nullable — Webhook URL for completion notifications
    - `callback_id` string, nullable — ID included in webhook payload
    - `enable_caption` boolean — Generate captions for the output video
    - `keep_the_same_format` boolean, nullable — Preserve the source video's encoding specs (resolution, bitrate).
    - `enable_dynamic_duration` boolean — Allow dynamic duration adjustment
    - `disable_music_track` boolean — Remove background music
    - `enable_speech_enhancement` boolean — Enhance speech quality
    - `enable_watermark` boolean — Add watermark to output
    - `start_time` number, nullable — Start time in seconds for partial lipsync
    - `end_time` number, nullable — End time in seconds for partial lipsync
    - `fps_mode` string, nullable — Frame rate mode: 'vfr', 'cfr', or 'passthrough'.
    - `folder_id` string, nullable — Project/folder ID to organize lipsync into

## Response `202`

Accepted — submission acknowledged; poll for completion.

- object
  - `data` CreateLipsyncBatchResponse
    - `batch_id` string, required — Identifier of the created batch. Poll GET /v3/lipsyncs/batches/{batch_id} for progress.

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication failed
- `409` — A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/heygen/apis/heygen-external-api.md) · [All operations](https://skmtc.net/heygen/apis/heygen-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heygen/heygen-external-api/revisions/e2e54726e210/schema)