2026-09-26모델

모션 컨트롤 API: 드라이빙 영상으로 이미지 움직이기

Sume의 Kling 3.0 Motion Control은 최대 30초 길이의 드라이빙 영상에서 움직임을 가져와 스틸 이미지를 움직입니다. 요청 필드, 제한, 가격을 다룹니다.

읽는 시간 5분Sume

스틸 이미지를 영상의 움직임대로 움직이려면 image_url에 이미지를, motion_video_url에 움직임을 가져올 드라이빙 클립을, duration_seconds에 그 클립의 길이를 담아 POST /v1/kling/3.0/motion-control을 보내세요. Kling 3.0 Motion Control은 Sume Job으로 실행되며, 출력 길이는 드라이빙 영상을 따릅니다.

필드 규칙은 Sume API 레퍼런스의 요청 스키마에서 가져왔습니다. 이 레퍼런스는 API 레퍼런스 문서가 소스 오브 트루스로 삼는 OpenAPI 문서입니다. 공통 Job 라이프사이클은 Models 개요 (영문)에서 가져왔으며, 모두 2026-09-26에 확인했습니다. 가격은 Sume의 가격 코드에서 읽었습니다.

Kling 3.0 Motion Control은 무엇을 하나요?

공개 이미지나 준비된 아바타 중 하나를 스틸로 받아, 직접 제공한 드라이빙 영상의 움직임으로 움직입니다. 선택 필드인 prompt는 외형 세부만 조정하며, 움직임은 드라이빙 영상에서 옵니다. character_orientation은 어느 쪽 프레이밍을 따를지 정합니다. video(기본값)는 드라이빙 영상의 방향을, image는 스틸의 방향을 유지합니다.

Kling 3.0은 POST /v1/videos의 영상 카탈로그에도 kling-3 모델로 올라 있으며, 이는 별개의 모델 ID입니다. Kling을 직접 호출하는 방식과 Sume를 통해 호출하는 방식은 Sume vs Kling에서 비교합니다. 대신 오디오 트랙으로 스틸이 말하게 하려면 립싱크 API 가이드를 참고하세요.

모션 컨트롤 요청은 어떻게 보내나요?

생성 요청마다 Idempotency-Key를 보내세요. 같은 페이로드로 키를 다시 쓰면 원래 Job이 idempotency_hit: true와 함께 반환되므로, 재시도해도 비용을 두 번 내지 않습니다. 아래 요청은 12초 길이의 댄스 클립으로 캐릭터 스틸을 움직입니다.

curl -X POST https://api.sume.com/v1/kling/3.0/motion-control \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: motion-clip-001" \
  -d '{
    "image_url": "https://example.com/character.png",
    "motion_video_url": "https://example.com/dance-reference.mp4",
    "duration_seconds": 12,
    "prompt": "Keep the red jacket and the studio backdrop",
    "character_orientation": "video"
  }'

요청에는 어떤 필드가 들어가나요?

motion_video_url과 duration_seconds는 필수이며, 시각 소스도 정확히 하나 있어야 합니다.

Sume API 레퍼런스의 Kling 3.0 Motion Control 요청 스키마 기준, 2026-09-26 확인.
필드	받는 값
`image_url`	움직일 스틸 이미지의 공개 HTTPS URL. `avatar_id` / `avatar_handle`과 함께 쓸 수 없음.
`avatar_id` 또는 `avatar_handle`	준비된 아바타. 서버에서 아바타 아이덴티티 스틸로 변환됨.
`motion_video_url`	필수. 가져올 수 있는 공개 HTTPS 모션 레퍼런스 영상, 최대 30초.
`duration_seconds`	필수. 1–30. 드라이빙 영상의 길이로, 제출 시 크레딧을 예약하는 데 쓰임.
`prompt`	선택, 최대 2,000자. 외형 세부만 조정.
`keep_original_sound`	드라이빙 영상의 오디오 트랙 유지(기본값 `true`). `false`면 무음 클립.
`character_orientation`	`video`(기본값) 또는 `image`.
`mode`, `webhook_url`, `wait_timeout_seconds`	결과를 받는 방식. `wait_timeout_seconds`는 0–30.

페이스 컨트롤 경로는 무엇인가요?

POST /v1/avatar-1.0/motion-control은 같은 엔드포인트의 페이스 컨트롤 별칭입니다. 본문도 같으며, 이 경로로 만든 Job에는 공개 모델 ID kling/3.0/motion-control이 저장됩니다. 준비된 아바타의 아이덴티티 스틸을 움직이려면 image_url 대신 avatar_id나 avatar_handle을 보내세요. 아바타를 만드는 방법은 재사용 가능한 AI 아바타 만들기에서 다룹니다.

두 경로에는 같은 본문을 받는 model-run 짝도 각각 있습니다. POST /v1/models/kling/3.0/motion-control/runs와 POST /v1/models/sume/avatar-1.0/motion-control/runs입니다.

클립은 어떻게 받고, 비용은 얼마인가요?

제출 응답의 job.id, status_url, result_url을 저장하고 상태를 폴링한 뒤, result_ready가 true가 되면 /result를 가져오세요. 미디어 Job은 Sume가 호스팅하는 산출물을 반환합니다. webhook_url은 종료 이벤트인 job.completed, job.failed, job.canceled만 받습니다.

Kling 3.0 Motion Control의 요금은 출력 초당 $0.1575이며, 기본적으로 5.5% 에이전트 수수료가 더해집니다. 드라이빙 영상 길이를 초 단위로 올림해 과금하며, 제출 시에는 duration_seconds가 그 금액을 예약합니다. 12초짜리 드라이빙 영상이라면 수수료 전 $1.89입니다. 실패한 Job과 생성이 시작되기 전에 취소된 Job은 확정 전에 환불됩니다.

어떤 제한이 있나요?

스키마와 API 레퍼런스에 정해진 규칙은 다음과 같습니다.

드라이빙 영상은 가져올 수 있는 공개 HTTPS URL이어야 하고 길이는 최대 30초이며, duration_seconds는 1에서 30 사이여야 합니다.
시각 소스는 image_url 또는 avatar_id / avatar_handle 중 정확히 하나여야 합니다. 둘은 함께 쓸 수 없습니다.
localhost, 사설 네트워크, HTTPS가 아닌 미디어 URL은 생성 제출 전에 거부됩니다.
prompt는 최대 2,000자이며 움직임을 바꾸지 않습니다.
공급사 큐 ID는 Sume가 고르며, 요청에 넣을 수 없습니다.
402는 잔액으로 예상 금액을 감당할 수 없다는 뜻이며, 이때 생성 Job은 시작되지 않습니다.

출처

작성자 Sume