APIMODELSAPIMODELS
API 文档

apimodels.app

Docs/Kling (可灵) Omni-Video API
OV

Kling (可灵) Omni-Video API

多模态视觉语言 (MVL) 视频生成 -- 在单一接口中融合自然语言提示、视频/图片引用和主体参考,实现统一调用。

快速开始

1
从控制台获取 API 密钥
2
选择模型 (kling-video-o1 或 kling-v3-omni)
3
发送 POST 请求创建任务
4
轮询 GET 请求获取视频结果

认证方式

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

Authorization: Bearer YOUR_API_KEY

可用模型

模型API 名称特性价格(可灵官方价)
Kling Video O1kling-video-o13-10s, MVL 多模态, 按秒计费(无音频)低至 $0.0881/秒
Kling V3 Omnikling-v3-omni3-15s, MVL 多模态, 音频, 保留原声低至 $0.0881/秒

只做文生 / 图生视频时,Kling V3(按秒计费)、Kling V2.6(按条计价)与Kling Motion Control 见 Kling 视频文档。

详细定价(可灵官方价)

Kling Video O1

模式参考视频$/秒
std-$0.0881
stdon$0.1320
pro-$0.1170
proon$0.1761

Kling V3 Omni

模式音频参考视频$/秒
std--$0.0881
stdon-$0.1170
std-on$0.1320
pro--$0.1170
proon-$0.1471
pro-on$0.1761

接口端点

POST/api/v1/video/generations

创建可灵 Omni-Video 视频生成任务。底层使用统一的 omni-video 端点 (POST /kling/v1/videos/omni-video)。

GET/api/v1/video/generations?task_id=xxx

查询任务状态并获取视频链接

请求参数

基本参数

model必填string
"kling-video-o1" 或 "kling-v3-omni"
promptstring
文本提示词(不超过2500字符)。描述期望的视频内容。
image_listarray
图片引用数组 { image_url, type }。① 纯图生视频:type 为 "first_frame"/"end_frame"(首/尾帧)。② 视频编辑(同时传 video_list)时:image_list 作为参考人物/主体——把该人脸/角色换进或加入视频(如"把视频里的人换成参考人脸"),此模式下 type 被忽略。要指定人脸务必在此传图,只在 prompt 里写 @某人 是无效的。
video_listarray
视频引用数组 { video_url, refer_type, keep_original_sound }。refer_type: "feature" 或 "base"。keep_original_sound: "yes" 或 "no"。
element_listarray
主体引用数组 { element_id }。用于保持角色/物体的一致性。
modestring
"std"(标准)或 "pro"(高品质)。默认:"std"
durationstring
O1:"3" 到 "10"。V3 Omni:"3" 到 "15"。默认:"5"
soundstring
"on" 或 "off"。是否生成音频。默认:"off"
aspect_ratiostring
"16:9"、"9:16" 或 "1:1"
callback_urlstring
完成后的回调 URL

高级参数

multi_shotboolean
是否生成多镜头视频。设为 true 时必须同时传 shot_type。
shot_typestring
分镜方式,multi_shot 为 true 时必填:"customize" = 按 multi_prompt 逐段指定每个镜头;"intelligence" = 由模型自动分镜(不需要 multi_prompt)。其他取值返回 400。
multi_promptarray
shot_type 为 "customize" 时必填:1–6 段的数组(不是字符串),每段 { index, prompt, duration }。index 从 1 开始连续递增;prompt 写这一段的画面;duration 是这一段的秒数,建议各段之和等于总 duration。例:[{"index": 1, "prompt": "特写:手指点亮手机", "duration": "3"}, {"index": 2, "prompt": "仰拍:屏幕光照亮人脸", "duration": "2"}]。传字符串、超过 6 段或 index 不从 1 开始都会在创建时返回 400,不扣费。
watermark_infoobject
{ enabled: true/false } - 是否生成含水印版本

代码示例

curl -X POST https://api.apimodels.app/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-video-o1",
    "prompt": "A girl dancing on the beach at sunset, cinematic lighting",
    "mode": "std",
    "duration": "5",
    "aspect_ratio": "16:9"
  }'

响应格式

创建任务响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "pending",
    "model": "kling-video/kling-video-o1"
  }
}

成功响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "completed",
    "model": "kling-video/kling-video-o1",
    "resultUrls": ["https://...video.mp4"],
    "createTime": 1705123450000,
    "completeTime": 1705123500000
  }
}

失败响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "failed",
    "model": "kling-video/kling-video-o1",
    "failMsg": "Content policy violation"
  }
}

回调通知 (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-video/kling-video-o1",
    "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/xxx.mp4"],
  "videoDuration": 5                   // optional, seconds
}

resultUrls 始终存在,长度通常为 1(失败时为空数组)。其它字段可选。state=failed 时 resultJson 通常为 null 或 {"resultUrls":[]}。

Node.js 接收示例

app.post('/webhook/kling-omni', express.json(), (req, res) => {
  const { taskId, state, resultJson, failMsg } = req.body.data
  if (state === 'completed') {
    const r = JSON.parse(resultJson)
    console.log('video ready', taskId, r.resultUrls[0], r.videoDuration)
  } else {
    console.warn('video failed', taskId, failMsg)
  }
  res.status(200).end()                 // must be 2xx, otherwise we retry
})

注意事项

  • -每个任务只在送达 2xx 后停止重发,已送达后不会重复推送。
  • -当前不附带签名头。建议在 callback_url 路径中放置一段随机 token,由你在收到回调时自行校验来源。
  • -Omni 视频任务通常耗时 30 秒到几分钟,强烈建议使用 callback_url 而不是轮询。
  • -回调地址建议使用公网 HTTPS 端点,并能在 10 秒内返回响应(单次超时为 10s)。

任务状态

pending任务已排队,等待处理
processing视频生成中
completed视频生成成功
failed视频生成失败

错误码

400请求错误 - 参数缺失或无效
401未授权 - API 密钥无效
402余额不足 - 积分不够
404未找到 - 任务 ID 不存在
500服务器内部错误

注意事项

  • *视频文件保存 30 天,请及时下载
  • *Omni-Video 使用统一端点,无需区分文生视频和图生视频
  • *至少需要提供 prompt、image_list 或 video_list 中的一个
  • *视频换脸/换人物:参考人脸必须通过 image_list 传图片 URL(和 video_list 一起),只在 prompt 里 @某人不会带入任何参考图
  • *O1 支持 3-10 秒时长,V3 Omni 支持 3-15 秒时长,均按秒计费
  • *两个模型均支持音频生成(设置 sound: "on")
  • *使用 video_list 并设置 refer_type: "base" 进行视频编辑/再创作
  • *建议每 5-10 秒轮询一次状态

常见问题

Kling Omni 视频是什么?

一个多模态 Kling 视频模型,接受文字/图片/参考组合输入生成视频,走 POST /api/v1/video/generations,一把 Key。