可灵AI 视频生成 API 文档

支持的模型

模型名称	功能
`Kling-Video-O1`	Omni-Video 多模态模型
`Kling-V2.6`	文生视频 / 图生视频 / 动作控制

统一请求地址

操作	请求方法	请求地址
创建任务	POST	`/v1/videos`
查询任务	GET	`/v1/videos/{task_id}`

说明：所有视频生成请求统一使用 /v1/videos 端点，系统会根据 model 和请求参数自动路由到对应的服务商接口。

Kling-V2.6 自动路由规则

Kling-V2.6 模型会根据请求参数自动路由：

优先级	条件	功能
1	`action_control: true`	动作控制
2	有 `image` 或 `image_tail` 参数	图生视频
3	无图像输入	文生视频

Kling-Video-O1 (Omni-Video) 模型

官方文档：Omni-Video 官方文档

功能特性

文生视频
图生视频（首尾帧）
图片/主体参考生成视频
视频编辑（指令变换）
视频风格/运镜参考
视频延长（生成下一个/上一个镜头）

请求格式

支持两种输入格式：标准格式和服务商原生格式。

标准格式参数

注意：平铺格式仅支持 image 相关参数的简化。element (主体) 和 video (视频) 相关参数请使用服务商原生格式。

参数名	类型	必填	说明	取值范围/格式
`model`	string	是	模型名称	`Kling-Video-O1`
`prompt`	string	是	文本提示词，可包含 `<<<image_N>>>`、`<<<element_N>>>`、`<<<video_1>>>` 引用	不超过 2500 个字符
`first_frame_url`	string	否	首帧图片 URL 或 Base64	支持 jpg/jpeg/png，≤10MB
`last_frame_url`	string	否	尾帧图片 URL 或 Base64	支持 jpg/jpeg/png，≤10MB
`reference_images/image_list`	array	否	参考图片列表（非首尾帧），用于风格、角色等参考	`["url1", "url2"]`
`element_list`	array	否	[原生格式] 主体库中的主体引用列表	`[{"element_id": "123"}, ...]`
`video_list`	array	否	[原生格式] 视频引用列表	`[{"video_url": "...", "refer_type": "base"}]`
`mode`	string	否	生成模式	`std`（标准）、`pro`（高品质），默认 `pro`
`aspect_ratio`	string	否	画面比例（无首帧或视频编辑时必填）	`16:9`、`9:16`、`1:1`
`seconds`	string	否	视频时长（秒）	`3`-`10`，文生视频仅支持 `5` 和 `10`
`callback_url`	string	否	任务结果回调地址	有效的 URL 地址
`external_task_id`	string	否	自定义任务 ID	单用户下需保证唯一性

服务商原生格式参数

本 API 完整支持服务商原生格式，element_list 和 video_list 必须使用此格式。

官方文档：可灵AI Omni-Video API

优先级：服务商原生格式 image_list > 标准平铺格式 first_frame_url/reference_images。如果同时传入，将使用原生格式。

请求示例

1. 文生视频

json

{
  "model": "Kling-Video-O1",
  "prompt": "一个宇航员在月球上行走，背景是地球",
  "mode": "pro",
  "aspect_ratio": "16:9",
  "seconds": "5"
}

2. 首尾帧生视频（平铺格式）

json

{
  "model": "Kling-Video-O1",
  "prompt": "让花被风吹动",
  "first_frame_url": "http://wanx.alicdn.com/material/20250318/stylization_all_1.jpeg",
  "seconds": 5
}

3. 图片/主体参考（混合格式）

图片使用平铺格式，主体使用原生格式

json

{
  "model": "Kling-Video-O1",
  "prompt": "<<<image_1>>>在东京街头漫步，偶遇<<<element_1>>>和<<<element_2>>>",
  "reference_images": ["https://p4-kling.klingai.com/bs2/upload-ylab-stunt/kling/element/%E5%88%BA%E5%AE%A2-%E5%85%B6%E4%BB%96%E5%8F%82%E8%80%831.jpg?x-kcdn-pid=112452"],
  "element_list": [
    { "element_id": "146" },
    { "element_id": "145" }
  ],
  "mode": "pro",
  "aspect_ratio": "1:1",
  "seconds": "5"
}

4. 视频编辑（指令变换）（混合格式）

视频使用原生格式

json

{
  "model": "Kling-Video-O1",
  "prompt": "给<<<video_1>>>中的女孩，拿上<<<image_1>>>中的花",
  "reference_images": ["http://wanx.alicdn.com/material/20250318/stylization_all_1.jpeg"],
  "video_list": [{
      "video_url": "https://cdn.wanx.aliyuncs.com/static/demo-wan26/vace.mp4",
      "refer_type": "base",
      "keep_original_sound": "yes"
  }],
  "mode": "pro"
}

5. 视频风格/运镜参考

json

{
  "model": "Kling-Video-O1",
  "prompt": "参考<<<video_1>>>的运镜方式，生成一段视频：<<<element_1>>>在东京街头漫步",
  "element_list": [{ "element_id": "12345" }],
  "video_list": [{
      "video_url": "https://cdn.wanx.aliyuncs.com/static/demo-wan26/vace.mp4",
      "refer_type": "feature"
  }],
  "mode": "pro",
  "aspect_ratio": "1:1",
  "seconds": "5"
}

