动作控制

动作控制以一张形象参考图 + 一段动作参考视频为输入，生成"参考图中的形象做出参考视频中动作"的视频。

备注

输出时长由参考视频中的有效动作决定（模型只提取有效动作，最短提取出 3 秒连续动作即可生成），费用按实际输出视频时长计算。

创建任务

POST https://platform.shuyanai.com/kling/motion-control/{model}

{model} 为路径参数，指定使用的模型版本：

模型	说明
`kling-3.0`	支持主体引用（element）
`kling-2.6`	不支持主体引用

请求头

参数	类型	必填	默认值	说明
`Content-Type`	string	是	application/json	数据交换格式
`Authorization`	string	是		鉴权信息，参考接口鉴权

请求体

参数	类型	必填	说明
`contents`	array	是	参考素材合集，见下表
`settings`	object	是	输出配置，其中 `character_orientation` 必填，见下表
`options`	object	否	通用配置，见下表

contents 数组元素类型

type	支持模型	字段	说明
`prompt`	全部	`text`（必填）	文本提示词，不超过 2500 个字符可通过提示词为画面增加元素、实现运镜效果等
`image`	全部	`url`（必填）	形象参考图，支持 URL 或 base64。生成视频中的人物、背景等元素均以参考图为准格式 .jpg/.jpeg/.png，不超过 50MB，宽高不小于 300px，宽高比 1:2.5 ~ 2.5:1
`video`	全部	`url`（必填，仅支持 URL）	动作参考视频，生成视频中的人物动作与参考视频一致格式 .mp4/.mov，不超过 100MB，宽高 340px ~ 3850px（含）时长不低于 3 秒；上限与 `character_orientation` 相关（随图片=10 秒，随视频=30 秒）
`element`	仅 `kling-3.0`	`element_id`（必填）、`id`（必填）	参考主体，可辅助提升主体一致性，最多指定 1 个引用主体时，生成的视频暂时只能参考视频中的人物朝向

素材内容建议（官方要求）

形象参考图：

人物需露出清晰的上半身或全身的肢体及头部，避免遮挡；

图片中人物比例尽量与参考视频中人物比例一致，尽量避免全身动作驱动半身人物；

避免极端朝向（倒立、平卧等），人物占画面比例不得太低；

支持真实/风格化的角色（包括人物/类人动物/部分纯动物/部分类人肢体比例的角色）。

动作参考视频：

人物需露出清晰的上半身或全身的全部肢体及头部，避免遮挡；

建议上传单人动作视频，2 人及以上会取画面占比最大的人物动作进行生成;

推荐真人动作，部分风格化的人物/类人肢体比例可以通过；

动作视频一镜到底，角色始终出现在画面中，避免切镜、运镜，否则会被截取；

动作避免过快，相对平稳的动作生成效果更佳；

动作难度高/速度快时，有概率生成不足上传视频时长的结果；系统会校验视频内容，如有问题返回错误码。

settings 子字段

参数	类型	必填	默认值	说明
`character_orientation`	string	是		生成视频中人物的朝向 - `image`：与图片中人物朝向一致，此时参考视频时长不得超过 10 秒 - `video`：与视频中人物朝向一致，此时参考视频时长不得超过 30 秒 - `kling-3.0` 引用主体时，暂时只能参考视频中的人物朝向
`audio`	string	否	original	声音设置 - `original`：生成的视频保留参考视频原声 - `off`：生成的视频不含声音注意：本能力默认值为 `original`（其他能力默认 `off`）
`resolution`	string	否	720p	生成视频的清晰度，可选值：`720p`、`1080p`

备注

动作控制没有 duration、aspect_ratio、multi_shot 参数：输出时长由参考视频中的有效动作决定，画面比例跟随素材。

options 子字段

参数	类型	必填	说明
`callback_url`	string	否	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知
`external_task_id`	string	否	自定义任务 ID，传入不会覆盖系统生成的任务 ID，但支持通过该 ID 进行任务查询；单用户下需保证唯一性
`watermark_info`	object	否	是否同时生成含水印的结果，格式：`{"enabled": true}`，默认 `false`；暂不支持自定义水印

请求示例

响应示例

{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "id": "string", // 任务ID，系统生成
    "status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeeded（成功）、failed（失败）
    "create_time": 1781080778802, // 任务创建时间，Unix时间戳、单位ms
    "update_time": 1781080794151, // 任务更新时间，Unix时间戳、单位ms
    "external_id": "string" // 该任务的自定义任务ID（如有）
  }
}

查询任务

新版接口使用统一查询端点 GET /kling/tasks，支持按系统任务 ID 或自定义任务 ID 查询、批量查询，详见查询任务。任务成功后可在 outputs[0].duration 中获取实际输出时长。

04-动作控制

动作控制#

创建任务#

请求头#

请求体#

请求示例#

响应示例#

查询任务#

动作控制

创建任务

请求头

请求体

请求示例

响应示例

查询任务