创建 Kling Motion Control 任务

POST

kling

videos

motion-control

curl https://api.cometapi.com/kling/v1/videos/motion-control \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image_url": "https://your-image-host.example.com/character.png",
    "video_url": "https://your-video-host.example.com/reference-motion.mp4",
    "prompt": "Studio scene.",
    "keep_original_sound": "no",
    "character_orientation": "video",
    "mode": "std"
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "<task_id>",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1785398400000,
    "updated_at": 1785398400000
  }
}

使用此端点可根据角色图像和一段参考视频创建 Motion Control 任务。

本页介绍兼容的 Motion Control 路由。Kling Video 3.0 Motion Control 使用独立的 API 合约。

所需媒体

image_url 接受公共 URL 或原始 Base64 字符串。

使用不超过 10 MB 的 JPG、JPEG 或 PNG 图像。
将每个图像维度设为 300 至 65,536 像素。
使用 1:2.5 至 2.5:1 的宽高比。
将 Base64 作为原始编码字符串发送，不要添加 data:image/...;base64, 前缀。
展示一名无遮挡的角色，身体取景应与动作参考相匹配。

video_url 接受公共 MP4 或 MOV URL。

使用不超过 100 MB 的视频。
将短边设为至少 340 像素。
将长边设为不超过 3850 像素。
使用仅有一名可见角色的连续镜头。
避免剪辑、镜头变化和过快的动作。

请遵守时长限制，并检查嵌套的终态 task_status。外层 HTTP 200 或响应 code: 0 确认的是查询响应，而不是成功的生成结果。

设置 orientation 值

character_orientation 为必填项，且接受 image 或 video。

值	参考视频时长
`image`	3–10 秒
`video`	3–30 秒

如果使用 element_list，则将 character_orientation 设为 video。

选择模型和模式

兼容路由接受 kling-v2-6 和 kling-v3。这两个模型值均接受以下两种模式值：

模型	`std`	`pro`
`kling-v2-6`	支持	支持
`kling-v3`	支持	支持

如省略 model_name，请求将使用 kling-v2-6。如省略 mode，请求将使用 std。kling-v3 值会保持兼容请求结构如本页所述；它不会选择独立的 Kling 3.0 路径版本合约。兼容合约不保证固定的输出分辨率。如果应用需要特定尺寸，请检查每个返回的视频。 keep_original_sound 接受 yes 或 no。如果省略此字段，请求将使用 yes。

任务流程

提交 Motion Control 请求

发送源图像、参考视频和 orientation 值。选择一个模型、模式和声音值，或使用其文档中指定的默认值。存储返回的 task_id。

轮询任务

使用获取 Kling 任务，并传入返回的 task_id。持续查询，直至状态为 succeed 或 failed。

存储结果

及时下载并存储结果。Kling 的兼容 API 文档指出，生成的视频会在 30 天后清除。请勿依赖返回的 URL 在整整 30 天内始终可访问。

可选字段

字段	结构	限制
`prompt`	字符串，最多 2500 个字符	兼容请求结构中的可选文本字段。
`callback_url`	URI 字符串或空字符串	未配置回调 URI 时，请省略该字段或使用空字符串。
`external_task_id`	对您的账户唯一的字符串	将任务与您的应用关联。它不能替代用于 CometAPI 查询的返回 `task_id`。
`element_list`	最多包含一个 `{"element_id": 123}` 对象的数组	仅将此字段与 `character_orientation: "video"`.
`watermark_info`	`{"enabled": boolean}`	兼容的水印结构仅包含 `enabled` 布尔值。

回调结构

旧版回调架构具有以下结构：

{
  "task_id": "<task_id>",
  "task_status": "succeed",
  "task_status_msg": "",
  "created_at": 1785398400000,
  "updated_at": 1785398460000,
  "final_unit_deduction": "<value>",
  "final_balance_deduction": {
    "quota": "<value>",
    "list_price": "<value>"
  },
  "task_info": {
    "external_task_id": "<your_unique_id>"
  },
  "task_result": {
    "videos": [
      {
        "id": "<video_id>",
        "url": "https://media.example.com/<file_id>.mp4",
        "duration": "6.4"
      }
    ]
  }
}