6. 视频延长（生成下一个镜头）

json

{
  "model": "Kling-Video-O1",
  "prompt": "基于<<<video_1>>>，生成下一个镜头",
  "video_list": [{
      "video_url": "https://cdn.wanx.aliyuncs.com/static/demo-wan26/vace.mp4",
      "refer_type": "feature",
      "keep_original_sound": "yes"
  }],
  "mode": "pro"
}

参数限制规则

规则	说明
首尾帧限制	暂不支持仅尾帧，有尾帧时必须有首帧
图片数量限制	超过 2 张图片时，不支持设置尾帧
参考资源数量	有参考视频时，图片+主体数量 ≤4；无参考视频时 ≤7
视频数量限制	至多仅支持上传 1 段视频
视频编辑限制	`refer_type: base` 时，不能定义首尾帧
时长限制	文生视频、首帧图生视频仅支持 5s 和 10s；视频编辑时与输入视频时长相同
画面比例	视频编辑、图生视频（含首尾帧）时不支持设置 `aspect_ratio`

注意事项

格式优先级：对于图片参数，服务商原生格式 image_list 优先于标准平铺格式。
混合格式：允许混合使用平铺的图片参数和原生的 element_list/video_list 参数。
引用语法：Omni 模型的 prompt 支持 <<<image_N>>>、<<<element_N>>>、<<<video_1>>> 引用语法，N 从 1 开始，对应列表中的第 N 个元素。
视频格式要求：
- 格式：MP4/MOV
- 时长：3-10 秒
- 尺寸：720px-2160px
- 大小：≤200MB
- 帧率：24-60fps（输出为 24fps）
图片格式要求：
- 格式：jpg/jpeg/png
- 大小：≤10MB
- 尺寸：≥300px
- 宽高比：1:2.5 ~ 2.5:1
参数透传：未知参数不会被过滤，会透传给服务商 API 进行最终判断。

文生视频 (Text to Video)

官方文档：文生视频官方文档

文生视频 API 支持通过文本提示词生成视频，当前支持 V2.6 模型（支持生成声音）。

创建任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`model`	string	是	-	模型名称：`Kling-V2.6`
`prompt`	string	是	-	正向文本提示词，不超过 2500 个字符
`negative_prompt`	string	否	空	负向文本提示词，不超过 2500 个字符
`sound`	string	否	off	是否同时生成声音。枚举值：`on`, `off`
`mode`	string	否	std	生成模式：`std`（标准模式）、`pro`（高品质模式）
`aspect_ratio`	string	否	16:9	画面比例：`16:9`, `9:16`, `1:1`
`seconds`	string	否	5	视频时长（秒）：`5`, `10`
`camera_control`	object	否	空	摄像机运动控制参数
`callback_url`	string	否	-	任务结果回调地址
`external_task_id`	string	否	-	自定义任务 ID，单用户下需保证唯一性

camera_control 参数

参数名	类型	必填	说明
`type`	string	否	预定义运镜类型：`simple`（简单运镜）、`down_back`（下移拉远）、`forward_up`（推进上移）、`right_turn_forward`（右旋推进）、`left_turn_forward`（左旋推进）
`config`	object	否	运镜配置，当 `type` 为 `simple` 时必填，其他类型无需填写

camera_control.config 参数

注意：以下参数 6 选 1，即只能有一个参数不为 0，其余参数为 0。

参数名	类型	取值范围	说明
`horizontal`	float	[-10, 10]	水平运镜（沿 x 轴平移），负值向左，正值向右
`vertical`	float	[-10, 10]	垂直运镜（沿 y 轴平移），负值向下，正值向上
`pan`	float	[-10, 10]	水平摇镜（绕 y 轴旋转），负值向左，正值向右
`tilt`	float	[-10, 10]	垂直摇镜（沿 x 轴旋转），负值向下，正值向上
`roll`	float	[-10, 10]	旋转运镜（绕 z 轴旋转），负值逆时针，正值顺时针
`zoom`	float	[-10, 10]	变焦，负值拉远，正值拉近

请求示例

基础文生视频

json

{
  "model": "Kling-V2.6",
  "prompt": "一只可爱的猫咪在花园里玩耍，阳光明媚",
  "mode": "pro",
  "aspect_ratio": "16:9",
  "seconds": "5"
}

带声音的文生视频

json

{
  "model": "Kling-V2.6",
  "prompt": "海浪拍打沙滩，海鸥在天空飞翔",
  "sound": "on",
  "mode": "pro",
  "aspect_ratio": "16:9",
  "seconds": "5"
}

带运镜控制的文生视频

json

{
  "model": "Kling-V2.6",
  "prompt": "城市夜景，霓虹灯闪烁",
  "mode": "pro",
  "aspect_ratio": "16:9",
  "seconds": "5",
  "camera_control": {
    "type": "simple",
    "config": {
      "zoom": 5,
      "horizontal": 0,
      "vertical": 0,
      "pan": 0,
      "tilt": 0,
      "roll": 0
    }
  }
}

使用预定义运镜

json

{
  "model": "Kling-V2.6",
  "prompt": "森林中的小溪",
  "mode": "std",
  "aspect_ratio": "1:1",
  "seconds": "5",
  "camera_control": {
    "type": "forward_up"
  }
}

