---
title: "Kling AI Advanced Lip-Sync API Reference"
aliases: [kling-lip-sync, advanced-lip-sync, kling-face-sync]
tags: [kling, api, lip-sync, video, ai-video]
sources: [raw/Kling AI Next-Gen AI Video & AI Image Generator 7.md]
created: 2026-04-26
updated: 2026-04-26
---

## Overview

Two-step workflow to overlay audio onto a detected face in a video: **identify face → create lip-sync task**. Session ID links the two calls. Currently supports **one person only**.

Base URL: `https://api-singapore.klingai.com`

---

## Step 1 — Identify Face

`POST /v1/videos/identify-face`

Detects faces in the source video and returns face IDs + time intervals. The `session_id` returned here is required for the next step.

### Request Body

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `video_id` | string | Either/or | Kling-generated video ID (last 30 days, ≤60 s) |
| `video_url` | string | Either/or | `.mp4`/`.mov`, ≤100 MB, 2–60 s, 720p or 1080p, 512–2160 px |

- `video_id` and `video_url` are mutually exclusive — exactly one must be provided.

### Response `data`

```json
{
  "session_id": "id",
  "final_unit_deduction": "string",
  "face_data": [
    {
      "face_id": "string",
      "face_image": "url",
      "start_time": 0,
      "end_time": 5200
    }
  ]
}
```

- `start_time` / `end_time` — face appearance window in the video (ms)

---

## Step 2 — Create Lip-Sync Task

`POST /v1/videos/advanced-lip-sync`

Assigns audio to a specific face and queues the render.

### Request Body

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `session_id` | string | Required | From identify-face response |
| `face_choose` | array | Required | One entry per face (max 1 currently) |
| `external_task_id` | string | Optional | Custom ID; must be unique per user |
| `callback_url` | string | Optional | Webhook for status changes |
| `watermark_info` | object | Optional | `{"enabled": true\|false}` |

#### `face_choose` entry fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `face_id` | string | Required | From `face_data` in Step 1 |
| `audio_id` | string | Either/or | ID from Kling TTS API; 2–60 s, last 30 days |
| `sound_file` | string | Either/or | Base64 or URL; `.mp3/.wav/.m4a/.aac`, ≤5 MB, 2–60 s |
| `sound_start_time` | long | Required | Crop start in source audio (ms from 0) |
| `sound_end_time` | long | Required | Crop end in source audio (ms); cropped segment ≥2 s |
| `sound_insert_time` | long | Required | Where in the video to insert audio (ms); must overlap face interval ≥2 s |
| `sound_volume` | float | Optional | `[0, 2]` — injected audio volume |
| `original_audio_volume` | float | Optional | `[0, 2]` — original video audio volume; no effect if video is silent |

### Response `data`

```json
{
  "task_id": "string",
  "task_status": "submitted|processing|succeed|failed",
  "created_at": 1722769557708,
  "updated_at": 1722769557708
}
```

---

## Step 3 — Query Task

### Single task

`GET /v1/videos/advanced-lip-sync/{task_id}`

### List tasks

`GET /v1/videos/advanced-lip-sync?pageNum=1&pageSize=30`

- `pageNum`: 1–1000
- `pageSize`: 1–500

### Result schema

```json
{
  "task_id": "string",
  "task_status": "submitted|processing|succeed|failed",
  "task_status_msg": "string",
  "task_info": {
    "parent_video": { "id": "string", "url": "string", "duration": "string" }
  },
  "task_result": {
    "videos": [
      {
        "id": "string",
        "url": "string",
        "watermark_url": "string",
        "duration": "string"
      }
    ]
  },
  "watermark_info": { "enabled": true },
  "final_unit_deduction": "string",
  "created_at": 1722769557708,
  "updated_at": 1722769557708
}
```

> **Warning:** Generated videos are deleted after **30 days** — download promptly.

---

## Key Takeaways

- **Two-step flow:** identify face (get `session_id` + `face_id`) → create lip-sync task
- **One person limit:** `face_choose` array currently supports a single face only
- **Audio source:** either Kling TTS `audio_id` or external `sound_file` (URL or base64) — mutually exclusive
- **Timing triplet:** `sound_start_time` + `sound_end_time` crop the audio; `sound_insert_time` places it in the video — overlap with face interval must be ≥2 s
- **Volume control:** both injected audio and original audio are independently adjustable on a `[0, 2]` scale
- **Video constraints:** source must be 720p/1080p, 2–60 s, ≤100 MB, `.mp4`/`.mov`
- **Results expire:** 30-day TTL on all generated video URLs
- **Callbacks supported:** set `callback_url` to avoid polling

---

## Related Articles

- [[wiki/web-agency/kling-text-to-video-api|Kling Text-to-Video API]] — generate source videos to feed into lip-sync
- [[wiki/web-agency/kling-image-to-video-api|Kling Image-to-Video API]] — animate a portrait image before syncing lips
- [[wiki/web-agency/kling-video-extension-api|Kling Video Extension API]] — extend the output after lip-sync
- [[wiki/web-agency/kling-multi-elements-api|Kling Multi-Elements API]] — session-based editing pattern (same session concept)
- [[wiki/web-agency/claude-code-nanobanana-website-workflow|Web Agency Workflow]] — where Kling fits in the £3–10K site pipeline

---

## Sources

- Raw: `raw/Kling AI Next-Gen AI Video & AI Image Generator 7.md`
- Kling AI API docs — Advanced Lip-Sync section
