Kling Lip Sync API

Quick Start

Authentication

Add Authorization header with Bearer token to all requests:

Authorization: Bearer YOUR_API_KEY

Available Models

Pricing (85% off)

Endpoints

Request Parameters

Step 1 — Face Recognition (kling-identify-face)

Submit a video to identify faces. Returns a session_id and list of face objects with face_id values.

Step 2 — Advanced Lip Sync (kling-advanced-lip-sync)

Use the session_id and face_id values from step 1 to apply lip sync with custom audio.

face_choose Object

Code Examples

# Step 1: Identify faces in the video
curl -X POST https://apimodels.app/api/v1/audio/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-identify-face",
    "video_url": "https://example.com/video.mp4"
  }'

Response Format

Create Task Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "pending",
    "model": "kling-identify-face"
  }
}

Face Recognition — Success

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "completed",
    "model": "kling-identify-face",
    "faceData": {
      "session_id": "session_abc123",
      "face_list": [
        {
          "face_id": "face_001",
          "face_reference": "https://...face_thumbnail.jpg"
        }
      ]
    }
  }
}

Lip Sync — Success

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "completed",
    "model": "kling-advanced-lip-sync",
    "resultUrls": ["https://...lip_synced_video.mp4"]
  }
}

Failed Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "failed",
    "failMsg": "Face detection failed: no faces found"
  }
}

Webhook Callback (callback_url)

Pass callback_url in the create request. When the task reaches the completed or failed terminal state, our server sends a single HTTP POST to that URL with Content-Type: application/json (no signing header). Delivery is retried up to 3 times (exponential backoff 1s/2s/4s, 10s per attempt); if still unsuccessful, a background job keeps retrying for up to 30 minutes until your endpoint returns 2xx.

Payload Structure

POST {your callback_url}
Content-Type: application/json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "model": "kling-video/kling-advanced-lip-sync",
    "state": "completed" | "failed",
    "param": "<JSON string>",            // request params, JSON.parse once
    "resultJson": "<JSON string> | null", // result object, JSON.parse once
    "failCode": null | "string",
    "failMsg": null | "string",
    "costTime": 12345,                    // duration in ms
    "completeTime": 1705123500000,        // ms epoch
    "createTime": 1705123450000           // ms epoch
  }
}

Note: data.param and data.resultJson are both JSON strings — call JSON.parse once on each.

Lip-sync (video) task: shape after JSON.parse(data.resultJson)

{
  "resultUrls":    ["https://r2.apimodels.app/videos/lip_synced.mp4"],
  "videoDuration": 8                   // optional, seconds
}

Lip-sync produces a video file. resultUrls is always present (length 1 in success, [] on failure). videoDuration may be present on some upstream branches. When state=failed, resultJson is typically null or {"resultUrls":[]}.

Node.js receiver example

app.post('/webhook/kling-lip-sync', express.json(), (req, res) => {
  const { taskId, state, resultJson, failMsg } = req.body.data
  if (state === 'completed') {
    const r = JSON.parse(resultJson)
    console.log('lip-sync ready', taskId, r.resultUrls[0])
  } else {
    console.warn('lip-sync failed', taskId, failMsg)
  }
  res.status(200).end()                 // must be 2xx, otherwise we retry
})

Notes

• -A task stops retrying only after a 2xx response — once delivered it is never pushed again.
• -Callbacks are not signed today. Embed a random token in your callback_url path and verify it on receipt.
• -For the kling-identify-face step the callback fires once face_list is ready — read it from JSON.parse(param) or from the GET poll response, not from resultJson.
• -Use a public HTTPS endpoint that responds within 10 seconds (per-attempt timeout).

Task States

Error Codes

Important Notes

• *Two-step process: always run face recognition first to get session_id
• *session_id and face_id from step 1 are required for step 2
• *face_choose supports multiple faces — each with independent audio and timing
• *Results are stored for 7 days, download the video promptly
• *Lip sync pricing is $0.0063 per 5s segment of the output video
• *Poll every 5-10 seconds to check task status