> ## 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.
# Tạo tác vụ Kling Motion Control
> Tạo tác vụ Kling Motion Control từ hình ảnh nhân vật và video chuyển động tham chiếu bằng route CometAPI tương thích.
Sử dụng endpoint này để tạo tác vụ Motion Control từ hình ảnh nhân vật và một
video tham chiếu.
Trang này mô tả route Motion Control tương thích. Kling Video 3.0
Motion Control sử dụng một API contract riêng biệt.
## Tệp phương tiện bắt buộc
`image_url` chấp nhận URL công khai hoặc chuỗi Base64 thô.
* Sử dụng hình ảnh JPG, JPEG hoặc PNG có dung lượng từ 10 MB trở xuống.
* Đặt mỗi chiều của hình ảnh trong khoảng từ 300 đến 65.536 pixel.
* Sử dụng tỷ lệ khung hình trong khoảng từ 1:2,5 đến 2,5:1.
* Gửi Base64 dưới dạng chuỗi đã mã hóa thô, không có
`data:image/...;base64,` tiền tố.
* Hiển thị một nhân vật không bị che khuất, với khung hình cơ thể khớp với chuyển động
tham chiếu.
`video_url` chấp nhận URL MP4 hoặc MOV công khai.
* Sử dụng video có dung lượng từ 100 MB trở xuống.
* Đặt cạnh ngắn tối thiểu là 340 pixel.
* Đặt cạnh dài không quá 3850 pixel.
* Sử dụng một cảnh quay liên tục có một nhân vật hiển thị.
* Tránh các đoạn cắt, thay đổi máy quay và chuyển động quá nhanh.
Tuân theo các giới hạn về thời lượng và kiểm tra `task_status` ở trạng thái kết thúc lồng nhau. Mã
HTTP 200 bên ngoài hoặc `code: 0` phản hồi chỉ xác nhận phản hồi truy vấn, không xác nhận
kết quả tạo thành công.
## Đặt giá trị orientation
`character_orientation` là bắt buộc và chấp nhận `image` hoặc `video`.
| Giá trị | Thời lượng video tham chiếu |
| ------- | --------------------------- |
| `image` | 3–10 giây |
| `video` | 3–30 giây |
Nếu bạn sử dụng `element_list`, hãy đặt `character_orientation` thành `video`.
## Chọn model và mode
Route tương thích chấp nhận `kling-v2-6` và `kling-v3`. Cả hai giá trị model
đều chấp nhận cả hai giá trị mode:
| Model | `std` | `pro` |
| ------------ | -------------- | -------------- |
| `kling-v2-6` | Được chấp nhận | Được chấp nhận |
| `kling-v3` | Được chấp nhận | Được chấp nhận |
Nếu bạn bỏ qua `model_name`, yêu cầu sẽ sử dụng `kling-v2-6`. Nếu bạn bỏ qua `mode`,
yêu cầu sẽ sử dụng `std`. Giá trị `kling-v3` giữ nguyên cấu trúc yêu cầu tương thích
được mô tả trên trang này; giá trị này không chọn API contract riêng cho phiên bản đường dẫn Kling 3.0
.
Contract tương thích không đảm bảo độ phân giải đầu ra cố định. Hãy kiểm tra
từng video được trả về nếu ứng dụng của bạn yêu cầu kích thước cụ thể.
`keep_original_sound` chấp nhận `yes` hoặc `no`. Nếu bỏ qua trường này,
yêu cầu sẽ sử dụng `yes`.
## Luồng tác vụ
Gửi hình ảnh nguồn, video tham chiếu và giá trị orientation. Chọn một
model, mode và giá trị sound hoặc sử dụng các giá trị mặc định đã được ghi lại. Lưu
`task_id` được trả về.
Sử dụng [Lấy một tác vụ Kling](./individual-queries) với `task_id` được trả về.
Tiếp tục cho đến khi trạng thái là `succeed` hoặc `failed`.
Tải xuống và lưu kết quả ngay. Tài liệu API tương thích của Kling
nêu rằng các video được tạo sẽ bị xóa sau 30 ngày. Không
nên dựa vào việc URL được trả về vẫn có thể truy cập trong đủ 30 ngày.
## Các trường tùy chọn
| Trường | Cấu trúc | Ràng buộc |
| ------------------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `prompt` | Chuỗi, tối đa 2500 ký tự | Trường văn bản tùy chọn trong cấu trúc yêu cầu tương thích. |
| `callback_url` | Chuỗi URI hoặc chuỗi rỗng | Bỏ qua trường này hoặc sử dụng chuỗi rỗng khi không cấu hình URI callback. |
| `external_task_id` | Chuỗi duy nhất cho tài khoản của bạn | Liên kết tác vụ với ứng dụng của bạn. Giá trị này không thay thế `task_id` được trả về cho các truy vấn CometAPI. |
| `element_list` | Mảng chứa tối đa một đối tượng `{"element_id": 123}` | Chỉ kết hợp trường này với `character_orientation: "video"`. |
| `watermark_info` | `{"enabled": boolean}` | Cấu trúc watermark tương thích chỉ chứa giá trị Boolean `enabled`. |
## Cấu trúc callback
Lược đồ callback Legacy có cấu trúc như sau:
```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"
}
]
}
}
```
Trạng thái callback có thể là `submitted`, `processing`, `succeed` hoặc `failed`.
Các trường kết quả ở trạng thái kết thúc chỉ xuất hiện khi được trả về cho trạng thái kết thúc.
## Các trường kết quả
| Trường | Kiểu | Mô tả |
| ------------------------------------ | ----------------------------------------- | ------------------------------------------------------------- |
| `task_result.videos[].id` | Chuỗi | ID video được tạo. |
| `task_result.videos[].url` | Chuỗi URI | URL phân phối video được tạo. |
| `task_result.videos[].watermark_url` | Chuỗi URI | URL phân phối video có watermark khi tác vụ trả về URL đó. |
| `task_result.videos[].duration` | Chuỗi | Thời lượng video được tạo tính bằng giây. |
| `final_unit_deduction` | Chuỗi | Giá trị khấu trừ đơn vị cuối cùng được trả về cùng tác vụ. |
| `final_balance_deduction` | `{"quota": string, "list_price": string}` | Các giá trị khấu trừ số dư cuối cùng được trả về cùng tác vụ. |
Trạng thái tác vụ là `submitted`, `processing`, `succeed` hoặc `failed`.
Xem [Tài liệu tham khảo API Kling Motion Control](https://kling.ai/document-api/api/video/motion-control/legacy)
và [Giao thức callback Kling](https://kling.ai/document-api/api/get-started/callbacks)
để biết chi tiết 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.
````