The Kling 3.0 series models API is now fully available
Learn More

Lip-Sync

Identify Face

POST/v1/videos/identify-face
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/identify-face \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_url": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/kling20260206mp4.mp4",
    "video_id": ""
  }'
200
{
  "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": {
    "session_id": "id", // Session ID
    "final_unit_deduction": "string", // The deduction units of task
    "face_data": [ //Face data list
      {
        "face_id": "string", // Face ID
        "face_image": "url", // Face image URL
        "start_time": 0, // Face appearance start time, unit: ms
        "end_time": 5200 //Face appearance end time, unit: ms
      }
    ]
  }
}

Identify faces in the video for lip-sync processing.

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Request Body

video_idstringOptional

The ID of the video generated by Kling AI

  • Used to specify the video and determine whether it can be used for lip-sync services.
  • This parameter and 'video_url' are mutually exclusive—only one can be filled, and neither can be left empty.
  • Only supports videos generated within the last 30 days with a duration of no more than 60 seconds.
video_urlstringOptional

The URL of the video

  • Used to specify the video and determine whether it can be used for lip-sync services.
  • This parameter and 'video_id' are mutually exclusive—only one can be filled, and neither can be left empty.
  • Supported video formats: .mp4/.mov, file size ≤100MB, duration 2s–60s, resolution 720p or 1080p, with both width and height between 512px–2160px. If validation fails, an error code will be returned.
  • The system checks video content—if issues are detected, an error code will be returned.
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/identify-face \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_url": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/kling20260206mp4.mp4",
    "video_id": ""
  }'
200
{
  "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": {
    "session_id": "id", // Session ID
    "final_unit_deduction": "string", // The deduction units of task
    "face_data": [ //Face data list
      {
        "face_id": "string", // Face ID
        "face_image": "url", // Face image URL
        "start_time": 0, // Face appearance start time, unit: ms
        "end_time": 5200 //Face appearance end time, unit: ms
      }
    ]
  }
}

Create Task

POST/v1/videos/advanced-lip-sync
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/advanced-lip-sync \
  --header 'Authorization: Bearer <token>' \
  --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": ""
  }'
200
{
  "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
  }
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Request Body

session_idstringRequired

Session ID generated during the identify face API. It remains unchanged during the selection/editing process.

face_choosearrayRequired

Specified Face for Lip-Sync

  • Includes Face ID, lip movement reference data, etc.
  • Currently only supports one person lip-sync.
▾Hide child attributes
face_idstringRequired

Face ID

  • Returned by the facial recognition interface.
audio_idstringOptional

Sound ID Generated via TTS API

  • Only supports audio generated within the last 30 days with a duration of no less than 2 seconds and no more than 60 seconds.
  • Either audio_id or sound_file must be provided (mutually exclusive; cannot be empty or both populated).
sound_filestringOptional

Sound File

  • Supports Base64-encoded audio or accessible audio URL.
  • Accepted formats: .mp3/.wav/.m4a/.aac (max 5MB). Format mismatches or oversized files will return error codes.
  • Only supports audio with a duration of no less than 2 seconds and no more than 60 seconds.
  • Either audio_id or sound_file must be provided (mutually exclusive; cannot be empty or both populated).
  • The system will verify the audio content and return error codes if there are any problems.
sound_start_timelongRequired

Time point to start cropping sound

  • Based on the original sound start time, the start time is 0'0", units: ms
  • The sound before the starting point will be cropped, and the cropped sound must not be shorter than 2 seconds.
sound_end_timelongRequired

Time point to stop cropping sound

  • Based on the original sound start time, the start time is 0'0", units: ms
  • The sound after the end point will be cropped, and the cropped sound must not be shorter than 2 seconds.
  • The end point time shouldn't be later than the total duration of the original sound.
sound_insert_timelongRequired

The time for inserting cropped sound

  • Based on the original video start time, the start time is 0'0", units: ms
  • The time range for inserting sound should overlap with the face's lip-sync time interval for at least 2 seconds.
  • 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.
sound_volumefloatOptionalDefault to 1

Volume Controls (higher values = louder)

  • Value range: [0, 2]
original_audio_volumefloatOptionalDefault to 1

Original video volume (higher values = louder)

  • Value range: [0, 2]
  • No effect if source video is silent.
watermark_infoobjectOptional

Whether to generate watermarked results simultaneously

  • Defined by the enabled parameter, format:
  "watermark_info": { "enabled": boolean }
  • true: generate watermarked result, false: do not generate
  • Custom watermarks are not currently supported
external_task_idstringOptional

Custom Task ID

  • User-defined task ID. It will not override the system-generated task ID, but supports querying tasks by this ID.
  • Please note that uniqueness must be ensured for each user.
callback_urlstringOptional

The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes.

curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/advanced-lip-sync \
  --header 'Authorization: Bearer <token>' \
  --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": ""
  }'
200
{
  "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)

GET/v1/videos/advanced-lip-sync/{id}
curl --request GET \
  --url https://api-singapore.klingai.com/v1/videos/advanced-lip-sync/{task_id} \
  --header 'Authorization: Bearer <token>'
200
{
  "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
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
  }
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Path Parameters

task_idstringOptional

Task ID for Video Generation - Lip-Sync. Fill the value directly in the request path.

curl --request GET \
  --url https://api-singapore.klingai.com/v1/videos/advanced-lip-sync/{task_id} \
  --header 'Authorization: Bearer <token>'
200
{
  "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
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
  }
}

Query Task (List)

GET/v1/videos/advanced-lip-sync
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/videos/advanced-lip-sync?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
200
{
  "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
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
    }
  ]
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Query Parameters

pageNumintOptionalDefault to 1

Page number

  • Value range: [1, 1000]
pageSizeintOptionalDefault to 30

Number of items per page

  • Value range: [1, 500]
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/videos/advanced-lip-sync?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
200
{
  "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
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
    }
  ]
}
Previous chapter：Extend Video
Next chapter：Avatar
Identify Face
Create Task
Query Task (Single)
Query Task (List)