Tạo tác vụ 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
  }
}

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 yêu cầu Motion Control

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ề.

Thăm dò tác vụ

Sử dụng Lấy một tác vụ Kling với task_id được trả về. Tiếp tục cho đến khi trạng thái là succeed hoặc failed.

Lưu kết quả

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:

{
  "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"
      }
    ]
  }
}

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 và Giao thức callback Kling để biết chi tiết API.

Ủy quyền

Authorization

string

header

bắt buộc

Bearer authentication. Use your CometAPI API key.

Nội dung

application/json

image_url

string

bắt buộc

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>

bắt buộc

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>

bắt buộc

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.

Tùy chọn có sẵn:

image,

video

model_name

enum<string>

mặc định: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.

Tùy chọn có sẵn:

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>

mặc định:yes

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

Tùy chọn có sẵn:

yes,

no

mode

enum<string>

mặc định:std

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

Tùy chọn có sẵn:

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

Phản hồi

200 - application/json

Task accepted.

code

integer

bắt buộc

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

message

string

bắt buộc

Response message.

data

object

bắt buộc

Show child attributes

Lần sửa đổi cuối 31 tháng 7, 2026

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
  }
}

Kiểm duyệt nội dung

Khóa API

Tệp phương tiện bắt buộc

Đặt giá trị orientation

Chọn model và mode

Luồng tác vụ

Các trường tùy chọn

Cấu trúc callback

Các trường kết quả

Ủy quyền

Nội dung

Phản hồi

​Tệp phương tiện bắt buộc

​Đặt giá trị orientation

​Chọn model và mode

​Luồng tác vụ

​Các trường tùy chọn

​Cấu trúc callback

​Các trường kết quả

Ủy quyền

Nội dung

Phản hồi

Tệp phương tiện bắt buộc

Đặt giá trị orientation

Chọn model và mode

Luồng tác vụ

Các trường tùy chọn

Cấu trúc callback

Các trường kết quả