Kling

모델 선택과 호출 경로

생성 방식에 따라 모델 코드가 다릅니다.

이 문서에서는 종류 이름으로 모델을 묶어 text-to-video 모델, image-to-video 모델, omni-video 모델이라고 부릅니다. V4 모델은 같은 종류의 V3 모델과 요청 필드가 같습니다. V4 모델은 해상도, 생성 길이와 비율의 선택지가 더 많고 image-to-video와 omni-video에서 중간 프레임과 끝 프레임을 FileInfos로 지정할 수 있습니다. 차이는 각 절과 생성 조건 정하기에서 확인합니다.

현재 스페이스의 이용 가능 여부와 적용 단가는 모델 선택에서 확인합니다. 호출은 Video Generations, 접수 이후 상태와 결과는 Jobs를 사용합니다. 결과 파일은 Seedance와 같은 방식으로 작업 조회와 Media Links에서 받습니다.

요청 필드 이름

Kling 요청은 model과 store_media를 뺀 입력 필드에 Kling 전용 필드 이름을 사용합니다. Prompt, OutputConfig, FileInfos처럼 대소문자까지 맞춰 보냅니다. Seedance의 prompt, references 같은 이름은 Kling 요청에서 쓰지 않습니다.

요청 본문의 최상위 필드는 다음과 같습니다.

표에 없는 필드는 거절됩니다. 모든 모델에서 ExtInfo, SceneType, SubjectInfos, LastFrameFileId, FirstFrameFileId는 거절됩니다. 다음 필드는 렛서가 정하는 값이므로 요청에 넣으면 거절됩니다.

• SubAppId, ModelName, ModelVersion
• OutputConfig의 콘텐츠 심사 설정 InputComplianceCheck, OutputComplianceCheck. 값과 관계없이 거절되며 콘텐츠 심사 해제는 아직 지원하지 않습니다.

텍스트로 생성하기

text-to-video 모델은 텍스트로만 영상을 생성합니다. FileInfos, LastFrameUrl 등 이미지나 영상을 입력하는 필드를 보내면 거절됩니다. 시작 프레임 이미지로 생성하려면 image-to-video 모델을, 참조 이미지나 영상을 입력하려면 omni-video 모델을 사용합니다.

{
  "model": "kling-v3-text-to-video",
  "Prompt": "바람에 천천히 흔들리는 초원의 풀을 고정 카메라로 촬영한 영상",
  "OutputConfig": {"Resolution": "720P", "Duration": 5, "AspectRatio": "16:9"},
  "store_media": false
}

시작 프레임으로 생성하기

image-to-video 모델은 시작 프레임 이미지 한 장과 Prompt로 영상을 생성합니다. FileInfos에 다음 시작 프레임 항목을 정확히 하나 넣습니다.

Url과 끝 프레임 LastFrameUrl에는 References 일반 업로드가 반환한 letsur-file://…, https:// URL 또는 인라인 data:image/…;base64,…를 넣습니다. LastFrameUrl은 선택입니다.

kling-v4-image-to-video는 시작 프레임과 함께 다음 이미지를 FileInfos에 넣을 수 있습니다. 이미지는 시작, 중간과 끝 프레임을 합쳐 10장 이하입니다.

• 중간 프레임: {"Category": "Image", "Usage": "Reference", "ReferenceType": "middle_frame"}. 여러 장 넣을 수 있음
• 끝 프레임: {"Category": "Image", "Usage": "LastFrame"}. LastFrameUrl과 둘 중 하나로 한 번만 보냄

다음 요청은 거절됩니다.

• FileInfos가 없거나 빈 배열이거나 형식이 맞지 않는 요청, Prompt가 없는 요청과 가져올 수 없는 URL
• 영상(Category: "Video")을 넣은 요청
• kling-v3-image-to-video에 시작 프레임 외의 이미지, Usage: "Reference" 또는 ReferenceType을 넣은 요청
• kling-v4-image-to-video에 middle_frame 외의 ReferenceType이나 ReferenceType 없는 Usage: "Reference"를 넣은 요청
• 끝 프레임을 LastFrameUrl과 Usage: "LastFrame" 항목으로 함께 보내거나 LastFrame 항목을 두 개 넣은 요청

참조 이미지나 영상을 입력하려면 omni-video 모델을 사용합니다.

{
  "model": "kling-v3-image-to-video",
  "Prompt": "이미지 속 인형이 천천히 고개를 돌리는 장면",
  "FileInfos": [
    {"Type": "Url", "Category": "Image", "Usage": "FirstFrame", "Url": "https://example.com/first-frame.png"}
  ],
  "OutputConfig": {"Resolution": "720P", "Duration": 5},
  "store_media": false
}

참조 입력과 영상 편집

omni-video 모델은 FileInfos 배열로 이미지와 영상을 입력합니다. 각 항목은 다음 필드로 구성합니다.

