可灵对口型 API 参数文档
可灵对口型(Kling AI Lip Sync)给现成的视频换一段新音频:传一段有人物出镜的视频和一段新语音,返回同一段视频,所选人脸的口型照着新音频在说。在 APIMODELS 上它是统一视频端点里的一个模型名 kling-lip-sync,只要一次请求,可灵的人脸识别在里面完成。成片时长和原视频一样;按原视频每 5 秒 $0.077 计费,不足 5 秒按 5 秒,人脸识别不另收费。
还在用旧版两步接口(kling-identify-face + kling-lip-sync-video)?它照常可用,文档在本页底部:旧版两步接口。
价格
| 原视频 | 价格 |
|---|---|
| 每 5 秒(不足 5 秒按 5 秒) | $0.077 |
| 5 秒视频 | $0.077 |
| 6 秒视频(按 2 段计) | $0.154 |
| 10 秒视频 | $0.154 |
| 30 秒视频 | $0.462 |
| 60 秒视频(最长) | $0.924 |
计费按原视频时长,由我们在建任务时测量;音频长短不影响价格,人脸识别不另收费。读不出时长或不在 2-60 秒之间的视频和音频在扣费前返回 400;生成失败不扣费。
认证
所有请求在 Header 携带 API Key:
Authorization: Bearer YOUR_API_KEY创建任务与查询结果
https://api.apimodels.app/v1/video/generations·GET/v1/video/generations?task_id=# Kling AI Lip Sync — an existing video + new audio -> the same video, lip-synced to the new audio.
# One request: face detection runs inside it. video_url and audio_url are required.
# Billed on the INPUT video: $0.077 per started 5 seconds (face detection included).
curl -X POST https://api.apimodels.app/v1/video/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-lip-sync",
"video_url": "https://example.com/interview.mp4",
"audio_url": "https://example.com/new-line.mp3"
}'
# Response (async — a task is created):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "pending", "model": "kling-lip-sync" } }
# Poll every 10-15 s until completed (result files are kept 30 days)
curl "https://api.apimodels.app/v1/video/generations?task_id=TASK_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
# { "code": 200, "data": { "state": "completed",
# "resultUrls": ["https://r2.apimodels.app/videos/clxxx.mp4"] } }任务状态依次是 pending → processing → completed 或 failed。completed 时 data.resultUrls[0] 是 MP4;failed 时原因在 data.failMsg,费用自动退回。识别不到人脸、或 face_index 超出识别到的人脸数,任务会以 failed 结束、不扣费。我们 2026 年 11 月 21 日实测,一段 6 秒的 720p 视频 111 秒完成,这是一次实测,不是承诺。
回调(callback_url)
不想轮询就在创建请求里传 callback_url。任务到达 completed 或 failed 时,我们向这个地址发一个 HTTP POST(JSON)。投递失败会按指数退避重试,30 分钟内持续重试,直到你的接口返回 2xx。回调地址必须公网可达,localhost 和内网地址在创建时就返回 400。
POST {your callback_url}
Content-Type: application/json
{
"code": 200,
"msg": "success",
"data": {
"taskId": "clxxx...",
"model": "kling-lip-sync",
"state": "completed", // or "failed"
"param": "<JSON string>", // your request, JSON.parse once
"resultJson": "<JSON string> | null", // {"resultUrls": ["https://...mp4"]}, JSON.parse once
"failCode": null,
"failMsg": null
}
}参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 是 | string | kling-lip-sync(kling-lipsync、kling-advanced-lip-sync 也可) |
| video_url | 是 | string | 要对口型的视频,公网 URL。MP4 或 MOV,2-60 秒,720p 或 1080p,宽高 512-2160 像素,不超过 100 MB。它的时长决定价格。 |
| audio_url | 是 | string | 新语音,公网 URL 或 base64 data URI。MP3、WAV、M4A 或 AAC,2-60 秒,不超过 5 MB。 |
| face_index | 否 | integer | 用识别到的第几张脸,从 0 开始,默认 0(第一张)。一次只给一个人对口型。 |
| audio_start_ms | 否 | integer | 从音频的第几毫秒开始截取,默认 0。 |
| audio_end_ms | 否 | integer | 截取到音频的第几毫秒,默认音频结尾。截取后至少 2 秒。 |
| insert_at_ms | 否 | integer | 音频从视频的第几毫秒开始,默认是所选人脸第一次出现的时间。所选人脸在音频播放时要至少出镜 2 秒。 |
| audio_volume | 否 | number | 新语音的音量,0-2,默认 1。 |
| original_audio_volume | 否 | number | 原视频声音的音量,0-2,默认 1;原视频无声时不起作用。 |
| callback_url | 否 | string | 任务完成时我们向该地址 POST 结果;不传就轮询 GET 查询。 |
输入限制
- 视频 — MP4 或 MOV;2-60 秒;720p 或 1080p,宽和高都在 512-2160 像素之间;不超过 100 MB。
- 音频 — MP3、WAV、M4A 或 AAC;2-60 秒;不超过 5 MB。截取后至少 2 秒。
- 人脸 — 一次一人;所选人脸在音频播放时至少出镜 2 秒。
- 输出 — MP4,时长和原视频一样。实测一例:6.0 秒 720p 视频 + 3.5 秒语音 → 5.97 秒视频,111 秒出片。
常见报错
参数问题在创建时同步返回 400({"code": 400, "msg": "..."}),不会建任务、不扣费。下表 msg 是当前原文(N 为实际数值)。
| msg | 原因 / 怎么改 |
|---|---|
video_url is required: the video to lip-sync (mp4 / mov, 2–60 seconds, 720p or 1080p, up to 100 MB) | 没传视频。 |
audio_url is required: the new speech (mp3 / wav / m4a / aac, 2–60 seconds, up to 5 MB) | 没传新音频。 |
Unable to read the video duration — provide a publicly reachable mp4 or mov URL | 我们读不出视频时长:链接需要登录、已过期,或不是可识别的 MP4 / MOV。 |
video is Ns — Kling Lip Sync accepts videos of 2–60 seconds | 视频不在 2-60 秒之间。 |
Unable to read the audio duration — provide a publicly reachable mp3, wav, m4a or aac URL | 我们读不出音频时长。换一个公网可直接下载的链接。 |
audio is Ns — Kling Lip Sync accepts audio of 2–60 seconds | 音频不在 2-60 秒之间。 |
face_index must be a non-negative integer (milliseconds or index) | face_index、audio_start_ms、audio_end_ms、insert_at_ms 只接受 0 或正整数(这条 msg 会写出具体字段名)。 |
audio_volume must be a number between 0 and 2 | audio_volume、original_audio_volume 只接受 0-2 的数字。 |
audio_end_ms (N) is past the end of the audio (N ms) | 截取的结束时间超过了音频长度。 |
the audio segment (audio_end_ms − audio_start_ms) must be at least 2 seconds | 截取后的音频短于 2 秒。 |
insert_at_ms (N) is past the end of the video (N ms) | 音频的开始时间超出了视频长度。 |
- 401:API Key 缺失或无效。
- 402:余额不足以支付这段视频的费用(5 秒段数 × $0.077)。
- 生成阶段的失败(识别不到人脸、face_index 超出范围、内容审核拒绝、上游报错、超时)状态为 failed,原因在 data.failMsg,费用自动退回。
说明
- 只有一张照片、没有视频时,用可灵数字人(kling-avatar)。
- 结果文件保留 30 天后自动删除,请及时下载或转存。
- 请只上传你有权使用的人像、视频和声音。
试一试:Playground;价格例子见 可灵对口型模型页。
相关
旧版两步接口(kling-identify-face + kling-lip-sync-video)
为已有集成保留:下面这些模型名照常可调,按下面的价格计费。新接入请用上面的一次调用模型 kling-lip-sync,人脸识别在同一个请求里完成。
高级对口型视频生成。先识别人脸,再同步自定义音频。
快速开始
认证方式
在所有请求中添加 Bearer Token 认证头:
Authorization: Bearer YOUR_API_KEY
可用模型
| 模型 | API 名称 | 特性 | 价格 (最多省60%) |
|---|---|---|---|
| 人脸识别 | kling-identify-face | 检测视频人脸,返回 sessionId + faceId | $0.0100/次 |
| 对口型视频生成 | kling-lip-sync-video | 用 sessionId + faceId + 音频生成对口型视频 | $0.0650/5秒 |
定价 (最多省60%)
| 操作 | 价格 |
|---|---|
| 人脸识别 (kling-identify-face) | $0.0100/次 |
| 对口型视频生成 (kling-lip-sync-video) | $0.0650/5秒 |
接口端点
/api/v1/video/generations创建人脸识别或对口型任务。将 model 设为 "kling-identify-face" 或 "kling-lip-sync-video"。
/api/v1/video/generations?task_id=xxx查询任务状态并获取结果
两步流程说明
对口型需要两次 API 调用。首先,将视频提交给 "kling-identify-face",返回 session_id 和检测到的人脸列表(含 face_id)。然后,向 "kling-lip-sync-video" 提交第二次请求,传入 session_id、要同步的 face_id 及对应音频来源。
请求参数
第一步 — 人脸识别 (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://api.apimodels.app/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": "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)。
任务状态
pending任务已排队,等待处理processing任务执行中completed任务成功完成failed任务失败错误码
400请求错误 - 参数缺失或无效401未授权 - API 密钥无效402余额不足 - 积分不够404未找到 - 任务 ID 不存在500服务器内部错误注意事项
- *两步流程:必须先调用 kling-identify-face 获取 sessionId
- *第二步需要第一步返回的 sessionId 和 faceId
- *音频用 audioId(来自 kling-lip-sync-tts)或直接 audioUrl,并传 soundStartTime/soundEndTime/soundInsertTime(毫秒)
- *结果文件保存 30 天,请及时下载视频
- *对口型按输出视频每 5 秒计费,$0.0650/5s
- *建议每 5-10 秒轮询一次任务状态
常见问题
可灵对口型 API 多少钱?
按原视频每 5 秒 $0.077 计费,不足 5 秒按 5 秒,在建任务时测量;音频长短不影响价格,人脸识别不另收费。生成失败不扣费。
需要先单独调用人脸识别吗?
不需要。一次请求传 video_url 和 audio_url 即可,人脸识别在里面完成。要用第一张以外的脸,传 face_index。
识别不到人脸会怎样?
任务以 failed 结束,原因在 data.failMsg,不扣费。face_index 超出识别到的人脸数时也一样。
旧版两步接口(kling-identify-face + kling-lip-sync-video)还能用吗?
能用。它为已有集成保留,按输出视频每 5 秒 $0.065 计费,文档在本页底部。新接入请用一次调用的 kling-lip-sync。