响应体

json

{
  "id": "task_abc123",
  "status": "pending",
  "created_at": "2025-01-13T10:00:00.000000Z",
  "model": "Kling-V2.6"
}

字段	类型	说明
`id`	string	任务 ID
`status`	string	任务状态：`pending`（等待中）、`processing`（处理中）、`completed`（完成）、`failed`（失败）
`created_at`	string	任务创建时间，ISO 8601 格式
`model`	string	模型名称

注意事项

声音生成：V2.6 模型支持 sound 参数，可在生成视频时同步生成声音。
运镜控制：V2.6 模型支持 camera_control 参数进行摄像机运动控制。
视频保存：生成的视频 URL 会在 30 天后清理，请及时转存。

图生视频 (Image to Video)

官方文档：图生视频官方文档

图生视频 API 支持通过图片生成视频，支持首帧/尾帧控制、运动笔刷、摄像机运镜等功能。

路由条件：使用 Kling-V2.6 模型，并传入 image 或 image_tail 参数时自动路由到图生视频。

创建任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`model`	string	是	-	模型名称：`Kling-V2.6`
`image`	string	条件必填	-	首帧图像，Base64 或 URL。图片格式：支持 .jpg / .jpeg / .png 图片限制：文件大小不超过 10MB；图片宽高尺寸不小于 300px；图片宽高比介于 1:2.5 ~ 2.5:1 之间参数关系：与 `image_tail` 至少二选一，二者不能同时为空；`image` + `image_tail` 参数、`dynamic_masks`/`static_mask` 参数、`camera_control` 参数三选一，不能同时使用
`image_tail`	string	条件必填	-	尾帧图像，Base64 或 URL。与 `image` 至少二选一
`prompt`	string	否	-	正向文本提示词长度限制：不能超过 2500 个字符音色指定：使用 `<<<voice_1>>>` 来指定音色，序号同 `voice_list` 参数所引用音色的排列顺序（如 `<<<voice_1>>>`、`<<<voice_2>>>`）音色使用规则：一次视频生成任务至多引用 2 个音色；指定音色时，`sound` 参数值必须为 `on` 语法建议：语法结构越简单越好，例如：`男人<<<voice_1>>>说："你好"` 计费说明：当 `voice_list` 参数不为空且 `prompt` 参数中引用音色 ID 时，视频生成任务按"有指定音色"计量计费
`negative_prompt`	string	否	空	负向文本提示词，不超过 2500 个字符
`sound`	string	否	off	是否生成声音（仅 V2.6）：`on`, `off`
`voice_list`	array	否	-	生成视频时所引用的音色的列表（仅 V2.6 及后续版本）数量限制：一次视频生成任务至多引用 2 个音色计费说明：当 `voice_list` 参数不为空且 `prompt` 参数中引用音色 ID 时，视频生成任务按"有指定音色"计量计费
`mode`	string	否	std	生成视频的模式枚举值：`std`、`pro` - `std`：标准模式（标准），基础模式，性价比高 - `pro`：专家模式（高品质），高表现模式，生成视频质量更佳
`seconds`	string	否	5	生成视频时长，单位 s 枚举值：`5`、`10`
`cfg_scale`	float	否	0.5	生成自由度 [0,1]，V2.x 不支持
`static_mask`	string	否	-	静态笔刷涂抹区域（用户通过运动笔刷涂抹的 mask 图片）说明："运动笔刷"能力包含"动态笔刷 dynamic_masks"和"静态笔刷 static_mask"两种格式要求：支持传入图片 Base64 编码或图片 URL（确保可访问，格式要求同 `image` 字段）；图片格式支持 .jpg / .jpeg / .png 尺寸要求：图片长宽比必须与输入图片相同（即 `image` 字段），否则任务失败（failed）分辨率要求：`static_mask` 和 `dynamic_masks.mask` 这两张图片的分辨率必须一致，否则任务失败（failed）
`dynamic_masks`	array	否	-	动态笔刷配置列表数量限制：可配置多组（最多 6 组），每组包含"涂抹区域 mask"与"运动轨迹 trajectories"序列版本支持：不同模型版本、视频模式支持范围不同，详见下文 `dynamic_masks` 参数
`camera_control`	object	否	空	控制摄像机运动的协议（如未指定，模型将根据输入的文本/图片进行智能匹配）版本支持：不同模型版本、视频模式支持范围不同，详见下文 `camera_control` 参数
`callback_url`	string	否	无	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知具体通知的消息 schema 见"Callback协议"
`external_task_id`	string	否	无	自定义任务 ID 用户自定义任务 ID，传入不会覆盖系统生成的任务 ID，但支持通过该 ID 进行任务查询请注意，单用户下需要保证唯一性

互斥参数规则

以下三组参数互斥，不能同时使用：

参数组	说明
`image` + `image_tail`	首尾帧控制
`static_mask` / `dynamic_masks`	运动笔刷
`camera_control`	摄像机控制

dynamic_masks 参数

动态笔刷配置列表。可配置多组（最多 6 组），每组包含"涂抹区域 mask"与"运动轨迹 trajectories"序列。不同模型版本、视频模式支持范围不同，具体支持情况请参考官方文档。

