> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 创建 Kling Motion Control 任务
> 通过兼容的 CometAPI 路由，根据角色图像和参考动作视频创建 Kling Motion Control 任务。
使用此端点可根据角色图像和一段
参考视频创建 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`。
## 任务流程
发送源图像、参考视频和 orientation 值。选择一个
模型、模式和声音值，或使用其文档中指定的默认值。存储返回的
`task_id`。
使用 [获取 Kling 任务](./individual-queries) ，并传入返回的 `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` 布尔值。 |
## 回调结构
旧版回调架构具有以下结构：
```json theme={null}
{
"task_id": "",
"task_status": "succeed",
"task_status_msg": "",
"created_at": 1785398400000,
"updated_at": 1785398460000,
"final_unit_deduction": "",
"final_balance_deduction": {
"quota": "",
"list_price": ""
},
"task_info": {
"external_task_id": ""
},
"task_result": {
"videos": [
{
"id": "",
"url": "https://media.example.com/.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 参考](https://kling.ai/document-api/api/video/motion-control/legacy)
和 [Kling 回调协议](https://kling.ai/document-api/api/get-started/callbacks)
，了解 API 详细信息。
## OpenAPI
````yaml api/openapi/video/kling/post-motion-control.openapi.json POST /kling/v1/videos/motion-control
openapi: 3.1.0
info:
title: Kling Motion Control API
version: 1.0.0
description: >-
Create a Kling Motion Control task from a character image and a reference
motion video.
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/kling/v1/videos/motion-control:
post:
summary: Create a Kling Motion Control task
description: >-
Submit a character image and a reference motion video. The response
contains a task ID that you can use for status queries.
operationId: create_kling_motion_control
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- image_url
- video_url
- character_orientation
properties:
model_name:
type: string
description: >-
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.
enum:
- kling-v2-6
- kling-v3
default: kling-v2-6
image_url:
type: string
description: >-
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:
type: string
format: uri
description: >-
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`.
prompt:
type: string
maxLength: 2500
description: >-
Optional text field in the compatible request structure.
Maximum 2500 characters.
keep_original_sound:
type: string
description: >-
Compatible string enum. Accepted values are `yes` and `no`.
Omitted requests use `yes`.
enum:
- 'yes'
- 'no'
default: 'yes'
character_orientation:
type: string
description: >-
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.
enum:
- image
- video
mode:
type: string
description: >-
Both compatible models accept `std` and `pro`. Omitted
requests use `std`.
enum:
- std
- pro
default: std
callback_url:
description: >-
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.
oneOf:
- type: string
format: uri
- type: string
const: ''
external_task_id:
type: string
description: >-
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:
type: array
maxItems: 1
description: >-
Optional compatible Element structure. Provide at most one
object, and combine this field only with
`character_orientation: video`.
items:
type: object
required:
- element_id
properties:
element_id:
type: integer
format: int64
description: Kling Element ID in the compatible structure.
additionalProperties: false
watermark_info:
type: object
description: Optional compatible watermark structure.
required:
- enabled
properties:
enabled:
type: boolean
description: Boolean flag in the compatible watermark structure.
additionalProperties: false
example:
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
examples:
Image URL:
summary: Use a public character image URL
value:
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
Image base64:
summary: Use a raw Base64 character image
value:
model_name: kling-v3
image_url:
video_url: https://your-video-host.example.com/reference-motion.mp4
prompt: Studio scene.
keep_original_sound: 'no'
character_orientation: video
mode: pro
responses:
'200':
description: Task accepted.
content:
application/json:
schema:
type: object
required:
- code
- message
- data
properties:
code:
type: integer
description: >-
Response code. A value of 0 indicates that the request was
accepted.
message:
type: string
description: Response message.
data:
type: object
required:
- task_id
- task_status
- task_info
- created_at
- updated_at
properties:
task_id:
type: string
description: System-generated task ID for status queries.
task_status:
type: string
description: Task state after submission.
const: submitted
task_status_msg:
type: string
description: Status detail when returned.
task_info:
type: object
description: Additional task metadata. The object can be empty.
additionalProperties: true
created_at:
type: integer
format: int64
description: Task creation timestamp in milliseconds.
updated_at:
type: integer
format: int64
description: Last task update timestamp in milliseconds.
example:
code: 0
message: SUCCEED
data:
task_id:
task_status: submitted
task_info: {}
created_at: 1785398400000
updated_at: 1785398400000
x-codeSamples:
- lang: Shell
label: Image URL
source: |
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"
}'
- lang: Python
label: Image URL
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/kling/v1/videos/motion-control",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"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",
},
)
result = response.json()
print(result.get("code"), result.get("data", {}).get("task_id"))
- lang: JavaScript
label: Image URL
source: |
const response = await fetch(
"https://api.cometapi.com/kling/v1/videos/motion-control",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
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",
}),
},
);
const result = await response.json();
console.log(result.code, result.data?.task_id);
- lang: Shell
label: Image base64
source: |
curl https://api.cometapi.com/kling/v1/videos/motion-control \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"model_name": "kling-v3",
"image_url": "",
"video_url": "https://your-video-host.example.com/reference-motion.mp4",
"prompt": "Studio scene.",
"keep_original_sound": "no",
"character_orientation": "video",
"mode": "pro"
}
JSON
- lang: Python
label: Image base64
source: |
import base64
import os
import requests
with open("character.png", "rb") as image_file:
image_base64 = base64.b64encode(image_file.read()).decode("ascii")
response = requests.post(
"https://api.cometapi.com/kling/v1/videos/motion-control",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"model_name": "kling-v3",
"image_url": image_base64,
"video_url": "https://your-video-host.example.com/reference-motion.mp4",
"prompt": "Studio scene.",
"keep_original_sound": "no",
"character_orientation": "video",
"mode": "pro",
},
)
result = response.json()
print(result.get("code"), result.get("data", {}).get("task_id"))
- lang: JavaScript
label: Image base64
source: >
import { readFile } from "node:fs/promises";
const imageBase64 = (await
readFile("character.png")).toString("base64");
const response = await fetch(
"https://api.cometapi.com/kling/v1/videos/motion-control",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model_name: "kling-v3",
image_url: imageBase64,
video_url: "https://your-video-host.example.com/reference-motion.mp4",
prompt: "Studio scene.",
keep_original_sound: "no",
character_orientation: "video",
mode: "pro",
}),
},
);
const result = response.json();
console.log(result.code, result.data?.task_id);
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer authentication. Use your CometAPI API key.
````