可灵 AI 动作控制 API 文档

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

官方文档入口（仅参考）：https://klingai.com/document-api/

创建动作控制任务

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

请求头

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

请求体参数

参数名	类型	必填	默认值	说明
`model_name`	string	可选	`Kling-V2.6`	推荐模型字段，目前支持`Kling-V3`，`Kling-V2.6`
`model`	string	可选	无	兼容字段，会映射到 `model_name`
`prompt`	string	可选	空	文本提示词，不超过 2500
`image_url`	string	必填	无	参考图像（URL/Base64）
`video_url`	string	必填	无	参考视频链接
`element_list`	array	可选	空	主体参考列表（当前最多 1 个主体）
`keep_original_sound`	string	可选	`yes`	是否保留原声：`yes`/`no`
`character_orientation`	string	必填	无	人物朝向：`image` / `video`
`mode`	string	必填	无	生成模式：`std` / `pro`
`watermark_info`	object	可选	空	水印开关，格式：`{\"enabled\": boolean}`
`callback_url`	string	可选	空	回调地址
`external_task_id`	string	可选	空	自定义任务 ID

prompt

文本提示词，可包含正向描述和负向描述。可通过提示词为画面增加元素、实现运镜效果等。

可选参数。
不能超过 2500 个字符。
当不传入时，服务商会主要依据 image_url 和 video_url 生成动作控制结果。

image_url

参考图像，生成视频中的人物、背景等元素均以参考图为准。

图片内容建议：

人物比例尽量与参考动作比例一致，尽量避免使用全身动作驱动半身人物进行生成。
人物需要露出清晰的上半身或全身肢体及头部，避免遮挡。
画面中人物避免极端朝向，例如倒立、平卧等。
人物占画面比例不宜过低。
支持真实或风格化角色，包括人物、类人动物、部分纯动物、部分类人肢体比例角色。

图片格式要求：

支持图片 URL 或 Base64 编码。
使用 Base64 时不要添加 data:image/png;base64, 等前缀，直接传 Base64 字符串。
图片格式支持 .jpg / .jpeg / .png。
图片文件大小不能超过 10MB。
图片宽高尺寸介于 300px ~ 65536px。
图片宽高比介于 1:2.5 ~ 2.5:1。

video_url

参考视频的获取链接。生成视频中的人物动作与参考视频一致。

视频内容建议：

人物需要露出清晰的上半身或全身肢体及头部，避免遮挡。
建议上传 1 人动作视频；2 人及以上时，服务商通常会取画面占比最大的人物动作进行生成。
推荐使用真人动作，部分风格化人物或类人肢体比例角色可以通过。
动作视频建议一镜到底，角色始终出现在画面中，避免切镜、明显运镜等，否则可能被截取。
动作不宜过快，相对平稳的动作生成效果更佳。
动作难度较高或速度较快时，可能生成不足上传视频时长的结果；模型最短提取出 3 秒可用连续动作即可生成。

视频格式要求：

视频文件支持 .mp4 / .mov。
文件大小不能超过 100MB。
视频宽高边长均需位于 340px ~ 3850px。
视频时长不短于 3 秒。
当 character_orientation=image 时，参考视频时长最长 10 秒。
当 character_orientation=video 时，参考视频时长最长 30 秒。
系统会校验视频内容；校验不通过时会返回错误码等信息。

element_list

参数名	类型	必填	默认值	说明
`element_list`	array	否	无	主体参考列表，基于主体库中的主体 ID 配置。动作控制场景下暂时仅支持引入 1 个主体。

子参数

参数名	类型	必填	默认值	说明
`element_id`	long	是	无	主体库中的主体 ID。

请求格式

json

{
  "element_list": [
    {
      "element_id": 829836802793406551
    }
  ]
}

character_orientation

生成视频中人物的朝向，可选择与图片一致或与视频一致。