参数名	类型	说明
`mask`	string	动态笔刷涂抹区域（用户通过运动笔刷涂抹的 mask 图片）格式要求：支持传入图片 Base64 编码或图片 URL（确保可访问，格式要求同 `image` 字段）；图片格式支持 .jpg / .jpeg / .png 尺寸要求：图片长宽比必须与输入图片相同（即 `image` 字段），否则任务失败（failed）分辨率要求：`static_mask` 和 `dynamic_masks.mask` 这两张图片的分辨率必须一致，否则任务失败（failed）
`trajectories`	array	运动轨迹坐标序列长度限制：生成 5s 的视频，轨迹长度不超过 77，即坐标个数取值范围：[2, 77] 坐标系说明：轨迹坐标系，以图片左下角为坐标原点注1：坐标点个数越多轨迹刻画越准确，如只有 2 个轨迹点则为这两点连接的直线注2：轨迹方向以传入顺序为指向，以最先传入的坐标为轨迹起点，依次链接后续坐标形成运动轨迹
`trajectories[].x`	int	轨迹点横坐标（在像素二维坐标系下，以输入图片 `image` 左下为原点的像素坐标）
`trajectories[].y`	int	轨迹点纵坐标（在像素二维坐标系下，以输入图片 `image` 左下为原点的像素坐标）

voice_list 参数（仅 V2.6）

生成视频时所引用的音色的列表。仅 V2.6 及后续版本模型支持当前参数。

限制说明：

一次视频生成任务至多引用 2 个音色
当 voice_list 参数不为空且 prompt 参数中引用音色 ID 时，视频生成任务按"有指定音色"计量计费

参数名	类型	说明
`voice_id`	string	音色 ID，通过音色定制接口返回，也可使用系统预置音色，详见音色定制相关 API；非对口型 API 的 `voice_id`

请求示例：

json

"voice_list": [
  {"voice_id": "voice_id_1"},
  {"voice_id": "voice_id_2"}
]

camera_control 参数

控制摄像机运动的协议（如未指定，模型将根据输入的文本/图片进行智能匹配）。不同模型版本、视频模式支持范围不同，具体支持情况请参考官方文档。

参数名	类型	说明
`type`	string	预定义的运镜类型枚举值：`simple`、`down_back`、`forward_up`、`right_turn_forward`、`left_turn_forward` - `simple`：简单运镜，此类型下可在 `config` 中六选一进行运镜 - `down_back`：镜头下压并后退 ➡️ 下移拉远，此类型下 `config` 参数无需填写 - `forward_up`：镜头前进并上仰 ➡️ 推进上移，此类型下 `config` 参数无需填写 - `right_turn_forward`：先右旋转后前进 ➡️ 右旋推进，此类型下 `config` 参数无需填写 - `left_turn_forward`：先左旋并前进 ➡️ 左旋推进，此类型下 `config` 参数无需填写
`config`	object	包含六个字段，用于指定摄像机在不同方向上的运动或变化使用规则：当运镜类型指定 `simple` 时必填，指定其他类型时不填参数规则：以下参数 6 选 1，即只能有一个参数不为 0，其余参数为 0

camera_control.config 参数

注意：以下参数 6 选 1，即只能有一个参数不为 0，其余参数为 0。

参数名	类型	说明
`horizontal`	float	水平运镜，控制摄像机在水平方向上的移动量（沿 x 轴平移）取值范围：[-10, 10]，负值表示向左平移，正值表示向右平移
`vertical`	float	垂直运镜，控制摄像机在垂直方向上的移动量（沿 y 轴平移）取值范围：[-10, 10]，负值表示向下平移，正值表示向上平移
`pan`	float	水平摇镜，控制摄像机在水平面上的旋转量（绕 y 轴旋转）取值范围：[-10, 10]，负值表示绕 y 轴向左旋转，正值表示绕 y 轴向右旋转
`tilt`	float	垂直摇镜，控制摄像机在垂直面上的旋转量（沿 x 轴旋转）取值范围：[-10, 10]，负值表示绕 x 轴向下旋转，正值表示绕 x 轴向上旋转
`roll`	float	旋转运镜，控制摄像机的滚动量（绕 z 轴旋转）取值范围：[-10, 10]，负值表示绕 z 轴逆时针旋转，正值表示绕 z 轴顺时针旋转
`zoom`	float	变焦，控制摄像机的焦距变化，影响视野的远近取值范围：[-10, 10]，负值表示焦距变长、视野范围变小，正值表示焦距变短、视野范围变大

请求示例

基础图生视频

json

{
  "model": "Kling-V2.6",
  "image": "https://example.com/start.jpg",
  "prompt": "画面中的人物开始跳舞",
  "mode": "pro",
  "seconds": "5"
}

首尾帧控制

json

{
  "model": "Kling-V2.6",
  "image": "https://example.com/start.jpg",
  "image_tail": "https://example.com/end.jpg",
  "prompt": "人物从站立变为坐下",
  "mode": "pro",
  "seconds": "5"
}

带声音和音色的图生视频

json

{
  "model": "Kling-V2.6",
  "image": "https://example.com/person.jpg",
  "prompt": "男人<<<voice_1>>>说：'你好，世界'",
  "sound": "on",
  "voice_list": [
    {"voice_id": "voice_123"}
  ],
  "mode": "pro",
  "seconds": "5"
}

带运动笔刷的图生视频

