Kling AI 이미지-투-비디오은(는) 무엇을 하나요?
개요
/v1/videos/image2video 엔드포인트를 사용하여 정적 이미지를 애니메이션화합니다. 모션 프롬프트, 카메라 제어, 동적 마스크(모션 브러시), 정적 마스크, 시작-끝 전환을 위한 이미지 테일을 지원합니다.
엔드포인트: POST https://api.klingai.com/v1/videos/image2video
요청 매개변수
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
model_name | string | 예 | kling-v1-5, kling-v2-1, kling-v2-master 등 |
image | string | 예 | 소스 이미지의 URL (JPG, PNG, WebP) |
prompt | string | 아니요 | 애니메이션의 움직임 설명 |
negative_prompt | string | 아니요 | 제외할 내용 |
duration | string | 예 | "5" 또는 "10" 초 |
aspect_ratio | string | 아니요 | "16:9" 기본값 |
mode | string | 아니요 | "standard" 또는 "professional" |
cfg_scale | float | 아니요 | 프롬프트 준수 정도 (0.0-1.0) |
image_tail | string | 아니요 | 마지막 프레임 이미지 URL (마스크/카메라와 상호 배타적) |
camera_control | object | 아니요 | 카메라 움직임 (마스크/image_tail과 상호 배타적) |
static_mask | string | 아니요 | 고정 영역을 위한 마스크 이미지 URL |
dynamic_masks | array | 아니요 | 모션 브러시 궤적 |
callback_url | string | 아니요 | 완료 알림을 위한 웹훅 |
기본 이미지-투-비디오
import jwt, time, os, requests
BASE = "https://api.klingai.com/v1"
def get_headers():
ak, sk = os.environ["KLING_ACCESS_KEY"], os.environ["KLING_SECRET_KEY"]
token = jwt.encode(
{"iss": ak, "exp": int(time.time()) + 1800, "nbf": int(time.time()) - 5},
sk, algorithm="HS256", headers={"alg": "HS256", "typ": "JWT"}
)
return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
# 풍경 사진을 애니메이션화
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-1",
"image": "https://example.com/landscape.jpg",
"prompt": "구름이 하늘에 천천히 떠다니고, 부드러운 바람이 나무를 흔들다",
"negative_prompt": "정적, 움직임 없음, 흐릿함",
"duration": "5",
"mode": "standard",
})
task_id = response.json()["data"]["task_id"]
# 결과 폴링
while True:
time.sleep(15)
result = requests.get(
f"{BASE}/videos/image2video/{task_id}", headers=get_headers()
).json()
if result["data"]["task_status"] == "succeed":
print(f"비디오: {result['data']['task_result']['videos'][0]['url']}")
break
elif result["data"]["task_status"] == "failed":
raise RuntimeError(result["data"]["task_status_msg"])
시작-끝 전환 (image_tail)
image_tail을 사용하여 첫 번째 프레임과 마지막 프레임을 모두 지정합니다. Kling이 그 사이의 움직임을 보간합니다.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://example.com/sunrise.jpg", # 첫 번째 프레임
"image_tail": "https://example.com/sunset.jpg", # 마지막 프레임
"prompt": "태양이 하늘을 가로지르는 타임랩스",
"duration": "5",
"mode": "professional",
})
모션 브러시 (dynamic_masks)
이미지의 특정 요소에 대한 움직임 경로를 그립니다. v2.6에서는 이미지당 최대 6개의 움직임 경로를 지원합니다.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-6",
"image": "https://example.com/person-standing.jpg",
"prompt": "사람이 자연스럽게 앞으로 걸어가는 모습",
"duration": "5",
"dynamic_masks": [
{
"mask": "https://example.com/person-mask.png", # 흰색 = 선택된 영역
"trajectories": [
{"x": 0.5, "y": 0.7, "t": 0.0}, # 시작 위치 (정규화 0-1)
{"x": 0.5, "y": 0.5, "t": 0.5}, # 중간점
{"x": 0.5, "y": 0.3, "t": 1.0}, # 끝 위치
]
}
],
})
정적 마스크 (영역 고정)
이미지의 특정 영역을 정적으로 유지하면서 나머지 부분을 애니메이션화합니다.
response = requests.post(f"{BASE}/videos/image2video", headers=get_headers(), json={
"model_name": "kling-v2-master",
"image": "https://example.com/scene.jpg",
"prompt": "강물이 흐르고 새들이 날아다니는 모습",
"duration": "5",
"static_mask": "https://example.com/buildings-mask.png", # 흰색 = 고정
})
상호 배타성 규칙
다음 기능들은 단일 요청에서 함께 사용할 수 없습니다:
| 기능 세트 A | 기능 세트 B |
|---|---|
image_tail | dynamic_masks, static_mask, camera_control |
dynamic_masks / static_mask | image_tail, camera_control |
camera_control | image_tail, dynamic_masks, static_mask |
이미지 요구 사항
| 제약 조건 | 값 |
|---|---|
| 형식 | JPG, PNG, WebP |
| 최대 크기 | 10 MB |
| 최소 해상도 | 300x300 px |
| 최대 해상도 | 4096x4096 px |
| 마스크 형식 | 흰색(선택) / 검은색(제외) PNG |
오류 처리
| 오류 | 원인 | 해결 방법 |
|---|---|---|
400 유효하지 않은 이미지 | URL에 접근할 수 없거나 형식이 잘못됨 | 이미지 URL이 공개적으로 접근 가능한지 확인 |
400 상호 배타성 | 호환되지 않는 기능 결합 | 요청당 하나의 기능 세트만 사용 |
task_status: failed | 이미지가 너무 복잡하거나 품질이 낮음 | 더 높은 해상도, 더 선명한 소스 사용 |
| 마스크 불일치 | 마스크 크기가 소스와 다름 | 마스크가 소스 이미지 크기와 일치하는지 확인 |
전제 조건
- 런타임 비밀 관리자에 저장된 Kling API 자격 증명, 승인된 모델 및 기간 허용 목록, 작업당 크레딧 예산.
- 합성 또는 권리 정리가 완료된 소스 이미지와 모든 마스크 또는 테일 이미지, 식별 가능한 개인에 대한 동의 기록 및 에셋 변환 권한.
- 비공개 스테이징 버킷과 검토 담당자. 새로 생성된 결과물은 정책, 품질 및 게시 승인이 기록될 때까지 초안 전용 및 워터마크 상태를 유지해야 합니다.
지침
- 승인된 허용 목록에서 소스 및 마스크 참조를 확인하고, 신뢰할 수 없는 URL, 출처가 불분명한 데이터 또는 문서화된 동의 없이 식별 가능한 개인이 포함된 에셋은 거부합니다.
- 크레딧을 사용하기 전에 형식, 크기, 기능 상호 배타성, 프롬프트 길이 및 요청된 기간을 검증합니다. 자동화된 확인을 위해 합성 테스트 데이터를 사용합니다.
- 안정적인 작업 키를 사용하여 요청을 중복 제거하고, 콘텐츠 정책 확인이 통과된 후에만 제출하며, 작업과 소스를 비공개 스테이징 저장소에 보관합니다.
- 하나의 짧고 워터마크가 포함된 샌드박스 카나리를 실행합니다. 더 크거나 공개 렌더링을 위한 소유자 승인을 요청하기 전에 움직임, 정책 결과, 소스 충실도 및 크레딧 예산을 확인합니다.
- 승인 시, 동일한 정확한 작업 결과를 다이제스트(digest)로 승격합니다. 실패 또는 철회 시, 다운스트림 게시를 중지하고, 스테이징된 미디어와 임시 URL을 제거하며, 이전에 승인된 에셋 또는 작업 상태를 복원합니다.
- 불투명한 작업 및 에셋 다이제스트, 정책 및 승인 결과, 예산 결과, 보존 기한 및 롤백 참조만 포함하는 수정된 영수증을 기록합니다.
출력
불투명한 작업 식별자, 모델 및 기간, 상태, 출력 다이제스트 또는 비공개 스테이징 URL, 카나리/승인 상태, 정리 또는 롤백 참조가 포함된 결과를 반환합니다. 소스 이미지, 마스크 URL, 프롬프트, 얼굴 데이터, 자격 증명 또는 수정되지 않은 공급자 응답을 로그나 영수증에 포함하지 마십시오.
예시
안전한 자동화 확인을 위해 합성 풍경 테스트 데이터와 비공개 카나리를 사용합니다:
source=fixture:synthetic-landscape-v3; rights=cleared; mode=standard;
duration=5; canary=watermarked-sandbox; policy=pass; approval=pending;
publish=false; contacts_exported=0; receipt=asset-sha256:opaque
동의, 정책, 품질 및 소유자 승인이 모두 기록될 때까지 라이브 고객 사진을 대체하거나 카나리를 게시하지 마십시오.