Volcengine video to video lip sync

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

Create Task

Use this endpoint to create a new video-to-video lip sync task. Upload a video and an audio file, and the model will drive the video lip movements to match the target audio.

Get Task Details — After submission, use the unified query endpoint to check task progress and retrieve results

TIP

For production use, we recommend providing the callBackUrl parameter so your service can receive completion notifications instead of polling for task status.

File Upload

TIP

Need to upload files before calling this endpoint? See File Upload API Quickstart.

Output Specifications

The generated video is returned in MP4 format at 25 fps. The final output duration follows the audio duration: if the source video is longer than the audio, it will be trimmed; if the source video is shorter than the audio, it will be looped.

Model Marketplace — Explore all available models and capabilities
Common API — Check account credits and usage

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
`model`	`string`	Yes	The model name used for video lip sync. This field is required. - This endpoint must use the `volcengine/video-to-video-lip-sync` model Default：`"volcengine/video-to-video-lip-sync"`。 Allowed values：`volcengine/video-to-video-lip-sync`。示例：`volcengine/video-to-video-lip-sync`。
`input`	`object`	Yes	Input parameters for the video-to-video lip sync task.
`input.mode`	`string`	Yes	Service mode for lip-sync generation. - `lite`: For single-person frontal videos. Faster processing. - `basic`: For single-person complex scenes. Supports scene segmentation and speaker identification. Allowed values：`lite` / `basic`。示例：`lite`。
`input.video_url`	`string`	Yes	Video URL. Supported resolution: 360p–1080p. Videos above 1080p will be compressed to 1080p, while videos below 360p are not supported. Supported formats: MOV, MP4, HDR, MKV. Recommended codec: H.264. Other formats/codecs may be transcoded. Max file size: 500 MB. Bitrate: 1–30 Mbps. Frame rate: 24–60 fps.
`input.audio_url`	`string`	Yes	Target pure vocal audio URL; used to drive video lip movements. Audio duration: over 1 s and up to 240 s in lite mode; over 1 s and up to 210 s in basic mode. Accepted file types: audio/mpeg, audio/wav, audio/x-wav, audio/aac, audio/mp4, audio/ogg. Max file size: 10MB.
`input.separate_vocal`	`boolean`	No	Enable vocal separation to suppress background noise. Default value: `false`. Default：`false`。示例：`false`。
`input.open_scenedet`	`boolean`	No	Whether to enable scene segmentation and speaker identification. Supported only in Basic mode. Default value: `false`. Default：`false`。示例：`false`。
`input.align_audio`	`boolean`	No	Supported in Lite mode. Whether to loop the video when the audio is longer than the video. Default value: `true`. Default：`true`。示例：`true`。
`input.align_audio_reverse`	`boolean`	No	Supported in Lite mode. Whether to loop the video in reverse (backward). Requires `align_audio` to be set to `true`. Default value: `false`. Default：`false`。示例：`false`。
`input.templ_start_seconds`	`number`	No	Supported in Lite mode. Start time of the template video, in seconds. Default value: `0`. Default：`0`。示例：`0`。
`callBackUrl`	`string`	No	Callback URL. Once the task is fully completed, ModelFold will send the result to the business webhook URL. To verify callbacks, see Webhook Verification Guide.

Request Example

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "volcengine/video-to-video-lip-sync",
  "input": {
    "mode": "lite",
    "video_url": "https://your-domain.com/video/example.mp4",
    "audio_url": "https://your-domain.com/audio/speech.mp3",
    "separate_vocal": false,
    "open_scenedet": false,
    "align_audio": true,
    "align_audio_reverse": false,
    "templ_start_seconds": 0
  },
  "callBackUrl": "https://your-domain.com/api/callback"
}'

json

{
  "model": "volcengine/video-to-video-lip-sync",
  "input": {
    "mode": "lite",
    "video_url": "https://your-domain.com/video/example.mp4",
    "audio_url": "https://your-domain.com/audio/speech.mp3",
    "separate_vocal": false,
    "open_scenedet": false,
    "align_audio": true,
    "align_audio_reverse": false,
    "templ_start_seconds": 0
  },
  "callBackUrl": "https://your-domain.com/api/callback"
}