json

{
  "model": "Kling-V2.6",
  "image": "https://example.com/scene.jpg",
  "prompt": "画面中的物体开始移动",
  "mode": "pro",
  "seconds": "5",
  "static_mask": "https://example.com/static_mask.png",
  "dynamic_masks": [
    {
      "mask": "https://example.com/dynamic_mask.png",
      "trajectories": [
        {"x": 100, "y": 200},
        {"x": 300, "y": 400}
      ]
    }
  ]
}

带运镜控制的图生视频

json

{
  "model": "Kling-V2.6",
  "image": "https://example.com/landscape.jpg",
  "prompt": "美丽的风景",
  "mode": "pro",
  "seconds": "5",
  "camera_control": {
    "type": "simple",
    "config": {
      "zoom": 5,
      "horizontal": 0,
      "vertical": 0,
      "pan": 0,
      "tilt": 0,
      "roll": 0
    }
  }
}

响应体

json

{
  "id": "task_abc123",
  "status": "pending",
  "created_at": "2025-01-13T10:00:00.000000Z",
  "model": "Kling-V2.6"
}

图片格式要求

要求	说明
格式	jpg / jpeg / png
大小	≤ 10MB
尺寸	宽高 ≥ 300px
宽高比	1:2.5 ~ 2.5:1

动作控制 (Motion Control)

官方文档：动作控制官方文档

动作控制 API 支持通过参考图像和参考视频生成动作控制视频，生成视频中的人物动作与参考视频一致。

路由条件：使用 Kling-V2.6 模型，并设置 action_control: true 参数时自动路由到动作控制。

创建任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`model`	string	是	-	模型名称：`Kling-V2.6`
`action_control`	boolean	是	-	必须设置为 `true` 以启用动作控制
`image_url`	string	是	无	参考图像，生成视频中的人物、背景等元素均已参考图为准视频内容要求： - 人物比例尽量与参考动作比例一致，尽量避免全身动作驱动半身人物进行生成 - 人物需要漏出清晰的上半身或全身的肢体及头部，避免遮挡 - 画面中人物避免存在极端朝向，比如倒立、平卧等。人物占画面比例不得太低 - 支持真实/风格化的角色（包括人物/类人动物/部分纯动物/部分类人肢体比例的角色）通过格式要求：支持传入图片 Base64 编码或图片 URL（确保可访问） Base64 编码说明：系统自动兼容含前缀（如 `data:image/png;base64,`）和无前缀的 Base64 编码格式，统一处理后传给服务商图片格式：支持 .jpg / .jpeg / .png 图片限制：文件大小不能超过 10MB，图片宽高尺寸介于 300px～65536px，图片宽高比介于 1:2.5 ~ 2.5:1 之间
`video_url`	string	是	无	参考视频的获取链接。生成视频中的人物动作与参考视频一致视频内容要求： - 人物需要漏出清晰的上半身或全身的全部肢体及头部，避免遮挡 - 建议上传 1 人动作视频，2 人及以上会取画面占比最大的人物动作进行生成 - 推荐使用真人动作，部分风格化的人物/类人肢体比例可以通过 - 动作视频一镜到底，角色始终出现在画面中，避免切镜、运镜等。否则会被截取 - 动作避免过快，相对平稳的动作生成效果更佳格式要求：视频文件支持 .mp4/.mov，文件大小不超过 100MB，仅支持长宽的边长均位于 340px~3850px 之间，上述校验不通过会返回错误码等信息时长要求：视频时长下限不短于 3 秒，时长上限与人物朝向参考（`character_orientation`）有关： - 当人物朝向与视频中人物一致时，视频时长最长可达 30 秒 - 当人物朝向与图片中人物一致时，视频时长最长可达 10 秒 - 如果您的动作难度比较高、速度比较快，有一定概率生成不足上传视频时长的结果，因为模型只能提取有效动作时长进行生成，最短提取出 3s 可用连续动作即可生成。请注意，因此消耗的积分将无法退还，建议适当调整动作难度与速度系统校验：系统会校验视频内容，如有问题会返回错误码等信息
`mode`	string	是	无	生成视频的模式枚举值：`std`、`pro` - `std`：标准模式（标准），基础模式，性价比高 - `pro`：专家模式（高品质），高表现模式，生成视频质量更佳不同模型版本、视频模式支持范围不同，详见能力地图
`character_orientation`	string	是	无	生成视频中人物的朝向，可选择与图片一致或与视频一致枚举值：`image`、`video` - `image`：与图片中人物朝向一致；此时参考视频时长不得超过 10 秒 - `video`：与视频中人物朝向一致；此时参考视频时长不得超过 30 秒
`prompt`	string	否	空	文本提示词，可包含正向描述和负向描述可通过提示词为画面增加元素、实现运镜效果等，详见可灵「动作控制」使用指南长度限制：不能超过 2500 个字符
`keep_original_sound`	string	否	yes	可选择是否保留视频原声枚举值：`yes`、`no` - `yes`：保留视频原声 - `no`：不保留视频原声
`callback_url`	string	否	无	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知具体通知的消息 schema 见"Callback协议"
`external_task_id`	string	否	无	自定义任务 ID 用户自定义任务 ID，传入不会覆盖系统生成的任务 ID，但支持通过该 ID 进行任务查询请注意，单用户下需要保证唯一性

