Kling Motion Control 작업 생성
캐릭터 이미지와 참조 동영상에서 호환 CometAPI 경로를 통해 Kling 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
}
}필수 미디어
image_url 공개 URL 또는 원시 Base64 문자열을 허용합니다.
- 10MB 이하의 JPG, JPEG 또는 PNG 이미지를 사용하세요.
- 각 이미지의 크기는 가로와 세로 모두 300~65,536픽셀로 설정하세요.
- 가로세로비는 1:2.5~2.5:1로 설정하세요.
- Base64는
data:image/...;base64,접두사 없이 원시 인코딩 문자열로 전송하세요. - 동작 참조와 일치하는 신체 구도로 가려지지 않은 캐릭터 한 명을 표시하세요.
video_url 공개 MP4 또는 MOV URL을 허용합니다.
- 100MB 이하의 동영상을 사용하세요.
- 짧은 변의 길이는 최소 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 요청 제출
task_id을 저장하세요.작업 폴링
task_id와 함께 사용하세요.
상태가 succeed 또는 failed 중 하나가 될 때까지 계속하세요.결과 저장
선택적 필드
| 필드 | 구조 | 제약 조건 |
|---|---|---|
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 불리언만 포함됩니다. |
콜백 구조
Legacy 콜백 스키마의 구조는 다음과 같습니다:{
"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입니다.
인증
Bearer authentication. Use your CometAPI API key.
본문
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.
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.
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 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 Optional text field in the compatible request structure. Maximum 2500 characters.
2500Compatible string enum. Accepted values are yes and no. Omitted requests use yes.
yes, no Both compatible models accept std and pro. Omitted requests use std.
std, pro 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.
Optional ID for correlation in your application. The value must be unique for your account. Store the returned task_id for CometAPI status queries.
Optional compatible Element structure. Provide at most one object, and combine this field only with character_orientation: video.
1Show child attributes
Show child attributes
Optional compatible watermark structure.
Show child attributes
Show child attributes
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
}
}