可灵数字人 API 参数文档
可灵数字人(Kling AI Avatar)是快手可灵的数字人模型:一张人像加一段驱动音频(可选提示词),生成照片里的人说出这段音频的视频,口型和表情跟着声音走。在 APIMODELS 上它是统一视频端点里的一个模型名 kling-avatar。成片时长等于音频时长(2-300 秒);mode 选 std 出 720p,选 pro 出 1080p。按驱动音频秒数计费,标准每秒 $0.062、专业每秒 $0.123,向上取整到整秒。
价格
| 驱动音频 | 标准 std(720p) | 专业 pro(1080p) |
|---|---|---|
| 每秒(向上取整到整秒) | $0.062 | $0.123 |
| 2 秒(最低) | $0.124 | $0.246 |
| 3.53 秒(按 4 秒计) | $0.248 | $0.492 |
| 10 秒 | $0.62 | $1.23 |
| 60 秒 | $3.72 | $7.38 |
| 300 秒(最高) | $18.60 | $36.90 |
计费秒数 = 驱动音频时长向上取整,由我们在建任务时测量(客户端传的时长字段不参与计费)。图片和提示词不影响价格,只有 mode 影响。读不出时长或不在 2-300 秒之间的音频在扣费前返回 400;生成失败不扣费。
认证
所有请求在 Header 携带 API Key:
Authorization: Bearer YOUR_API_KEY创建任务与查询结果
https://api.apimodels.app/v1/video/generations·GET/v1/video/generations?task_id=# Kling AI Avatar — one portrait + one driving audio -> talking-avatar video.
# image_url and audio_url are required; prompt and mode (std | pro) are optional.
# The video is as long as the audio; billed per audio second, rounded up:
# std (720p) $0.062/s, pro (1080p) $0.123/s.
curl -X POST https://api.apimodels.app/v1/video/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-avatar",
"image_url": "https://example.com/presenter.jpg",
"audio_url": "https://example.com/voice.mp3",
"prompt": "She nods while talking and smiles at the end; slow push-in",
"mode": "std"
}'
# Response (async — a task is created):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "pending", "model": "kling-avatar" } }
# 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,费用自动退回。我们 2026 年 11 月 21 日实测,标准模式一段 3.53 秒的音频 146 秒完成,这是一次实测,不是承诺;每 10-15 秒轮询一次即可。
回调(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-avatar",
"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-avatar(kling-ai-avatar 也可) |
| image_url | 是 | string | 人像,公网 URL 或 base64 data URI,只能一张。也接受 image,或只含一项的 image_urls。 |
| audio_url | 是 | string | 驱动音频(说话或唱歌),公网 URL 或 base64 data URI。MP3、WAV、M4A 或 AAC,2-300 秒,不超过 5 MB。它的时长决定成片时长和价格。 |
| mode | 否 | string | std(默认,720p,每秒 $0.062)或 pro(1080p,每秒 $0.123)。也可以传 resolution: 720p / 1080p。 |
| prompt | 否 | string | 描述动作、情绪和运镜,最多 2500 个字符。 |
| callback_url | 否 | string | 任务完成时我们向该地址 POST 结果;不传就轮询 GET 查询。 |
没有时长参数:时长取自音频。要多长就先把音频剪到那么长。
输入限制
- 图片 — JPG 或 PNG;不超过 10 MB;短边至少 300 像素;宽高比在 1:2.5 到 2.5:1 之间。只能一张。
- 音频 — MP3、WAV、M4A 或 AAC;2-300 秒;不超过 5 MB。时长在建任务时测量。
- 提示词 — 可选,最多 2500 个字符。
- 输出 — MP4,时长约等于音频。实测一例:标准模式,1280×720 人像 + 3.53 秒语音 → 3.47 秒视频,146 秒出片。
常见报错
参数问题在创建时同步返回 400({"code": 400, "msg": "..."}),不会建任务、不扣费。下表 msg 是当前原文(N 为实际数值)。
| msg | 原因 / 怎么改 |
|---|---|
image_url is required: one portrait image (jpg / png, at least 300 px, aspect ratio between 1:2.5 and 2.5:1, up to 10 MB) | 没传人像。用 image_url(或 image、只含一项的 image_urls)传一张 JPG / PNG。 |
audio_url is required: the driving audio (mp3 / wav / m4a / aac, 2–300 seconds, up to 5 MB) | 没传驱动音频。 |
mode must be "std" (720p) or "pro" (1080p) | mode 只接受 std 或 pro(resolution 传 720p / 1080p 也行)。 |
Unable to read the audio duration — provide a publicly reachable mp3, wav, m4a or aac URL | 我们读不出音频时长:链接需要登录、已过期,或文件不是可识别的音频。换一个公网可直接下载的链接。 |
driving audio is Ns — Kling Avatar needs at least 2 seconds | 音频短于 2 秒。 |
driving audio is Ns — Kling Avatar accepts up to 300 seconds (5 minutes) | 音频长于 300 秒。剪短,或拆成几段分别生成。 |
prompt is N characters; Kling Avatar accepts up to 2500 | 提示词超过 2500 个字符。 |
- 401:API Key 缺失或无效。
- 402:余额不足以支付这段音频的费用(秒数 × 每秒单价)。
- 生成阶段的失败(内容审核拒绝、上游报错、超时)状态为 failed,原因在 data.failMsg,费用自动退回。
说明
- 一个请求只有一张人像和一段音频;轮流说话的对话,建议每一轮单独生成一条再剪辑。
- 结果文件保留 30 天后自动删除,请及时下载或转存。
- 请只上传你有权使用的人像和声音。
试一试:Playground;用例和价格例子见 可灵数字人模型页。
相关
常见问题
可灵数字人 API 多少钱?
按驱动音频秒数计费,标准模式(720p)每秒 $0.062,专业模式(1080p)每秒 $0.123,向上取整到整秒,在建任务时测量。生成失败不扣费。
可灵数字人请求需要哪些字段?
model(kling-avatar)、image_url(一张 JPG 或 PNG 人像)和 audio_url(驱动音频)。mode(std 或 pro)、prompt、callback_url 可选。
可灵数字人接受什么样的音频?
MP3、WAV、M4A 或 AAC,2-300 秒,不超过 5 MB,公网 URL 或 base64 data URI 都行。读不出时长或不在 2-300 秒之间的音频在扣费前返回 400。