character_orientation 说明

值	说明	视频时长限制
`image`	生成视频中人物朝向与参考图片一致	参考视频 ≤ 10 秒
`video`	生成视频中人物朝向与参考视频一致	参考视频 ≤ 30 秒

请求示例

基础动作控制

json

{
  "model": "Kling-V2.6",
  "action_control": true,
  "image_url": "https://example.com/person.jpg",
  "video_url": "https://example.com/dance.mp4",
  "mode": "pro",
  "character_orientation": "video"
}

带提示词的动作控制

json

{
  "model": "Kling-V2.6",
  "action_control": true,
  "image_url": "https://example.com/person.jpg",
  "video_url": "https://example.com/dance.mp4",
  "mode": "pro",
  "character_orientation": "video",
  "prompt": "在舞台上表演",
  "keep_original_sound": "yes"
}

人物朝向与图片一致

json

{
  "model": "Kling-V2.6",
  "action_control": true,
  "image_url": "https://example.com/person.jpg",
  "video_url": "https://example.com/action.mp4",
  "mode": "std",
  "character_orientation": "image",
  "keep_original_sound": "no"
}

响应体

json

{
  "id": "task_abc123",
  "status": "pending",
  "created_at": "2025-01-13T10:00:00.000000Z",
  "model": "Kling-V2.6"
}

参考图像要求

要求	说明
格式	jpg / jpeg / png
大小	≤ 10MB
尺寸	300px ~ 65536px
宽高比	1:2.5 ~ 2.5:1
内容要求	人物需露出清晰的上半身或全身肢体及头部，避免遮挡

参考视频要求

要求	说明
格式	mp4 / mov
大小	≤ 100MB
尺寸	边长 340px ~ 3850px
时长	≥ 3 秒；`character_orientation=video` 时 ≤ 30 秒；`character_orientation=image` 时 ≤ 10 秒
内容要求	人物需露出清晰的上半身或全身肢体及头部，建议单人视频，动作平稳

注意事项

人物比例：参考图像中的人物比例尽量与参考视频中的人物比例一致。
动作难度：动作难度较高或速度较快时，可能生成不足上传视频时长的结果。
计费说明：
- 标准模式（std）：0.5 元/秒
- 高品质模式（pro）：0.8 元/秒
视频保存：生成的视频 URL 会在 30 天后清理，请及时转存。

查询任务

查询视频生成任务的状态和结果。所有视频生成功能共用此接口。

请求信息

网络协议	请求地址	请求方法	响应格式
https	`/v1/videos/{task_id}`	GET	application/json

请求头

字段	值	描述
Authorization	Bearer	鉴权信息

请求路径参数

参数名	类型	必填	说明
`task_id`	string	是	任务 ID，创建任务时返回的 `id` 字段

查询参数（可选）

参数名	类型	必填	说明
`provider`	string	否	服务商名称，可选。如果任务不在缓存中可加快查询

请求示例

bash

GET /v1/videos/task_abc123
Authorization: Bearer {api_key}

响应体（任务进行中）

json

{
  "id": "task_abc123",
  "status": "processing",
  "created_at": "2025-01-13T10:00:00.000000Z",
  "model": "Kling-V2.6"
}

响应体（任务完成）

json

{
  "id": "task_abc123",
  "status": "completed",
  "created_at": "2025-01-13T10:00:00.000000Z",
  "completed_at": "2025-01-13T10:03:00.000000Z",
  "model": "Kling-V2.6",
  "video_url": "https://example.com/output.mp4",
  "usage": {
    "seconds": 5.0,
    "video_count": 1,
    "size": "1920*1080"
  },
  "raw_response": { ... }
}

响应体（任务失败）

json

{
  "id": "task_abc123",
  "status": "failed",
  "created_at": "2025-01-13T10:00:00.000000Z",
  "model": "Kling-V2.6",
  "error": "内容审核未通过"
}

响应参数说明

字段	类型	说明
`id`	string	任务 ID
`status`	string	任务状态：`pending`（等待中）、`processing`（处理中）、`completed`（完成）、`failed`（失败）
`created_at`	string	任务创建时间，ISO 8601 格式
`completed_at`	string	任务完成时间（仅完成时返回）
`model`	string	模型名称
`video_url`	string	生成的视频 URL（仅完成时返回）
`usage.seconds`	float	视频时长（秒）
`usage.video_count`	int	生成的视频数量
`usage.size`	string	视频尺寸
`raw_response`	object	服务商原始响应
`error`	string	错误信息（仅失败时返回）

任务状态说明

状态	说明
`pending`	任务等待中，已提交但尚未开始处理
`processing`	任务处理中，正在生成视频
`completed`	任务完成，视频生成成功
`failed`	任务失败，可查看 `error` 字段获取失败原因

注意事项

轮询间隔：建议轮询间隔为 3-5 秒，避免过于频繁的请求。
视频有效期：生成的视频 URL 会在 30 天后清理，请及时转存。
任务缓存：任务结果会在服务端缓存一段时间，超时后需要通过 provider 参数指定服务商以加快查询。

响应格式

所有视频生成功能的响应格式统一如下：

任务提交响应

json

{
  "id": "task_abc123",
  "status": "pending",
  "created_at": "2025-01-13T10:00:00.000000Z",
  "model": "kling-video-o1"
}

