lip_sync_create_video
Create lip-synced videos programmatically by matching audio to a video or image, enabling automated batch processing and integration into apps or workflows.
Instructions
What this API does
Create the same Lip Sync you can make in the browser, but programmatically, so you can automate it, run it at scale, or connect it to your own app or workflow.
Good for
Automation and batch processing
Adding lip sync into apps, pipelines, or tools
How it works (3 steps)
Upload your inputs (video, image, or audio) with Generate Upload URLs and copy the
file_path.Send a request to create a lip sync job with the basic fields.
Check the job status until it's
complete, then download the result fromdownloads.
Key options
Inputs: usually a file, sometimes a YouTube link, depending on project type
Resolution: free users are limited to 576px; higher plans unlock HD and larger sizes
Extra fields: e.g.
face_swap_mode,start_seconds/end_seconds, or a text prompt
Cost
Credits are only charged for the frames that actually render. You'll see an estimate when the job is queued, and the final total after it's done.
For detailed examples, see the product page.
MCP guidance:
This starts an async video generation job and returns
idpluscredits_chargedimmediately. If the user wants the finished result, call thewait_for_video_projecthelper with the returned id, or poll the matchingGET /v1/video-projects/{id}endpoint until status iscomplete,error, orcanceled. Completed projects includedownloadswith direct URLs. The custom wait helper also returnsexact_download_urlsseparately from expiration metadata.For
*_file_pathvalues, prefer an existing Magic Hour file path or afile_pathreturned by the upload-URL endpoint after the file bytes are uploaded. Direct public media URLs may work when they are stable, fetchable, and return raw file bytes, but hotlinked URLs can fail; when in doubt, use the presigned upload flow first and pass the returnedfile_path.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Give your video a custom name for easy identification. | Lip Sync - dateTime |
| style | No | Attributes used to dictate the style of the output | |
| assets | Yes | Provide the assets for lip-sync. For video, The `video_source` field determines whether `video_file_path` or `youtube_url` field is used | |
| end_seconds | Yes | End time of your clip (seconds). Must be greater than start_seconds. | |
| max_fps_limit | No | Defines the maximum FPS (frames per second) for the output video. If the input video's FPS is lower than this limit, the output video will retain the input FPS. This is useful for reducing unnecessary frame usage in scenarios where high FPS is not required. | |
| start_seconds | Yes | Start time of your clip (seconds). Must be ≥ 0. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads. | |
| credits_charged | Yes | The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. If video generation fails, credits will be refunded, and this field will be updated to include the refund. |