Name: HeyGen Lipsync Speed Video Dubbing API
Brand: magicapi
SKU: api-magicapi-fast-lip-sync-video-heygen-lipsync-speed
Availability: InStock
Author: API Market

Shashank Agarwal

# 🗣️ Fast Lipsync Video Dubbing API (HeyGen Lipsync Speed)

## Overview
HeyGen Lipsync Speed replaces or dubs the audio on a video. You send a source video and a replacement audio file, and the model re-animates the lip movements in the video to match the new audio. Its developer describes it as fast, audio-driven lip sync for replacing or dubbing audio on any video.

Only `video` and `audio` are required. Optional switches strip background music from the source video, enhance speech in the output and let the output length adjust to the new audio. Each request returns the URL of one MP4 video.

## Features
- **Lipsync to new audio**: `video` is the source video to lip-sync and `audio` is the replacement audio file. Both are passed as URLs.
- **Dynamic duration**: `enable_dynamic_duration` (default `true`) allows the output duration to adjust to match the new audio length.
- **Background music removal**: set `disable_music_track` to `true` to strip background music from the source video (default `false`).
- **Speech enhancement**: set `enable_speech_enhancement` to `true` to enhance speech quality in the output (default `false`).

## Use Cases
1. **Dubbing and localization**: match a speaker's lips to a translated voice track.
2. **Dialogue fixes**: replace a line of dialogue after recording without reshooting.
3. **Presenters and avatars**: make a recorded or generated presenter speak a new script.
4. **Personalized video messages**: reuse one recording with different audio for each recipient.

## Visual Examples
### Example Input
- `video`: [Watch the input video](https://blog.api.market/wp-content/uploads/2026/10/lipsync-input-talk-api-market.mp4), a short talking video.
- `audio`: [Listen to the input audio](https://blog.api.market/wp-content/uploads/2026/10/realtime-tts-1.5-max-output-api-market.mp3), a speech clip of about 5.4 seconds.

All other fields were left at their defaults (`enable_dynamic_duration` `true`, `disable_music_track` `false`, `enable_speech_enhancement` `false`).

About the inputs: the video and audio must be close in length. In our testing, an 8.04 second video with a 5.42 second audio clip was rejected with the message that the two durations can differ by at most 15%. For this example the source video was trimmed to about the length of the speech.

### Example Output
[Watch the example output](https://blog.api.market/wp-content/uploads/2026/10/lipsync-speed-output-api-market.mp4)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `video` | string (URL) | Yes |  |  | Source video file to lip-sync. |
| `audio` | string (URL) | Yes |  |  | Replacement audio file. The video's lip movements will be re-animated to match this audio. |
| `enable_dynamic_duration` | boolean | No | `true` |  | Allow the 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. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.042 per API unit.
- **1 API unit = 1 second of output video**, rounded up per request. You are billed on the length of the output video. There is no `duration` field: the output length follows your inputs, and with `enable_dynamic_duration` on (the default) it follows the length of the new audio.
- **Worked example**: a 5 second output video is 5 units = $0.21. A 10 second output video is 10 units = $0.42.
- **The example above**: the audio is about 5.4 seconds long, so the output is about 5.4 seconds, which rounds up to 6 units = $0.252.
- Music removal and speech enhancement do not change the price per second.
- **Failed or cancelled predictions are not billed**, including requests rejected because the video and audio lengths differ too much.
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/fast-lip-sync-video-heygen-lipsync-speed`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/fast-lip-sync-video-heygen-lipsync-speed/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "8eabe9f38713e9d89951ada8ee7a9f40c1d7260b5145d3bd3f03fd7dfc50c967",
    "input": {
      "video": "https://blog.api.market/wp-content/uploads/2026/10/lipsync-input-talk-api-market.mp4",
      "audio": "https://blog.api.market/wp-content/uploads/2026/10/realtime-tts-1.5-max-output-api-market.mp3"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "cpe752mvbnrmw0d17ge92dqstw",
  "version": "8eabe9f38713e9d89951ada8ee7a9f40c1d7260b5145d3bd3f03fd7dfc50c967",
  "status": "starting",
  "created_at": "2026-10-14T20:31:10.310Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/fast-lip-sync-video-heygen-lipsync-speed/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "cpe752mvbnrmw0d17ge92dqstw",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/lipsync-speed-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-14T20:31:10.310Z",
  "started_at": "2026-10-14T20:31:11.310Z",
  "completed_at": "2026-10-14T20:32:10.310Z"
}
```

`output` is a single URL string pointing to the lip-synced MP4 video.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `video` or `audio`.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. For example, when the video and audio lengths differ by more than 15%, the prediction fails with a `duration_mismatch` message. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400 or a failed prediction.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/fast-lip-sync-video-heygen-lipsync-speed";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "8eabe9f38713e9d89951ada8ee7a9f40c1d7260b5145d3bd3f03fd7dfc50c967", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "video": "https://blog.api.market/wp-content/uploads/2026/10/lipsync-input-talk-api-market.mp4",
  "audio": "https://blog.api.market/wp-content/uploads/2026/10/realtime-tts-1.5-max-output-api-market.mp3"
}).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/fast-lip-sync-video-heygen-lipsync-speed"

def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "8eabe9f38713e9d89951ada8ee7a9f40c1d7260b5145d3bd3f03fd7dfc50c967", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")

print(create_and_wait_for_prediction({
    "video": "https://blog.api.market/wp-content/uploads/2026/10/lipsync-input-talk-api-market.mp4",
    "audio": "https://blog.api.market/wp-content/uploads/2026/10/realtime-tts-1.5-max-output-api-market.mp3"
}))
```

## FAQ
- **What kind of video and audio should I send?**
  - A source video of a person speaking and the replacement audio, both as URLs. Keep the two close in length: they can differ by at most 15%, so trim the video to about the length of the new audio before sending it.
- **How long is the output video, and what do I pay?**
  - With `enable_dynamic_duration` on (the default) the output adjusts to the length of the new audio. You pay $0.042 per second of the output video, rounded up per request.
- **Can I remove background music from the source video?**
  - Yes. Set `disable_music_track` to `true` to strip background music from the source video.
- **What does `enable_speech_enhancement` do?**
  - It enhances speech quality in the output. It is off (`false`) by default and does not change the price.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field; a `duration_mismatch` error means the video and audio lengths are too far apart.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Replace or dub the audio on a video with HeyGen Lipsync Speed. Send a video and an audio file, get back a lip-synced MP4. $0.042 per second of output video.