Kling Lip Sync (Two-Step)

Channel type: Kling Extended (66) Gateway path: Identify face POST https://maasunion.com/kling/v1/extended/videos/identify-face (sync) Lip sync synthesis POST/GET https://maasunion.com/kling/v1/extended/videos/advanced-lip-sync Official upstream: https://api-beijing.klingai.com (/v1/videos/identify-face, /v1/videos/advanced-lip-sync)

Overview

Advanced lip sync is a two-step process:

Identify face (sync): upload a video; synchronously return the faces detected in the video and a session_id
Lip sync synthesis (async): based on the session_id and the selected face/audio, generate a lip-synced video

Authentication

Header	Required	Description
`Authorization`	Yes	`Bearer {your_api_token}`
`Content-Type`	Required for POST	`application/json`

Step 1: Identify Face (Sync)

POST https://maasunion.com/kling/v1/extended/videos/identify-face

Request Parameters

Parameter	Type	Required	Description
`video_url`	string	Yes	Video URL
`video_id`	string	No	Video ID (can be left empty)

Request Example

curl --request POST \
  --url "https://maasunion.com/kling/v1/extended/videos/identify-face" \
  --header "Authorization: Bearer {your_api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "video_url": "https://example.com/video.mp4",
    "video_id": ""
  }'

Sync Response

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "session_id": "id",
    "final_unit_deduction": "string",
    "face_data": [
      {
        "face_id": "string",
        "face_image": "url",
        "start_time": 0,
        "end_time": 5200
      }
    ]
  }
}

Field	Description
`data.session_id`	Session ID, used for step 2
`data.face_data[].face_id`	Face ID
`data.face_data[].face_image`	Face screenshot URL
`data.face_data[].start_time` / `end_time`	Time range during which the face appears (milliseconds)

Step 2: Lip Sync Synthesis (Async)

POST https://maasunion.com/kling/v1/extended/videos/advanced-lip-sync

Request Parameters

Parameter	Type	Required	Description
`session_id`	string	Yes	The `session_id` returned in step 1
`face_choose`	array	Yes	Selected face and audio configuration, see the table below
`external_task_id`	string	No	Custom task ID

face_choose[]

Parameter	Type	Description
`face_id`	string	The face ID returned in step 1
`sound_file`	string	Audio file URL
`sound_insert_time`	number	Audio insertion time (milliseconds)
`sound_start_time`	number	Audio start time (milliseconds)
`sound_end_time`	number	Audio end time (milliseconds)
`sound_volume`	number	Audio volume
`original_audio_volume`	number	Original audio volume

Request Example

curl --request POST \
  --url "https://maasunion.com/kling/v1/extended/videos/advanced-lip-sync" \
  --header "Authorization: Bearer {your_api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "session_id": "第1步返回的session_id",
    "face_choose": [
      {
        "face_id": "0",
        "sound_file": "https://example.com/voice.mp3",
        "sound_insert_time": 1000,
        "sound_start_time": 0,
        "sound_end_time": 3000,
        "sound_volume": 2,
        "original_audio_volume": 2
      }
    ]
  }'

Create Response

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "gateway_public_task_id",
    "task_status": "submitted",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  }
}

Query Task

GET https://maasunion.com/kling/v1/extended/videos/advanced-lip-sync/{task_id}

curl --request GET \
  --url "https://maasunion.com/kling/v1/extended/videos/advanced-lip-sync/{task_id}" \
  --header "Authorization: Bearer {your_api_token}"

The query response returns the synthesized video in task_result.videos, with the same structure as the standard video.

Task Status

`task_status`	Meaning
`submitted`	Submitted
`processing`	Processing
`succeed`	Succeeded
`failed`	Failed

Identify face is a synchronous endpoint that returns results directly; no polling required.

For more general information, see Kling Gateway Overview.