> ## Documentation Index > > Fetch the complete documentation index at: https://kling.ai/document-api/llms.txt > Use this file to discover all available pages before exploring further. # Lip Sync > Source: https://kling.ai/document-api/api/video/lip-sync > Locale: en > Current Tab: Lip Sync > Sibling Tabs: Lip Sync / Face Recognition > This content is optimized for LLMs. In-page tabs are expanded and UI-only controls are omitted. --- ## Create Task ### API Overview - Method: `POST` - Path: `/v1/videos/advanced-lip-sync` - Auth: `Authorization: Bearer ` - Content-Type: `application/json` ### Headers | Field | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format | | `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication | ### Request Body | Field Path | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `session_id` | string | Yes | - | - | Session ID generated during the identify face API. It remains unchanged during the selection/editing process. | | `face_choose` | array | Yes | - | - | Specified Face for Lip-Sync | | `face_choose[].face_id` | string | Yes | - | - | Face ID | | `face_choose[].audio_id` | string | No | - | - | Sound ID Generated via TTS API | | `face_choose[].sound_file` | string | No | - | - | Sound File | | `face_choose[].sound_start_time` | long | Yes | - | - | Time point to start cropping sound | | `face_choose[].sound_end_time` | long | Yes | - | - | Time point to stop cropping sound | | `face_choose[].sound_insert_time` | long | Yes | - | - | The time for inserting cropped sound | | `face_choose[].sound_volume` | float | No | `1` | - | Volume Controls (higher values = louder) | | `face_choose[].original_audio_volume` | float | No | `1` | - | Original video volume (higher values = louder) | | `watermark_info` | object | No | - | - | Whether to generate watermarked results simultaneously | | `external_task_id` | string | No | - | - | Custom Task ID | | `callback_url` | string | No | - | - | The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes. | #### Request Body Field Notes - `session_id`: Generated by the [Face Recognition](https://kling.ai/document-api/api/video/lip-sync/face-detection) API. - `face_choose`: Includes Face ID, lip movement reference data, etc. - `face_choose`: Currently only supports one person lip-sync. - `face_choose[].face_id`: Returned by the facial recognition interface. - `face_choose[].audio_id`: Only supports audio generated within the last 30 days with a duration of no less than 2 seconds and no more than 60 seconds. - `face_choose[].audio_id`: Either audio_id or sound_file must be provided (mutually exclusive; cannot be empty or both populated). - `face_choose[].sound_file`: Supports Base64-encoded audio or accessible audio URL. - `face_choose[].sound_file`: Accepted formats: .mp3/.wav/.m4a/.aac (max 5MB). Format mismatches or oversized files will return error codes. - `face_choose[].sound_file`: Only supports audio with a duration of no less than 2 seconds and no more than 60 seconds. - `face_choose[].sound_file`: Either audio_id or sound_file must be provided (mutually exclusive; cannot be empty or both populated). - `face_choose[].sound_file`: The system will verify the audio content and return error codes if there are any problems. - `face_choose[].sound_start_time`: Based on the original sound start time, the start time is 0'0", units: ms - `face_choose[].sound_start_time`: The sound before the starting point will be cropped, and the cropped sound must not be shorter than 2 seconds. - `face_choose[].sound_end_time`: Based on the original sound start time, the start time is 0'0", units: ms - `face_choose[].sound_end_time`: The sound after the end point will be cropped, and the cropped sound must not be shorter than 2 seconds. - `face_choose[].sound_end_time`: The end point time shouldn't be later than the total duration of the original sound. - `face_choose[].sound_insert_time`: Based on the original video start time, the start time is 0'0", units: ms - `face_choose[].sound_insert_time`: The time range for inserting sound should overlap with the face's lip-sync time interval for at least 2 seconds. - `face_choose[].sound_insert_time`: The start time for inserting sound must not be earlier than the start time of the video, and the end time for inserting sound must not be later than the end time of the video. - `face_choose[].sound_volume`: Value range: [0, 2] - `face_choose[].original_audio_volume`: Value range: [0, 2] - `face_choose[].original_audio_volume`: No effect if source video is silent. - `watermark_info`: Defined by the enabled parameter, format: ```json "watermark_info": { "enabled": boolean } ``` - `watermark_info`: true: generate watermarked result, false: do not generate - `watermark_info`: Custom watermarks are not currently supported - `external_task_id`: User-defined task ID. It will not override the system-generated task ID, but supports querying tasks by this ID. - `external_task_id`: Please note that uniqueness must be ensured for each user. - `callback_url`: For specific message schema, see [Callback Protocol](https://kling.ai/document-api/api/get-started/callbacks) ### Request Example ```bash curl --request POST \ --url https://api-singapore.klingai.com/v1/videos/advanced-lip-sync \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "session_id": "850508686686064678", "face_choose": [ { "face_id": "0", "sound_file": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/go-to-world.mp3", "sound_insert_time": 1000, "sound_start_time": 0, "sound_end_time": 3000, "sound_volume": 2, "original_audio_volume": 2 } ], "external_task_id": "", "callback_url": "" }' ``` ### Response Example ```json { "code": 0, // Error codes; Specific definitions can be found in "Error Code" "message": "string", // Error information "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems "data": { "task_id": "string", // Task ID, generated by the system "task_info": { //Task creation parameters "external_task_id": "string" //User-defined task ID }, "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms } } ``` --- ## Query Task (Single) ### API Overview - Method: `GET` - Path: `/v1/videos/advanced-lip-sync/{id}` - Auth: `Authorization: Bearer ` - Content-Type: `application/json` ### Headers | Field | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format | | `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication | ### Path Params | Field | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `task_id` | string | No | - | - | Task ID for Video Generation - Lip-Sync. Fill the value directly in the request path. | ### Request Example ```bash curl --request GET \ --url https://api-singapore.klingai.com/v1/videos/advanced-lip-sync/{task_id} \ --header 'Authorization: Bearer ' ``` ### Response Example ```json { "code": 0, // Error codes; Specific definitions can be found in "Error Code" "message": "string", // Error information "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems "data": { "task_id": "string", // Task ID, generated by the system "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed "task_status_msg": "string", // Task status message, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) "task_info": { //Task creation parameters "parent_video": { //Original video information "id": "string", // Original video ID "url": "string", // Original video URL "duration": "string" //Original video duration, unit: s } }, "task_result": { //Task result "videos": [ //Generated video list { "id": "string", // Generated video ID; globally unique "url": "string", // URL for generating videos (Please note that for security purposes, generated images/videos will be deleted after 30 days. Please save them promptly.) "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format "duration": "string" //Total video duration, unit: s } ] }, "watermark_info": { "enabled": boolean //Whether watermark is enabled }, "final_unit_deduction": "string", // The deduction units of task "final_balance_deduction": { // Balance deduction information "quota": "string", // Balance deduction discount price "list_price": "string" // Balance deduction list price }, "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms } } ``` --- ## Query Task (List) ### API Overview - Method: `GET` - Path: `/v1/videos/advanced-lip-sync` - Auth: `Authorization: Bearer ` - Content-Type: `application/json` ### Headers | Field | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format | | `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication | ### Query Params | Field | Type | Required | Default | Enum | Description | |---|---|---:|---|---|---| | `pageNum` | int | No | `1` | - | Page number | | `pageSize` | int | No | `30` | - | Number of items per page | #### Query Params Field Notes - `pageNum`: Value range: [1, 1000] - `pageSize`: Value range: [1, 500] ### Request Example ```bash curl --request GET \ --url 'https://api-singapore.klingai.com/v1/videos/advanced-lip-sync?pageNum=1&pageSize=30' \ --header 'Authorization: Bearer ' ``` ### Response Example ```json { "code": 0, // Error codes; Specific definitions can be found in "Error Code" "message": "string", // Error information "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems "data": [ { "task_id": "string", // Task ID, generated by the system "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed "task_status_msg": "string", // Task status message, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) "task_info": { //Task creation parameters "parent_video": { //Original video information "id": "string", // Original video ID "url": "string", // Original video URL "duration": "string" //Original video duration, unit: s } }, "task_result": { //Task result "videos": [ //Generated video list { "id": "string", // Generated video ID; globally unique "url": "string", // URL for generating videos (Please note that for security purposes, generated images/videos will be deleted after 30 days. Please save them promptly.) "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format "duration": "string" //Total video duration, unit: s } ] }, "watermark_info": { "enabled": boolean //Whether watermark is enabled }, "final_unit_deduction": "string", // The deduction units of task "final_balance_deduction": { // Balance deduction information "quota": "string", // Balance deduction discount price "list_price": "string" // Balance deduction list price }, "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms } ] } ```