APIMODELSAPIMODELS
API 文档

apimodels.app

可灵对口型 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

创建任务与查询结果

POSThttps://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是stringkling-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 2audio_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;价格例子见 可灵对口型模型页。

相关

LS

旧版两步接口(kling-identify-face + kling-lip-sync-video)

为已有集成保留:下面这些模型名照常可调,按下面的价格计费。新接入请用上面的一次调用模型 kling-lip-sync,人脸识别在同一个请求里完成。

高级对口型视频生成。先识别人脸,再同步自定义音频。

快速开始

1
从控制台获取 API 密钥
2
调用 kling-identify-face 获取 sessionId 和 faceId
3
调用 kling-lip-sync-video,传入 sessionId、faceId 和音频
4
轮询获取合成视频结果

认证方式

在所有请求中添加 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秒

接口端点

POST/api/v1/video/generations

创建人脸识别或对口型任务。将 model 设为 "kling-identify-face" 或 "kling-lip-sync-video"。

GET/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/次。

model必填string
"kling-identify-face"
videoUrlstring
视频 URL(MP4/MOV,<=100MB,2-60秒,720p/1080p,边长 512-2160px)。宽度小于 512 或大于 2160 像素的视频建任务时直接返回 400,不扣费。videoUrl/videoId 二选一。
videoIdstring
可灵生成的视频 ID(30天内,<=60秒)。videoUrl/videoId 二选一。
callback_urlstring
完成后的回调 URL

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

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

model必填string
"kling-lip-sync-video"
sessionId必填string
来自 kling-identify-face 的 sessionId
faceId必填string
来自 kling-identify-face 的 faceId(如 "0")
audioIdstring
kling-lip-sync-tts 生成的音频 ID(2-60秒,30天内)。audioId/audioUrl 二选一。
audioUrlstring
音频 URL(.mp3/.wav/.m4a,<=5MB,2-60秒)。audioId/audioUrl 二选一。
soundStartTime必填int
音频裁剪起点(ms)。裁剪后音频不得短于 2 秒。
soundEndTime必填int
音频裁剪终点(ms)。裁剪后音频不得短于 2 秒。
soundInsertTime必填int
音频插入时间(ms)。需与人脸可对口型区间至少重合 2 秒,且不超出视频起止。
soundVolumefloat
音频音量 [0, 2],默认 1。
originalAudioVolumefloat
原视频音量 [0, 2],默认 1(原视频无声时无效)。
callback_urlstring
完成后的回调 URL

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

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

model必填string
"kling-lip-sync-tts"
text必填string
要合成的文本,最长 1000 字符。
voiceId必填string
音色 ID,共 45 个预设。枚举:genshin_vindi2, zhinen_xuesheng, tiyuxi_xuedi, ai_shatang, genshin_klee2, genshin_kirara, ai_kaiya, tiexin_nanyou, ai_chenjiahao_712, girlfriend_1_speech02, chat1_female_new-3, girlfriend_2_speech02, cartoon-boy-07, cartoon-girl-01, ai_huangyaoshi_712, you_pingjing, ai_laoguowang_712, chengshu_jiejie, zhuxi_speech02, uk_oldman3, laopopo_speech02, heainainai_speech02, dongbeilaotie_speech02, chongqingxiaohuo_speech02, chuanmeizi_speech02, chaoshandashu_speech02, ai_taiwan_man2_speech02, xianzhanggui_speech02, tianjinjiejie_speech02, diyinnansang_DB_CN_M_04-v2, yizhipiannan-v1, guanxiaofang-v2, tianmeixuemei-v1, daopianyansang-v1, mengwa-v1, AOT, oversea_male1, girlfriend_4_speech02, chat_0407_5-1, uk_boy1, PeppaPig_platform, ai_huangzhong_712, calm_story1, uk_man2, reader_en_m-v1, commercial_lady_en_f-v1
voiceLanguage必填string
音色语种,需与所选音色对应。枚举:zh / en。默认 zh。
voiceSpeedfloat
语速,0.8–2.0(精确到 1 位小数)。默认 1.0。

代码示例

# 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。