回调状态可以是 submitted、processing、succeed 或 failed。终态结果字段仅会在返回终态时出现。

结果字段

字段	类型	说明
`task_result.videos[].id`	字符串	生成的视频 ID。
`task_result.videos[].url`	URI 字符串	生成的视频交付 URL。
`task_result.videos[].watermark_url`	URI 字符串	任务返回水印视频时的交付 URL。
`task_result.videos[].duration`	字符串	生成的视频时长，以秒为单位。
`final_unit_deduction`	字符串	随任务返回的最终单位扣减值。
`final_balance_deduction`	`{"quota": string, "list_price": string}`	随任务返回的最终余额扣减值。

任务状态为 submitted、processing、succeed 或 failed。

请参阅 Kling Motion Control API 参考和 Kling 回调协议，了解 API 详细信息。

授权

Authorization

string

header

必填

Bearer authentication. Use your CometAPI API key.

请求体

application/json

image_url

string

必填

Character image as a public URL or a raw Base64 string. Send raw Base64 without a data:image/...;base64, prefix; data-URI input is outside the compatible contract. Supported formats are JPG, JPEG, and PNG. The image must be 10 MB or smaller. Its width and height must each be from 300 through 65,536 pixels, and its aspect ratio must be between 1:2.5 and 2.5:1.

video_url

string<uri>

必填

Public reference motion video URL. Use an MP4 or MOV file that is 100 MB or smaller. The short edge must be at least 340 pixels, and the long edge must not exceed 3850 pixels. The video must be at least 3 seconds long. The maximum duration depends on character_orientation.

character_orientation

enum<string>

必填

Required compatible string enum. With image, the reference video can be 3 to 10 seconds long. With video, the reference video can be 3 to 30 seconds long.

可用选项:

image,

video

model_name

enum<string>

默认值:kling-v2-6

Model ID for this compatible Motion Control request. Omit this field to use kling-v2-6. The kling-v3 value keeps this compatible request shape; it does not select the separate Kling 3.0 path-version contract.

可用选项:

kling-v2-6,

kling-v3

prompt

string

Optional text field in the compatible request structure. Maximum 2500 characters.

Maximum string length: 2500

keep_original_sound

enum<string>

默认值:yes

Compatible string enum. Accepted values are yes and no. Omitted requests use yes.

可用选项:

yes,

no

mode

enum<string>

默认值:std

Both compatible models accept std and pro. Omitted requests use std.

可用选项:

std,

pro

callback_url

Optional callback field in the compatible structure. Provide a URI, or omit the field or send an empty string when no callback URI is configured.

external_task_id

string

Optional ID for correlation in your application. The value must be unique for your account. Store the returned task_id for CometAPI status queries.

element_list

object[]

Optional compatible Element structure. Provide at most one object, and combine this field only with character_orientation: video.

Maximum array length: 1

Show child attributes

watermark_info

object

Optional compatible watermark structure.

Show child attributes

响应

200 - application/json

Task accepted.

code

integer

必填

Response code. A value of 0 indicates that the request was accepted.

message

string

必填

Response message.

data

object

必填

Show child attributes

最后修改于 2026年7月31日

curl https://api.cometapi.com/kling/v1/videos/motion-control \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image_url": "https://your-image-host.example.com/character.png",
    "video_url": "https://your-video-host.example.com/reference-motion.mp4",
    "prompt": "Studio scene.",
    "keep_original_sound": "no",
    "character_orientation": "video",
    "mode": "std"
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "<task_id>",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1785398400000,
    "updated_at": 1785398400000
  }
}

内容审核

API 密钥

所需媒体

设置 orientation 值

选择模型和模式

任务流程

可选字段

回调结构

结果字段

授权

请求体

响应

​所需媒体

​设置 orientation 值

​选择模型和模式

​任务流程

​可选字段

​回调结构

​结果字段

授权

请求体

响应

所需媒体

设置 orientation 值

选择模型和模式

任务流程

可选字段

回调结构

结果字段