Kling V3.0 모션 컨트롤을 사용하면 참조 영상에서 움직임을 추출하여 프레임별로 적용함으로써 정적 캐릭터 이미지에 애니메이션을 적용할 수 있습니다. 출력 결과는 사용자 이미지의 캐릭터 외형을 유지하면서 영상의 움직임을 재현합니다. 이를 동작 전이 라고 합니다. 이 가이드에서는 Novita AI 엔드포인트, 필수 입력값, 주요 파라미터, 그리고 실제 API 키로 실행할 수 있는 Python 및 curl 예제를 다룹니다.
모션 컨트롤이 적합한 경우
모션 컨트롤은 두 가지 요소가 있을 때 사용하기 좋은 도구입니다: 애니메이션을 적용하려는 정적 캐릭터 이미지와 재현하려는 움직임이 담긴 참조 영상. 프롬프트를 기반으로 움직임을 생성하는 이미지-투-비디오(I2V)와는 다릅니다. 모션 컨트롤에서는 움직임이 참조 영상에서 정확히 복사됩니다. 출력된 캐릭터는 참조 영상 속 인물과 동일한 동작 궤적을 따릅니다.
다음과 같은 경우에 사용하세요:
- 특정 춤, 걷기 패턴, 제스처를 캐릭터 일러스트나 사진에 적용하고 싶을 때
- 서로 다른 캐릭터에 일관되고 반복 가능한 움직임이 필요할 때 (동일한 참조 영상, 다른 이미지)
- 움직임 품질이 중요하고, 개방형 I2V 프롬프트 결과가 너무 예측 불가능할 때
움직임 자체가 아직 정의되지 않은 경우에는 사용하지 마세요. 그런 경우에는 설명적 프롬프트를 사용한 I2V가 더 유연하고 비용이 낮습니다.
1단계: Novita API 키 받기
novita.ai에 가입하고 대시보드에서 API 키를 생성하세요. 새 계정에는 프로덕션 볼륨에 투자하기 전에 모션 컨트롤을 테스트할 수 있는 무료 크레딧이 제공됩니다.
2단계: 엔드포인트 및 모델 ID 확인
Novita AI의 Kling V3.0 모션 컨트롤은 표준 비동기 영상 패턴을 사용합니다:
작업 제출:
POST https://api.novita.ai/v3/async/kling-v3.0-motion-control
결과 폴링:
GET https://api.novita.ai/v3/async/task-result?task_id={task_id}
모든 요청에 필요:
Authorization: Bearer YOUR_NOVITA_API_KEY
Content-Type: application/json
전체 문서: novita.ai/docs/api-reference/model-apis-kling-v3.0-motion-control
3단계: 입력값 준비
모션 컨트롤에는 참조 이미지와 참조 영상 두 가지 입력값이 필요합니다. 이 입력값을 올바르게 준비하는 것이 출력 품질을 결정짓는 가장 중요한 요소입니다.
참조 이미지
출력 결과에 외형이 보존될 캐릭터입니다. 요구 사항:
- 형식: JPEG, PNG, JPG
- 최대 크기: 10MB
- 최소 해상도: 각 변 340px
- 종횡비: 2:5 ~ 5:2
- 캐릭터가 명확히 보여야 하며, 이미지 영역의 5% 이상을 차지하고 심하게 가려지지 않아야 함 (머리나 몸이 잘리지 않도록 주의)
최상의 결과를 얻으려면 캐릭터의 신체 비율이 참조 영상에 보이는 것과 대략 일치하는 이미지를 사용하세요. 참조 영상이 전신 무용수라면 얼굴 클로즈업보다는 전신 캐릭터 이미지를 사용하는 것이 좋습니다.
참조 영상
움직임의 원본입니다. 출력의 캐릭터가 이 영상의 움직임을 복제합니다:
- 형식: MP4, MOV
- 최대 크기: 10MB
- 길이: 3~30초
- 최소 해상도: 각 변 340px
- 종횡비: 2:5 ~ 5:2
- 참조 영상 속 인물은 머리를 포함하여 전신 또는 상체가 보이고 가려짐이 없어야 함
배경이 깔끔하고 조명이 밝은 영상이 노이즈가 많거나 복잡한 장면보다 움직임을 더 정확하게 전이합니다.
4단계: 첫 번째 요청 보내기
최소 curl 요청:
curl --request POST \
--url https://api.novita.ai/v3/async/kling-v3.0-motion-control \
--header 'Authorization: Bearer $NOVITA_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"image": "https://example.com/character.jpg",
"video": "https://example.com/reference_motion.mp4",
"prompt": "A person performing a smooth dance routine, cinematic lighting",
"model_name": "kling-v3.0-motion-control",
"character_orientation": "video"
}'
응답은 즉시 task_id를 반환합니다:
{
"task_id": "abc123xyz"
}
5단계: 결과 폴링
Kling V3.0 모션 컨트롤은 비동기 방식입니다. 작업을 제출한 후 상태가 succeed가 될 때까지 폴링합니다:
curl --request GET \
--url 'https://api.novita.ai/v3/async/task-result?task_id=abc123xyz' \
--header 'Authorization: Bearer $NOVITA_API_KEY'
완료되면 응답에 출력 URL이 포함된 videos 배열이 있습니다:
{
"task": {
"status": "succeed"
},
"videos": [
{
"video_url": "https://cdn.novita.ai/output/abc123xyz.mp4",
"video_url_ttl": "3600"
}
]
}
일반적인 생성 시간은 영상 길이와 모드에 따라 30~120초입니다. 엔드포인트에 과도한 요청을 보내지 말고 5~10초마다 폴링하세요.
전체 Python 통합 예제
이 스크립트는 모션 컨트롤 작업을 제출하고 완료될 때까지 폴링합니다:
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_motion_control(image: str, video: str, prompt: str = "") -> str:
payload = {
"image": image,
"video": video,
"prompt": prompt,
"model_name": "kling-v3.0-motion-control",
"character_orientation": "video",
}
resp = requests.post(f"{BASE_URL}/v3/async/kling-v3.0-motion-control", json=payload, headers=HEADERS)
resp.raise_for_status()
return resp.json()["task_id"]
def poll_result(task_id: str, timeout: int = 300) -> str:
deadline = time.time() + timeout
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}/v3/async/task-result",
params={"task_id": task_id},
headers=HEADERS,
)
resp.raise_for_status()
data = resp.json()
status = data.get("task", {}).get("status")
if status == "succeed":
return data["videos"][0]["video_url"]
if status == "failed":
raise RuntimeError(f"Task failed: {data}")
time.sleep(8)
raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")
if __name__ == "__main__":
image = "https://example.com/character.jpg"
video = "https://example.com/reference_motion.mp4"
print("Submitting task...")
task_id = submit_motion_control(image, video, prompt="smooth dance routine, warm lighting")
print(f"Task ID: {task_id}")
print("Polling for result...")
output_url = poll_result(task_id)
print(f"Output video: {output_url}")
API 파라미터 참조
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
image |
string | 예 | 애니메이션할 캐릭터 이미지의 URL입니다. 위 입력 요구 사항을 참조하세요. |
video |
string | 예 | 움직임이 전이될 참조 영상의 URL입니다. |
model_name |
string | 예 | kling-v3.0-motion-control로 설정합니다. |
prompt |
string | 아니요 | 원하는 동작 스타일이나 장면 맥락에 대한 텍스트 설명입니다. 선택 사항이지만 출력 품질을 개선할 수 있습니다. |
character_orientation |
string | 아니요 | 포즈 정렬 및 출력 길이를 제어합니다. "video"는 참조 영상 방향과 일치시켜 복잡한 전신 동작에 더 좋으며 최대 30초를 지원합니다. "image"는 캐릭터 이미지 방향과 일치시켜 카메라 상대적 움직임에 더 좋으며 5초로 고정됩니다. |
실제 사용 시 character_orientation
참조 영상이 정면을 향한 무용수를 보여주고 캐릭터 이미지도 정면을 향한 경우, "video"는 더 나은 동작 전이를 제공하며 최대 30초를 지원합니다. 참조 영상의 카메라가 피사체 주위를 움직이고 이미지가 고정된 각도의 초상화인 경우, "image"는 원치 않는 원근 왜곡을 줄이는 경향이 있지만 5초짜리 고정 길이 클립을 생성합니다.
Standard vs. Pro: 어떤 품질 등급을 선택할까
Kling V3.0 모션 컨트롤은 두 가지 품질 등급으로 제공됩니다:
Standard 는 720p로 출력합니다. 반복 작업, 모션 호환성 테스트, 최종 버전 확정 전 초안 생성에 적합합니다.
Pro 는 1080p로 출력하며 향상된 동작 충실도와 피사체 일관성을 제공합니다. Pro를 사용해야 하는 경우:
- 출력물이 완성된 프로덕션(소셜 게시물, 단편 영화, 제품 데모)에 투입될 때
- 캐릭터 얼굴이나 의상의 세부 묘사가 중요할 때
- 더 긴 클립(10초 이상)을 생성하여 시간에 따른 품질 저하가 더 눈에 띌 때
대부분의 개발 워크플로우에서는 Standard로 시작하여 입력 호환성과 동작 품질을 확인한 후, 최종 패스에서 Pro로 전환하세요.
가격, 길이 및 비용 추정
Novita AI는 생성된 영상 1초당 모션 컨트롤 비용을 청구합니다. Standard와 Pro 등급은 각각 초당 요금이 다릅니다. 현재 가격은 Novita AI 모델 페이지를 확인하세요.
길이 제한:
character_orientation: "video"— 최대 30초character_orientation: "image"— 5초 고정
비용은 "video" 모드에서 길이에 비례합니다. "image" 모드는 항상 5초 클립을 생성합니다.
일반적인 오류 해결
작업이 422 또는 유효성 검사 오류와 함께 즉시 실패함
image와 video가 모두 공개적으로 접근 가능한 URL인지 확인하세요(인증이 필요하거나 만료된 단기 서명 URL이 아닌지). Novita 백엔드는 작업 실행 시 두 파일을 모두 가져올 수 있어야 합니다.
출력 동작이 어색하거나 캐릭터가 왜곡됨
가장 흔한 원인은 이미지의 캐릭터 방향과 참조 영상 간의 불일치입니다. character_orientation을 "video"와 "image" 사이에서 전환하여 더 나은 정렬을 보이는 쪽을 선택해보세요.
클립 중간에 캐릭터의 얼굴 정체성이 손실됨 참조 이미지의 캐릭터가 얼굴과 몸이 명확하고 가려짐이 없는지 확인하세요. 긴 클립의 경우 Pro 등급이 Standard보다 피사체 일관성을 더 잘 유지합니다.
참조 영상의 움직임이 깔끔하게 전이되지 않음 노이즈가 많거나 복잡한 참조 영상은 동작 추출을 저하시킵니다. 수행자가 합리적으로 깨끗한 배경 앞에서 주 피사체인 영상을 사용하세요. 부드러운 동작 전이가 목표라면 손떨림이 심한 영상은 피하세요.
상태가 3분 이상 processing에 머물러 있음
가끔 큐 지연이 발생할 수 있습니다. 중단된 것으로 간주하기 전에 최대 5분까지 기다리세요. 계속 중단된 상태로 남아 있으면 새 작업을 제출하세요. 이전 task_id를 재사용하지 마세요.
개발자들이 Kling 모션 컨트롤로 구축하는 것
게임 에셋용 캐릭터 애니메이션: 캐릭터 일러스트를 가져와 리깅이나 애니메이션 소프트웨어 없이 참조 동작 클립(걷기, 달리기, 공격)을 적용합니다.
일관된 동작의 소셜 콘텐츠: 동일한 댄스 참조 영상을 여러 캐릭터 이미지에 적용하여 안무는 동일하지만 외형이 다른 일련의 클립을 제작합니다.
사전 시각화: 전체 프로덕션 애니메이션에 투자하기 전에 특정 움직임 시퀀스가 캐릭터 디자인에 어떻게 보일지 테스트합니다.
이커머스 제품 디스플레이: 의류 움직임을 보여주는 신중하게 선택된 참조 영상을 사용하여 제품 이미지에 미묘한 포즈 변화나 옷의 움직임을 적용합니다.
FAQ
Novita AI에서 모션 컨트롤과 이미지-투-비디오의 차이점은 무엇인가요?
이미지-투-비디오(I2V)는 텍스트 프롬프트를 기반으로 이미지에 애니메이션을 적용합니다. 움직임은 설명을 기반으로 모델이 생성합니다. 모션 컨트롤은 참조 영상의 특정 움직임을 이미지의 캐릭터로 전이합니다. 모션 컨트롤은 정확하고 재현 가능한 움직임을 제공하고, I2V는 참조 클립 없이 창의적인 유연성을 제공합니다.
참조 영상의 캐릭터가 이미지 캐릭터의 외형과 일치해야 하나요?
아니요. 참조 영상은 동작 추출에만 사용됩니다. 출력 캐릭터는 영상이 아닌 이미지에서 가져옵니다. 이것이 핵심 기능입니다. 한 소스에서는 움직임, 다른 소스에서는 외형. 최상의 전이 품질을 위해 비율이 대략 일치해야 합니다(전신 영상에는 전신 이미지, 상체 영상에는 초상화).
공개적으로 사용 가능한 모든 영상을 참조로 사용할 수 있나요?
형식과 크기 요구 사항을 충족하는 모든 영상을 사용할 수 있습니다. 피사체가 명확하게 보이고 최소한의 가려짐이 있는 영상에서 동작 전이가 가장 잘 됩니다. 복잡한 다중 인물 장면이나 과도하게 편집된 영상(컷, 줌)은 정확도를 떨어뜨릴 수 있습니다.
생성 시간은 얼마나 걸리나요?
일반적으로 출력 길이와 Standard 또는 Pro 모드 선택에 따라 30~120초입니다. 짧은 간격으로 반복하지 말고 8~10초마다 폴링하세요.
