Lip Sync API documentation
Synchronize lip movements in a photo or video. Image + audio costs 15 credits/second (minimum 75), video + audio costs 25 credits/second (minimum 125), and video-to-video costs 2 credits/second (minimum 20). Audio modes support 2–15 seconds; video-to-video supports up to 20 seconds.
Endpoints
| Contract item | Value |
|---|---|
| Capability | lip-sync |
| Submit | POST https://vidmage.ai/api/v1/lip-sync/submit |
| Query | POST https://vidmage.ai/api/v1/lip-sync/query |
| Task identifier | taskId |
| Result field | videoUrl |
Authenticate with Authorization: Bearer YOUR_API_KEY. Save the task identifier and query the same capability. Use a stable Idempotency-Key for submission retries.
Product guide: AI Lip Sync API for Photos and Videos
Parameters and input rules
| Field | Type | Required | Default | Meaning and limits |
|---|---|---|---|---|
visualUrl | string | Yes | Not specified | URL of the source image (JPG/JPEG/PNG/WebP, up to 30 MB) or video (MP4/MOV, up to 50 MB). Video duration limits depend on inputType. |
inputType | string | No | "image" | Type of source. Values: "image", "video", "video-to-video" |
audioUrl | string | No | Not specified | Driving-audio fileUrl returned by upload_files (MP3 or WAV, required unless inputType is video-to-video). |
targetVideoUrl | string | No | Not specified | Target-video fileUrl returned by upload_files (MP4/MOV; required when inputType is video-to-video). |
audioUrl is required when inputType is not "video-to-video".
targetVideoUrl is required when inputType equals "video-to-video".
Measured media limits
| Input | Rule |
|---|---|
audioUrl | The server measures this media for billing. Maximum 15 seconds. Minimum 2 seconds. Do not send audioDuration in the submission body. |
targetVideoUrl | Used when inputType is video-to-video. |
inputType = video-to-video | Maximum 20 seconds. |
inputType = video-to-video | Minimum 0.1 seconds. |
Example request
{
"visualUrl": "https://vidmage.ai/assets/images/samples/blue-eyed-woman-sunlight.webp",
"inputType": "image",
"audioUrl": "https://vidmage.ai/templates/voices/alice.mp3"
}# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/lip-sync/submit" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
-H "Content-Type: application/json" \
-d '{"visualUrl":"https://vidmage.ai/assets/images/samples/blue-eyed-woman-sunlight.webp","inputType":"image","audioUrl":"https://vidmage.ai/templates/voices/alice.mp3"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }Task results and recovery
URL of the lip-synced video. Read videoUrl from the completed query response. Preserve taskId while the task is running.
curl -X POST "https://vidmage.ai/api/v1/lip-sync/query" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "videoUrl": "https://..." } }Submission and task queries report the available task and usage information. A timeout is not a confirmed failure. Recover the existing task instead of resubmitting.
For face selection and error recovery, follow Task lifecycle. MCP uses the normalized taskId argument in get_task_result, including capabilities whose REST identifier is requestId.
Credits
| Component / option | Rate | Minimum |
|---|---|---|
| Image + audio | 15 credits / second | 75 credits |
| Video + audio | 25 credits / second | 125 credits |
| Video to Video | 2 credits / second | 20 credits |
The server measures the uploaded driving media; audioDuration is quote-only input.
Image/video plus audio is billed at a minimum five-second output duration.
The example uses the duration shown above. The server measures uploaded media for billing; this duration is only supplied to the estimate.
The selected input workflow determines the rate. Duration is rounded up to whole seconds and the workflow minimum applies.
Use the Playground or the MCP credit estimator for your exact inputs. Credits and billing.