# HeyGen Lip Sync API > HeyGen LipSync: a new audio track for an existing video, the lips of the person on screen move to it. Developer: HeyGen Model key in the API: `heygen` ## Connect in three steps 1. [Get a key](https://api.cyhub.ai/docs/connection.md?lang=en): Create a key in the dashboard after you confirm your email. One key opens every model. 2. [Check the price](https://api.cyhub.ai/docs/generations.md?lang=en): POST /v1/price shows the cost of a run in advance, without charging you. 3. [Run a task and collect the result](https://api.cyhub.ai/docs/tasks.md?lang=en): POST /v1/tasks starts a task, GET /v1/tasks/{id} shows its status and files. ## Ready-to-use code Replace YOUR_API_KEY with your key. The code starts a task and waits for the result. In cURL, repeat the second request with the id from the first response instead of TASK_ID until status becomes succeeded. ```bash curl -X POST "https://api.cyhub.ai/v1/tasks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "heygen", "settings": { "video_url": [ "https://example.com/speaker.mp4" ], "audio_url": [ "https://example.com/new_voice.mp3" ] } }' curl "https://api.cyhub.ai/v1/tasks/TASK_ID" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import time import requests API = "https://api.cyhub.ai/v1" HEADERS = {"Authorization": "Bearer YOUR_API_KEY"} body = { "model": "heygen", "settings": { "video_url": [ "https://example.com/speaker.mp4", ], "audio_url": [ "https://example.com/new_voice.mp3", ], }, } response = requests.post(f"{API}/tasks", json=body, headers=HEADERS, timeout=60) response.raise_for_status() task = response.json() while task["status"] in ("queued", "running"): time.sleep(5) task = requests.get(f"{API}/tasks/{task['id']}", headers=HEADERS, timeout=30).json() print(task["status"], task["result"]) ``` ```javascript const API = "https://api.cyhub.ai/v1"; const HEADERS = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" }; const body = { "model": "heygen", "settings": { "video_url": [ "https://example.com/speaker.mp4" ], "audio_url": [ "https://example.com/new_voice.mp3" ] } }; async function main() { let response = await fetch(`${API}/tasks`, { method: "POST", headers: HEADERS, body: JSON.stringify(body) }); if (!response.ok) throw new Error(await response.text()); let task = await response.json(); while (task.status === "queued" || task.status === "running") { await new Promise((resolve) => setTimeout(resolve, 5000)); response = await fetch(`${API}/tasks/${task.id}`, { headers: HEADERS }); task = await response.json(); } console.log(task.status, task.result); } main(); ``` [Get a key](https://cyhub.ai/cabinet/keys) ## Price before the run Prices as of 15.10.2026: from 3 ₽. POST /v1/price shows the exact price of your settings. Send the same settings to POST /v1/price: the response shows the price of the run without charging you. ```bash curl -X POST "https://api.cyhub.ai/v1/price" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "model": "heygen", "settings": { "video_url": [ "https://example.com/speaker.mp4" ], "audio_url": [ "https://example.com/new_voice.mp3" ] } }' ``` - amount_minor: the price of the run in minor units (kopecks for rubles) - currency: the wallet currency - available_minor: how much your balance has for new tasks right now Price in this mode from 3 ₽, with a 1 s file. ## Parameters Model parameters go inside settings. Omitted optional fields take their default values. ### `mode` (Optional) Quality. Speed suits a face that barely moves. Precision handles head turns, movement and a partly covered face better, takes longer and costs more. - Type: String - Allowed values: `speed`, `precision` - Default: `"speed"` ### `video_url` (Required) One URL of the source video. The speaker's face must be clearly visible, and the video must have its own audio track with speech. - Type: List (String, uri) - Maximum items: 1 ### `audio_url` (Required) One URL of the new audio track: the lips move to it. - Type: List (String, uri) - Maximum items: 1 ### `enable_dynamic_duration` (Optional) Fit the length of the finished video to the audio. On: the audio and video lengths must differ by at most 15%, otherwise HeyGen refuses. Off: the video keeps its own length. - Type: Boolean - Default: `true` ### `disable_music_track` (Optional) Remove the background music from the source video. - Type: Boolean - Default: `false` ### `enable_speech_enhancement` (Optional) Improve how the speech sounds in the finished video. - Type: Boolean - Default: `false` ### `keep_the_same_format` (Optional) Keep the resolution and bitrate of the source video. - Type: Boolean - Default: `true` ### `enable_watermark` (Optional) Put a HeyGen watermark on the finished video. - Type: Boolean - Default: `false` Parameters not listed here are not accepted: the response is 422 unknown_setting. ## Input - The video is a URL of an MP4, MOV or WebM file up to 200 MB, the audio is a URL of an MP3, WAV, M4A, OGG or FLAC file up to 50 MB. The video is at most 10 minutes long, the audio at most 10 minutes. - The URLs must be public and start with https://: HeyGen downloads the files itself. - The source video needs its own audio track with speech: HeyGen uses it to find who speaks and when. It does not accept a video without sound or with silence. - The video goes to HeyGen whole, and the price follows its full length in seconds. | Field | Accepts | Formats | Files | File size up to | |---|---|---|---|---| | `video_url` | Video | mp4, mov, webm | 1 | 200 MB | | `audio_url` | Audio | mp3, wav, m4a, ogg, flac | 1 | 50 MB | [How to send files](https://api.cyhub.ai/docs/files.md?lang=en) ## Request example Send this JSON to POST /v1/tasks with your API key. To check the price first, send the same JSON to POST /v1/price. New voice-over for a video ```json { "model": "heygen", "settings": { "video_url": [ "https://example.com/speaker.mp4" ], "audio_url": [ "https://example.com/new_voice.mp3" ] } } ``` Precision mode, the video keeps its length ```json { "model": "heygen", "settings": { "mode": "precision", "video_url": [ "https://example.com/interview.mov" ], "audio_url": [ "https://example.com/dub.wav" ], "enable_dynamic_duration": false, "disable_music_track": true } } ``` The price is calculated when the task is accepted, currency `RUB`. [Complete generation example](https://api.cyhub.ai/docs/generations.md?lang=en) ## Output - One video with the new audio track. - Processing usually takes a few minutes, occasionally up to half an hour. | Kind | Formats | How many | Note | |---|---|---|---| | `video` | mp4 | 1 | | A finished task as GET /v1/tasks/{id} returns it (some fields left out). The caption may sit on the task or on a single file and may be empty; the model picks the file name. ```json { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "succeeded", "finished_at": "2026-10-01T12:03:41+00:00", "result": { "caption": "Caption of the result: the model and its settings", "texts": [], "files_expire_at": "2026-10-08T12:03:41+00:00", "files_expired": false, "artifacts": [ { "index": 0, "kind": "video", "filename": "video.mp4", "size": 12582912, "caption": "", "download_path": "/v1/tasks/7c9e6679-7425-40de-944b-e07fc1f90ae7/artifacts/0" } ] } } ``` [How to read the result and download files](https://api.cyhub.ai/docs/tasks.md?lang=en#result) ## See also - [HeyGen Lip Sync: features and prices](https://api.cyhub.ai/models/heygen-lip-sync) - Similar models: [Seedance 2.5 API](https://api.cyhub.ai/en/models/seedance-2-5/api.md), [Kling 3.0 API](https://api.cyhub.ai/en/models/kling-3/api.md), [Kling Motion 3.0 API](https://api.cyhub.ai/en/models/kling-motion/api.md), [Veo 3.1 API](https://api.cyhub.ai/en/models/veo-3-1/api.md), [Wan 3.0 API](https://api.cyhub.ai/en/models/wan-3/api.md), [MiniMax H3 (Hailuo 03) API](https://api.cyhub.ai/en/models/minimax-h3/api.md) - [API documentation](https://api.cyhub.ai/docs.md?lang=en) - [API errors and how to handle them](https://api.cyhub.ai/docs/errors.md?lang=en)