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 문자열을 허용합니다.

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 요청 제출

소스 이미지, 참조 동영상 및 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` 불리언만 포함됩니다.

콜백 구조

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입니다.

다음 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 값 설정

모델 및 모드 선택

작업 흐름

선택적 필드

콜백 구조

결과 필드