任务完成响应

json

{
  "created": 1736758800,
  "data": [
    {
      "url": "https://example.com/generated-video.mp4",
      "duration": 5.0,
      "width": 1920,
      "height": 1080,
      "cover_url": "https://example.com/cover.jpg"
    }
  ],
  "usage": {
    "total_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0,
    "video_count": 1,
    "duration_seconds": 5.0
  },
  "provider": "可灵AI",
  "model": "Kling-Video-O1",
  "origin_data": { ... }
}

响应参数说明

参数名	类型	说明
`created`	integer	响应创建时间，Unix 时间戳（秒）
`data`	array	生成的视频数据数组
`data[].url`	string	生成的视频 URL
`data[].duration`	float	视频时长（秒）
`data[].width`	integer	视频宽度（像素）
`data[].height`	integer	视频高度（像素）
`data[].cover_url`	string	视频封面 URL
`data[].b64_json`	string	视频的 Base64 编码（可选）
`usage.video_count`	integer	生成的视频数量
`usage.duration_seconds`	float	视频总时长
`provider`	string	服务商名称
`model`	string	模型名称
`origin_data`	object	服务商原始响应（可选）

任务状态

状态	说明
`pending`	任务等待中
`processing`	任务处理中
`completed`	任务完成
`failed`	任务失败

主体（Element）管理

主体（Element）是用于视频生成中的角色、物体等元素。系统支持创建自定义主体、查询主体列表、删除自定义主体等功能。

创建主体

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/elements/custom`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息，参考接口鉴权

请求体

字段	类型	必填	默认值	描述
`element_name`	string	必须	无	主体名称不能超过10个字符
`element_description`	string	必须	无	主体描述不能超过100个字符
`element_frontal_image`	string	必须	无	主体正面参考图支持传入图片Base64编码或图片URL（确保可访问）图片格式支持.jpg / .jpeg / .png 图片文件大小不能超过10MB，图片宽高尺寸不小于300px，图片宽高比要在1:2.5 ~ 2.5:1之间
`element_refer_list`	array	必须	无	主体其他参考列表可通过上传多张、不同角度的主体参考图来定义主体外观至少上传1张参考图，至多上传3张参考图用key:value承载，其中具体如下： `json<br/>"element_refer_list":[<br/> {"image_url":"image_url_1"},<br/> {"image_url":"image_url_2"},<br/> {"image_url":"image_url_3"}<br/>]<br/>`
`tag_list`	array	选填	空	为主体配置标签，一个主体可以配置多个标签用key:value承载，其中具体如下： `json<br/>"tag_list": [<br/> {<br/> "tag_id": "o_101"<br/> }, {<br/> "tag_id": "o_102"<br/> }<br/>]<br/>` tag的ID与名称关系： \| ID \| 名称 \| \|-----

请求示例

json

{
  "element_name": "测试主体",
  "element_description": "这是一个测试主体描述",
  "element_frontal_image": "https://example.com/image.jpg",
  "element_refer_list": [
    {
      "image_url": "https://example.com/image1.jpg"
    },
    {
      "image_url": "https://example.com/image2.jpg"
    }
  ],
  "tag_list": [
    {
      "tag_id": "o_102"
    }
  ]
}

响应体

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "element_id": 842130978230767622,
    "element_name": "string",
    "element_description": "string",
    "element_frontal_image": "image_url_0",
    "element_refer_list": [
      {"image_url": "image_url_1"},
      {"image_url": "image_url_2"},
      {"image_url": "image_url_3"}
    ],
    "tag_list": [
      {
        "id": "o_101",
        "name": "animal",
        "description": "The content of description."
      },
      {
        "id": "o_102",
        "name": "animal",
        "description": "The content of description."
      }
    ],
    "owned_by": "kling"
  }
}

查询自定义主体（列表）

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/elements/custom`	GET	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息，参考接口鉴权

查询参数

/v1/elements/custom?page_num=1&page_size=30

字段	类型	必填	默认值	描述
`page_num`	int	可选	1	页码取值范围：[1,1000]
`page_size`	int	可选	30	每页数据量取值范围：[1,500]

响应体

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "element_id": 842130978230767622,
      "element_name": "string",
      "element_description": "string",
      "element_frontal_image": "image_url_0",
      "element_refer_list": [
        {"image_url": "image_url_1"},
        {"image_url": "image_url_2"},
        {"image_url": "image_url_3"}
      ],
      "tag_list": [
        {
          "id": "o_101",
          "name": "animal",
          "description": "The content of description."
        },
        {
          "id": "o_102",
          "name": "animal",
          "description": "The content of description."
        }
      ],
      "owned_by": "kling"
    }
  ]
}

查询官方主体（列表）

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/elements/presets`	GET	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息，参考接口鉴权

查询参数

/v1/elements/presets?page_num=1&page_size=30

字段	类型	必填	默认值	描述
`page_num`	int	可选	1	页码取值范围：[1,1000]
`page_size`	int	可选	30	每页数据量取值范围：[1,500]

请求体

无

响应体

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "element_id": 123,
      "element_name": "string",
      "element_description": "string",
      "element_frontal_image": "image_url_0",
      "element_refer_list": [
        {"image_url": "image_url_1"},
        {"image_url": "image_url_2"},
        {"image_url": "image_url_3"}
      ],
      "tag_list": [
        {
          "id": "o_101",
          "name": "animal",
          "description": "The content of description."
        },
        {
          "id": "o_102",
          "name": "animal",
          "description": "The content of description."
        }
      ],
      "owned_by": "kling"
    }
  ]
}

删除自定义主体

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/elements/delete`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息，参考接口鉴权