Response

200 — Request successful

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_volcengine-video-to-video-lip-sync_1234567890"
  }
}

Callback

videoTaskCompleted

Callback URL: {request.body#/callBackUrl} (the callBackUrl in the request body).

The system sends this callback when the volcengine/video-to-video-lip-sync task succeeds or fails.

Callback body parameters

参数	类型	必填	说明
`code`	`integer`	是	Unified callback code: 200 for success, 501 for failure. Allowed values：`200` / `501`。示例：`200`。
`msg`	`string`	是	Unified callback message. Allowed values：`Playground task completed successfully.` / `Playground task failed.`。示例：`Playground task completed successfully.`。
`data`	`object`	是	—
`data.taskId`	`string`	是	The unique task identifier.
`data.model`	`string`	是	The model used for the task. Allowed values：`volcengine/video-to-video-lip-sync`。示例：`volcengine/video-to-video-lip-sync`。
`data.state`	`string`	是	Terminal task state. Allowed values：`success` / `fail`。示例：`success`。
`data.param`	`string`	是	JSON string containing the submitted task parameters.
`data.resultJson`	`string`	否	JSON string containing resultUrls, firstFrameUrl, lastFrameUrl, or resultObject when successful. Present only when state is success.
`data.failCode`	`string`	否	Failure code, a numeric string such as "400" or "500". Present only when state is fail.
`data.failMsg`	`string`	否	Failure reason. Present only when state is fail.
`data.costTime`	`integer`	否	Processing time in seconds. Present on both success and failure callbacks.
`data.completeTime`	`integer`	否	Task completion timestamp.
`data.createTime`	`integer`	否	Task creation timestamp.
`data.updateTime`	`integer`	否	Use completeTime as the completion time; updateTime may equal createTime.
`data.creditsConsumed`	`number`	否	Credits consumed by the task; 0 for failed tasks.

Task completed successfully

json

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "volcengine/video-to-video-lip-sync",
    "state": "success",
    "param": "{\"input\":\"{\\\"mode\\\":\\\"lite\\\",\\\"video_url\\\":\\\"https://example.com/input-video.mp4\\\",\\\"audio_url\\\":\\\"https://example.com/input-audio.mp3\\\",\\\"separate_vocal\\\":false,\\\"open_scenedet\\\":false,\\\"align_audio\\\":true,\\\"align_audio_reverse\\\":false,\\\"templ_start_seconds\\\":0}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"volcengine/video-to-video-lip-sync\"}",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
    "costTime": 12,
    "completeTime": 1234567890,
    "createTime": 1234560000,
    "updateTime": 1234567890,
    "creditsConsumed": 1.23
  }
}

Task failed

json

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "volcengine/video-to-video-lip-sync",
    "state": "fail",
    "param": "{\"input\":\"{\\\"mode\\\":\\\"lite\\\",\\\"video_url\\\":\\\"https://example.com/input-video.mp4\\\",\\\"audio_url\\\":\\\"https://example.com/input-audio.mp3\\\",\\\"separate_vocal\\\":false,\\\"open_scenedet\\\":false,\\\"align_audio\\\":true,\\\"align_audio_reverse\\\":false,\\\"templ_start_seconds\\\":0}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"volcengine/video-to-video-lip-sync\"}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 12,
    "creditsConsumed": 0
  }
}

Volcengine video to video lip sync ​

Endpoint ​

Create Task ​

File Upload ​

Output Specifications ​

Related Resources ​

Request Parameters ​

Body (application/json) ​

Request Example ​

Response ​

200 — Request successful ​

Callback ​

videoTaskCompleted ​

Volcengine video to video lip sync

Endpoint

Create Task

File Upload

Output Specifications

Related Resources

Request Parameters

Body (application/json)

Request Example

Response

200 — Request successful

Callback

videoTaskCompleted