Kling V3.0 Motion Control을 사용하면 참조 비디오에서 모션을 추출하여 프레임별로 적용함으로써 정적 캐릭터 이미지를 애니메이션화할 수 있습니다. 출력물은 이미지의 캐릭터 외형을 유지하면서 비디오의 움직임을 재현합니다. 이를 모션 트랜스퍼(motion transfer)라고 합니다. 이 가이드에서는 Novita AI 엔드포인트, 필수 입력 사항, 주요 파라미터, 실제 API 키로 실행할 수 있는 Python 및 curl 예제를 다룹니다.
Motion Control을 사용해야 하는 경우
Motion Control은 두 가지가 있을 때 적합한 도구입니다. 애니메이션화하려는 정적 캐릭터 이미지와 재현하려는 모션이 담긴 참조 비디오입니다. 프롬프트에서 모션을 생성하는 Image-to-Video(I2V)와는 다릅니다. Motion Control을 사용하면 참조 비디오에서 모션을 정확히 복사하므로 출력 캐릭터는 참조 비디오의 인물과 동일한 동작 궤적을 따릅니다.
다음과 같은 경우에 사용하세요:
- 특정 춤, 걷기 주기, 제스처를 캐릭터 일러스트나 사진에 적용하려는 경우
- 서로 다른 캐릭터에서 일관되고 반복 가능한 모션이 필요한 경우 (동일한 참조 비디오, 다른 이미지)
- 모션 품질이 중요하고 개방형 I2V 프롬프트 결과가 너무 예측 불가능한 콘텐츠를 제작하는 경우
모션 자체가 아직 정의되지 않은 경우에는 사용하지 마세요. 이 경우 설명적인 프롬프트를 사용한 I2V가 더 낮은 비용으로 더 큰 유연성을 제공합니다.
1단계: Novita API 키 받기
novita.ai에 가입하고 대시보드에서 API 키를 생성하세요. 새 계정에는 프로덕션 규모로 전환하기 전에 Motion Control을 테스트하는 데 사용할 수 있는 무료 크레딧이 제공됩니다.
2단계: 엔드포인트 및 모델 ID 확인
Novita AI의 Kling V3.0 Motion Control은 표준 비동기 비디오 패턴을 사용합니다.
작업 제출:
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단계: 입력 준비
Motion Control에는 참조 이미지와 참조 비디오라는 두 가지 입력이 필요합니다. 이 입력을 올바르게 준비하는 것이 출력 품질을 결정하는 가장 큰 요소입니다.
참조 이미지
출력물이 외형을 유지할 캐릭터입니다. 요구 사항:
- 형식: JPEG, PNG, JPG
- 최대 크기: 10 MB
- 최소 해상도: 각 변 340px
- 종횡비: 2:5 ~ 5:2
- 캐릭터가 선명하게 보여야 하며, 이미지 영역의 5% 이상을 차지하고, 심한 가림이 없어야 합니다 (머리나 몸을 자르지 마세요).
최상의 결과를 얻으려면 캐릭터의 신체 비율이 참조 비디오에 보이는 것과 대략 일치하는 이미지를 사용하세요. 참조 비디오가 전신 댄서를 보여준다면 인물 크롭 대신 전신 캐릭터 이미지를 사용하세요.
참조 비디오
모션 소스입니다. 출력물의 캐릭터는 이 비디오의 움직임을 복제합니다:
- 형식: MP4, MOV
- 최대 크기: 10 MB
- 길이: 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 Motion Control은 비동기 방식입니다. 작업을 제출한 후 상태가 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 Motion Control은 두 가지 품질 등급으로 제공됩니다.
Standard 모드는 720p로 출력합니다. 반복 작업, 모션 호환성 테스트, 최종 버전 확정 전 초안 생성에 적합한 선택입니다.
Pro 모드는 향상된 모션 정확도와 피사체 일관성으로 1080p로 출력합니다. Pro는 다음 경우에 사용하세요:
- 출력물이 완성된 프로덕션(소셜 게시물, 단편 영화, 제품 데모)에 사용되는 경우
- 캐릭터의 얼굴이나 의복의 디테일이 중요한 경우
- 시간이 지남에 따라 품질 저하가 더 눈에 띄는 긴 클립(10초 이상)을 생성하는 경우
대부분의 개발 워크플로에서는 Standard로 시작하여 입력 호환성과 모션 품질을 확인한 다음 최종 패스에서 Pro로 전환하세요.
가격, 길이, 비용 추정
Novita AI는 생성된 비디오 1초당 Motion Control 비용을 청구합니다. 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 Motion Control로 만드는 것들
게임 에셋용 캐릭터 애니메이션: 리깅이나 애니메이션 소프트웨어 없이 캐릭터 일러스트에 참조 모션 클립(걷기, 달리기, 공격)을 적용합니다.
일관된 모션의 소셜 콘텐츠: 동일한 댄스 참조 비디오를 여러 캐릭터 이미지에 적용하여 동일한 안무지만 다른 외형을 가진 일련의 클립을 생성합니다.
프리비주얼라이제이션: 전체 프로덕션 애니메이션에 투자하기 전에 특정 움직임 시퀀스가 캐릭터 디자인에서 어떻게 보이는지 테스트합니다.
이커머스 제품 표시: 의류 움직임을 보여주는 신중하게 선택된 참조 비디오를 사용하여 제품 이미지에 미묘한 포즈 변화나 옷의 움직임을 적용합니다.
FAQ
Novita AI에서 Motion Control과 Image-to-Video의 차이점은 무엇인가요?
Image-to-Video(I2V)는 텍스트 프롬프트를 기반으로 이미지를 애니메이션화합니다. 모션은 사용자 설명에서 모델이 생성합니다. Motion Control은 참조 비디오의 특정 모션을 이미지의 캐릭터에 전송합니다. Motion Control은 정확하고 재현 가능한 모션을 제공하고, I2V는 참조 클립 없이 창의적인 유연성을 제공합니다.
참조 비디오의 캐릭터가 이미지 캐릭터의 외형과 일치해야 하나요?
아니요. 참조 비디오는 모션 추출에만 사용됩니다. 출력 캐릭터는 비디오가 아니라 이미지에서 나옵니다. 이것이 핵심 기능입니다. 한 소스에서 모션을, 다른 소스에서 외형을 가져옵니다. 최상의 전송 품질을 위해 비율이 대략 일치해야 합니다 (전신 비디오에는 전신 이미지, 상체 비디오에는 인물 사진).
공개적으로 사용 가능한 비디오를 참조로 사용할 수 있나요?
형식과 크기 요구 사항을 충족하는 모든 비디오를 사용할 수 있습니다. 모션은 피사체가 최소한의 가림으로 선명하게 보이는 영상에서 가장 잘 전송됩니다. 복잡한 다인 장면이나 과도하게 편집된 영상(컷, 줌)은 정확도를 떨어뜨릴 수 있습니다.
생성에는 시간이 얼마나 걸리나요?
일반적으로 출력 길이와 Standard 또는 Pro 모드 선택에 따라 30~120초가 걸립니다. 긴밀한 루프보다는 8~10초 간격으로 폴링하세요.