请求体

字段	类型	必填	默认值	描述
`element_id`	string	必须	无	要删除的主体ID，仅支持删除自定义主体

请求示例

json

{
  "element_id": "842130978230767622"
}

响应体

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "string"
  }
}

字段	类型	说明
`task_id`	string	任务ID，系统生成
`task_status`	string	任务状态，枚举值：`submitted`（已提交）、`processing`（处理中）、`succeed`（成功）、`failed`（失败）

注意事项

名称长度限制：element_name 不超过 10 个字符
图片格式：element_frontal_image 和 element_refer_list 中的图片可以是 URL 或 Base64 编码
参考图数量：element_refer_list 需要 1-3 张参考图
图片要求：
- 格式：支持 .jpg / .jpeg / .png
- 大小：不超过 10MB
- 尺寸：宽高不小于 300px
- 宽高比：1:2.5 ~ 2.5:1

可灵AI 视频生成 API 文档 ​

支持的模型 ​

统一请求地址 ​

Kling-V2.6 自动路由规则 ​

Kling-Video-O1 (Omni-Video) 模型 ​

功能特性 ​

请求格式 ​

标准格式参数 ​

服务商原生格式参数 ​

请求示例 ​

1. 文生视频 ​

2. 首尾帧生视频（平铺格式） ​

3. 图片/主体参考（混合格式） ​

4. 视频编辑（指令变换）（混合格式） ​

5. 视频风格/运镜参考 ​

6. 视频延长（生成下一个镜头） ​

参数限制规则 ​

注意事项 ​

文生视频 (Text to Video) ​

创建任务 ​

请求头 ​

请求体参数 ​

camera_control 参数 ​

camera_control.config 参数 ​

请求示例 ​

基础文生视频 ​

带声音的文生视频 ​

带运镜控制的文生视频 ​

使用预定义运镜 ​

响应体 ​

注意事项 ​

图生视频 (Image to Video) ​

创建任务 ​

请求头 ​

请求体参数 ​

互斥参数规则 ​

dynamic_masks 参数 ​

voice_list 参数（仅 V2.6） ​

camera_control 参数 ​

camera_control.config 参数 ​

请求示例 ​

基础图生视频 ​

首尾帧控制 ​

带声音和音色的图生视频 ​

带运动笔刷的图生视频 ​

带运镜控制的图生视频 ​

响应体 ​

图片格式要求 ​

动作控制 (Motion Control) ​

创建任务 ​

请求头 ​

请求体参数 ​

character_orientation 说明 ​

请求示例 ​

基础动作控制 ​

带提示词的动作控制 ​

人物朝向与图片一致 ​

响应体 ​

参考图像要求 ​

参考视频要求 ​

注意事项 ​

查询任务 ​

请求信息 ​

请求头 ​

请求路径参数 ​

查询参数（可选） ​

请求示例 ​

响应体（任务进行中） ​

响应体（任务完成） ​

响应体（任务失败） ​

响应参数说明 ​

任务状态说明 ​

注意事项 ​

响应格式 ​

任务提交响应 ​

任务完成响应 ​

响应参数说明 ​

任务状态 ​

主体（Element）管理 ​

创建主体 ​

可灵AI 视频生成 API 文档

支持的模型

统一请求地址

Kling-V2.6 自动路由规则

Kling-Video-O1 (Omni-Video) 模型

功能特性

请求格式

标准格式参数

服务商原生格式参数

请求示例

1. 文生视频

2. 首尾帧生视频（平铺格式）

3. 图片/主体参考（混合格式）

4. 视频编辑（指令变换）（混合格式）

5. 视频风格/运镜参考

6. 视频延长（生成下一个镜头）

参数限制规则

注意事项

文生视频 (Text to Video)

创建任务

请求头

请求体参数

camera_control 参数

camera_control.config 参数

请求示例

基础文生视频

带声音的文生视频

带运镜控制的文生视频

使用预定义运镜

响应体

注意事项

图生视频 (Image to Video)

创建任务

请求头

请求体参数

互斥参数规则

dynamic_masks 参数

voice_list 参数（仅 V2.6）

camera_control 参数

camera_control.config 参数

请求示例

基础图生视频

首尾帧控制

带声音和音色的图生视频

带运动笔刷的图生视频

带运镜控制的图生视频

响应体

图片格式要求

动作控制 (Motion Control)

创建任务

请求头

请求体参数

character_orientation 说明

请求示例

基础动作控制

带提示词的动作控制

人物朝向与图片一致

响应体

参考图像要求

参考视频要求

注意事项

查询任务

请求信息

请求头

请求路径参数

查询参数（可选）

请求示例

响应体（任务进行中）

响应体（任务完成）

响应体（任务失败）

响应参数说明

任务状态说明

注意事项

响应格式

任务提交响应

任务完成响应

响应参数说明

任务状态

主体（Element）管理

创建主体