Kling (可灵) 对口型 API

快速开始

认证方式

在所有请求中添加 Bearer Token 认证头：

Authorization: Bearer YOUR_API_KEY

可用模型

定价 (最多省60%)

接口端点

请求参数

第一步 — 人脸识别 (kling-identify-face)

提交一段视频识别人脸,返回 sessionId 和 faceId(在 resultJson 里),供第二步使用。$0.01/次。

第二步 — 对口型视频生成 (kling-lip-sync-video)

用第一步的 sessionId 和 faceId,配合音频(kling-lip-sync-tts 产出的 audioId,或直接 audioUrl)完成对口型。

文字转语音 (kling-lip-sync-tts)

用预设音色把文本合成为语音(可用于驱动对口型),返回音频结果。

代码示例

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

响应格式

创建任务响应

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

人脸识别 — 成功响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "completed",
    "model": "kling-identify-face",
    "resultUrls": [],
    "resultJson": "{ \"resultUrls\": [], \"sessionId\": \"891032747618619461\", \"faceId\": \"0\", \"faces\": [{ \"face_id\": \"0\", \"start_time\": 0, \"end_time\": 13500 }] }"
  }
}

对 data.resultJson 做 JSON.parse,取 sessionId 和 faceId 传给 kling-lip-sync-video。faces[] 还带每个人脸的 start_time / end_time 可对口型区间。

对口型 — 成功响应

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

失败响应

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

回调通知 (callback_url)

在创建请求中传入 callback_url 后，任务进入 completed 或 failed 终态时，我们会向该地址发起一次 HTTP POST。请求头仅包含 Content-Type: application/json，无签名头。失败会自动重试 3 次（指数退避 1s/2s/4s，单次超时 10s）；如果仍未成功，后台会在 30 分钟内继续补偿重发，直到接收端返回 2xx。

Payload 结构

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

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "model": "rh-lip-sync-video/kling-lip-sync-video",
    "state": "completed" | "failed",
    "param": "<JSON string>",            // request params, JSON.parse once
    "resultJson": "<JSON string> | null", // result object, JSON.parse once
    "failCode": null | "CONTENT_MODERATION | INVALID_INPUT | INSUFFICIENT_BALANCE | UPSTREAM_BUSY | UPSTREAM_FAILED | TIMEOUT | INTERNAL_ERROR | OTHER",
    "failMsg": null | "string",
    "retryable": true | false,           // present when state=failed: safe to retry/fallback
    "costTime": 12345,                    // duration in ms
    "completeTime": 1705123500000,        // ms epoch
    "createTime": 1705123450000           // ms epoch
  }
}

注意：data.param 与 data.resultJson 都是 JSON 字符串，使用前必须 JSON.parse 一次。

对口型（视频）任务：JSON.parse(data.resultJson) 后的结构

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

对口型最终产物是视频。resultUrls 始终存在（成功时长度为 1，失败时为空数组）；部分上游会带 videoDuration。state=failed 时 resultJson 通常为 null 或 {"resultUrls":[]}。

Node.js 接收示例

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
})

注意事项

• -每个任务只在送达 2xx 后停止重发，已送达后不会重复推送。
• -当前不附带签名头。建议在 callback_url 路径中放置一段随机 token，由你在收到回调时自行校验来源。
• -kling-identify-face 步骤的回调会在 face_list 就绪时触发，face_list 需要从 JSON.parse(param) 或 GET 轮询响应中读取，而不是从 resultJson 中。
• -回调地址建议使用公网 HTTPS 端点，并能在 10 秒内返回响应（单次超时为 10s）。

任务状态

错误码

注意事项

• *两步流程：必须先调用 kling-identify-face 获取 sessionId
• *第二步需要第一步返回的 sessionId 和 faceId
• *音频用 audioId(来自 kling-lip-sync-tts)或直接 audioUrl,并传 soundStartTime/soundEndTime/soundInsertTime(毫秒)
• *结果文件保存 7 天，请及时下载视频
• *对口型按输出视频每 5 秒计费，$0.0650/5s
• *建议每 5-10 秒轮询一次任务状态