omni-video 모델의 Url과 LastFrameUrl에는 다음 값을 넣을 수 있습니다.

• References 일반 업로드가 반환한 letsur-file://…
• https:// URL
• 인라인 data:image/…;base64,…. Category가 Image인 항목과 LastFrameUrl에만 사용

http://, ftp://, 상대 경로, 파일 ID FileId와 관리형 참조 letsur-asset://…는 거절됩니다. Seedance의 인물이 포함된 참조에 쓰는 관리형 업로드는 Kling에서 사용하지 않습니다. 등록 요소 SubjectInfos도 지원하지 않습니다.

끝 프레임은 Usage: "FirstFrame" 이미지가 있을 때만 보낼 수 있습니다. V3 모델은 끝 프레임을 LastFrameUrl로 보냅니다. V4 모델은 LastFrameUrl 또는 Usage: "LastFrame" 이미지 항목 중 하나로 보내며, 둘을 함께 보내거나 LastFrame 항목을 두 개 넣으면 거절됩니다. V4 모델은 ReferenceType: "middle_frame" 이미지로 중간 프레임을 여러 장 지정할 수도 있습니다.

kling-v3-omni-video의 이미지 개수는 다음 한도를 따릅니다.

kling-v4-omni-video는 이미지 10개 이하(시작, 중간과 끝 프레임 포함), 영상 5개 이하, 이미지와 영상 합계 15개 이하를 입력할 수 있습니다. 입력 영상 길이의 합은 30초 이하여야 합니다. 이 길이는 접수할 때 검사하지 않으므로 초과하면 접수 뒤 작업이 실패합니다.

이 한도와 업로드 제한을 통과해도 공급사의 영상 길이, 해상도와 콘텐츠 조건에 따라 거절될 수 있습니다.

프롬프트에서는 <<<image_1>>>, <<<video_1>>>처럼 FileInfos에 넣은 순서로 각 항목을 가리킵니다. 다음은 업로드한 이미지를 참조하는 설명용 본문입니다. letsur-file:// 뒤의 값은 실제 업로드 응답으로 바꿉니다.

{
  "model": "kling-v3-omni-video",
  "Prompt": "<<<image_1>>>의 인형이 해질녘 해변을 천천히 걷는 장면",
  "FileInfos": [
    {"Type": "Url", "Category": "Image", "Usage": "Reference", "Url": "letsur-file://example-file-id"}
  ],
  "OutputConfig": {"Resolution": "720P", "Duration": 5},
  "store_media": true
}

생성 조건 정하기

OutputConfig에 출력 조건을 지정합니다. Duration과 AspectRatio는 모델에 따라 기본값과 검증이 다릅니다.

V4 모델에 AudioGeneration을 보내도 요청은 거절되지 않지만 Disabled를 보내도 결과 영상에 소리가 들어갑니다. V4 모델에서 대사, 환경음, 음악이나 효과음이 필요하면 Prompt에 묘사합니다.

PersonGeneration과 LogoAdd는 모든 Kling 모델에서 사용할 수 있습니다. 생략하면 게이트웨이가 값을 보내지 않으며 모델의 기본 동작을 따릅니다. 표에 없는 값을 보내면 요청이 거절됩니다.

omni-video 모델에서 Duration이나 AspectRatio를 생략하면 게이트웨이가 값을 지정하지 않고 보냅니다. 영상 편집에서는 원본 영상을 따릅니다.

작업 조회의 usage.items[].unit은 모든 Kling 모델에서 second입니다. kling-v4-omni-video를 뺀 Kling 모델의 사용량은 생성된 출력 영상의 길이로 계산합니다. kling-v4-omni-video는 입력 영상의 길이와 출력 영상의 길이를 더해 계산하며, 입력 영상이 없으면 출력 영상의 길이로 계산합니다. 예를 들어 5초 영상을 편집해 5초 영상을 만들면 사용량은 10초입니다. 적용 단가는 해상도 등 생성 조건에 따라 다르며, image-to-video 모델의 단가는 같은 버전의 text-to-video 모델과 같습니다. kling-v3-omni-video는 입력에 영상(Category: "Video")이 있으면 단가가 달라집니다. 모델별 현재 단가는 모델 선택, 비용 확인 방법은 요청별 비용을 따릅니다.

접수와 결과 받기

Kling의 접수 응답은 작업 ID를 Response.TaskId에 담습니다. 값은 Seedance와 같은 렛서 작업 ID lst-…입니다. 응답 형식과 응답을 받지 못했을 때의 대응은 Video Generations 접수 응답에서 확인합니다.

받은 ID로 Jobs를 조회하고, 결과 파일을 영상 생성하고 파일 받기와 같은 순서로 받습니다. store_media의 보관 동작은 결과 보관 선택하기를 따릅니다.