APIMODELSAPIMODELS
API 文档

apimodels.app

可灵数字人 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

创建任务与查询结果

POSThttps://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是stringkling-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否stringstd(默认,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。