取值	说明
`image`	与图片中人物朝向一致；此时参考视频时长不得超过 `10` 秒
`video`	与视频中人物朝向一致；此时参考视频时长不得超过 `30` 秒

mode

生成视频的模式。

取值	说明
`std`	标准模式，基础模式，性价比高
`pro`	专家模式，高品质模式，生成视频质量更佳

不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

watermark_info

是否同时生成含水印的结果。

json

{
  "watermark_info": {
    "enabled": false
  }
}

子参数	类型	必填	说明
`enabled`	boolean	是	`true` 表示生成含水印结果，`false` 表示不生成含水印结果

暂不支持自定义水印。

callback_url

本次任务结果回调通知地址。如果配置，服务端会在任务状态发生变更时主动通知。

external_task_id

自定义任务 ID。

查询任务

功能	方法	路径
创建	POST	`/v1/videos/kling/motion-control`
单任务查询	GET	`/v1/videos/kling/motion-control/{task_id}`
列表查询	GET	`/v1/videos/kling/motion-control?pageNum=1&pageSize=30`

参数兼容

兼容字段	行为
`action_control`	历史兼容字段；当前路径下会在透传前清理，不作为必填

请求示例（官方字段）

json

{
  "model_name": "Kling-V2.6",
  "image_url": "https://example.com/character.png",
  "video_url": "https://example.com/motion.mp4",
  "character_orientation": "video",
  "prompt": "保持角色形象一致，跟随参考视频动作",
  "mode": "pro"
}

返回结构示例

创建任务返回示例

json

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_status": "submitted",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（单个）

json

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",
          "duration": "string"
        }
      ]
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（列表）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "task_id": "string",
      "task_status": "submitted|processing|succeed|failed",
      "task_status_msg": "string",
      "task_info": {
        "external_task_id": "string"
      },
      "task_result": {
        "videos": [
          {
            "id": "string",
            "url": "string",
            "watermark_url": "string",
            "duration": "string"
          }
        ]
      },
      "watermark_info": {
        "enabled": true
      },
      "final_unit_deduction": "string",
      "created_at": 1722769557708,
      "updated_at": 1722769557708
    }
  ],
  "aiping_id": "string"
}

注意事项

建议优先使用 model_name；model 为兼容写法。
action_control 不是当前主参数，仅为历史兼容字段。
mode 在官方动作控制接口口径下为 std/pro，请避免传入不受支持模式。

图像生成模型

视频生成模型

Vidu

创建视频任务

任务管理

其他任务

可灵 AI

语音生成模型

MiniMax

可灵 AI 动作控制 API 文档

创建动作控制任务

请求头

请求体参数

prompt

image_url

video_url

element_list

子参数

请求格式

character_orientation

mode

watermark_info

callback_url

external_task_id

查询任务

参数兼容

请求示例（官方字段）

返回结构示例

创建任务返回示例

查询任务返回示例（单个）

查询任务返回示例（列表）

注意事项

Vidu

创建视频任务

任务管理

其他任务

可灵 AI

MiniMax

可灵 AI 动作控制 API 文档 ​

创建动作控制任务 ​

请求头 ​

请求体参数 ​

prompt ​

image_url ​

video_url ​

element_list ​

子参数 ​

请求格式 ​

character_orientation ​

mode ​

watermark_info ​

callback_url ​

external_task_id ​

查询任务 ​

参数兼容 ​

请求示例（官方字段） ​

返回结构示例 ​

创建任务返回示例 ​

查询任务返回示例（单个） ​

查询任务返回示例（列表） ​

注意事项 ​

可灵 AI 动作控制 API 文档

创建动作控制任务

请求头

请求体参数

prompt

image_url

video_url

element_list

子参数

请求格式

character_orientation

mode

watermark_info

callback_url

external_task_id

查询任务

参数兼容

请求示例（官方字段）

返回结构示例

创建任务返回示例

查询任务返回示例（单个）

查询任务返回示例（列表）

注意事项