WAND wiki
최근 문서

검색 결과가 없습니다. 모델명이나 다른 키워드로 검색해 보세요.

↑ ↓ 이동 ↵ 열기전체 결과 보기 →
VOD APILast Updated 2026-09-05

Kling

On this page

Endpoint: POST https://vod.intl.tencentcloudapi.com
Action: CreateAigcVideoTask

기본 정보

항목 값
ModelName Kling
ModelVersion 3.0 / 3.0-turbo / 3.0-Omni / O1 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6
기본값 ModelVersion=3.0 / Resolution=1080P
가드레일 해제 지원 지원

버전별 지원 규격

버전 해상도 비율 길이
공통 480P / 720P / 1080P / 2K / 4K — —
3.0-turbo 720P / 1080P / 2K / 4K 텍스트 생성 16:9 / 9:16 / 1:1 3–15초

입력 조건

버전 조건
3.0-turbo 텍스트 또는 첫 프레임 이미지 1장

요청 파라미터

파라미터 필수 타입 설명
ModelName 필수 String 고정값 Kling
ModelVersion 선택 String 3.0 / 3.0-turbo / 3.0-Omni / O1 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6
Prompt 필수 String 생성 프롬프트
FileInfos.N 선택 Array 참조 입력. Usage는 FirstFrame(첫 프레임) 또는 Reference(참조)
OutputConfig.Resolution 선택 String 480P / 720P / 1080P / 2K / 4K
OutputConfig.Duration 선택 Integer 영상 길이(초)
OutputConfig.AspectRatio 선택 String 16:9 / 9:16 / 1:1 등
ExtInfo 선택 String 2중 JSON 인코딩. 아래 고급 기능(동작 제어, 립싱크, 디지털 휴먼)의 세부 파라미터를 전달합니다.
FirstFrameFileId / LastFrameUrl 선택 String 첫/끝 프레임 생성용. 참조 프레임을 FileInfos의 Usage=FirstFrame으로, 끝 프레임을 LastFrameUrl/LastFrameFileId로 지정 (2.1 버전은 1080P 필수)
OutputConfig.
InputComplianceCheck		 선택 String Disabled를 명시적으로 전달하면 입력 심사 해제. 사용 전 영업담당자 문의
OutputConfig.
OutputComplianceCheck		 선택 String Disabled를 명시적으로 전달하면 출력 심사 해제. 사용 전 영업담당자 문의

요청 예시

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "3.0",
  "Prompt": "a calm sunset over the ocean, cinematic",
  "OutputConfig": {
    "Resolution": "1080P",
    "Duration": 5,
    "AspectRatio": "16:9",
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

응답 예시

LANGUAGE
{
  "AigcVideoTask": {
    "Status": "FINISH",
    "ErrCode": 0,
    "Progress": 100,
    "Output": {
      "FileInfos": [
        {
          "FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcVideoGenFile.mp4",
          "ExpireTime": "2026-08-01T10:29:48Z",
          "MetaData": {
            "Width": 1920,
            "Height": 1080,
            "Duration": 5.07,
            "Container": "mov,mp4,m4a",
            "Bitrate": 9494850
          }
        }
      ]
    }
  }
}

참조 개수 제한 (Kling 기준)

참조 이미지와 참조 참조 대상, 참조 영상의 수는 서로 영향을 줍니다.

조건 제한
참조 영상 있음 참조 이미지 수 + 참조 참조 대상 수 합산 4 이하
참조 영상 — 참조 이미지 수 + 참조 참조 대상 수 합산 7 이하
끝 프레임 사용 참조 이미지 최대 2장

ErrCode까지 확인해야 합니다

완료 응답의 Status="FINISH"와 ErrCode=0을 함께 확인합니다.

특수 설정

가드레일 해제

입력과 출력 심사를 각각 설정할 수 있습니다.

가드레일 해제 파라미터를 사용하려면 먼저 영업담당자에게 연락해 사용 권한을 확인해야 합니다. 지원 엔진에서도 해당 파라미터를 명시적으로 전달하는 경우에만 가드레일 해제가 적용됩니다. 파라미터를 생략하면 해제되지 않습니다.

파라미터 해제 값 적용 대상
OutputConfig.InputComplianceCheck Disabled 입력 심사 해제
OutputConfig.OutputComplianceCheck Disabled 출력 심사 해제

다음 설정을 기존 생성 요청에 병합합니다. 입력과 출력 심사를 모두 해제하려면 두 필드를 함께 전달합니다.

LANGUAGE
{
  "OutputConfig": {
    "InputComplianceCheck": "Disabled",
    "OutputComplianceCheck": "Disabled"
  }
}

첫/끝 프레임 생성 (First / Last Frame)

시작 프레임과 종료 프레임 이미지를 주면 두 프레임 사이를 자연스럽게 이어 붙인 영상을 만듭니다. 첫 프레임은 FileInfos에 Usage=FirstFrame으로, 끝 프레임은 LastFrameUrl(또는 LastFrameFileId)로 지정합니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "2.1",
  "Prompt": "camera slowly pushes in, cinematic",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Usage": "FirstFrame",
      "Url": "https://<cdn>/first.jpg"
    }
  ],
  "LastFrameUrl": "https://<cdn>/last.jpg",
  "OutputConfig": {
    "Resolution": "1080P",
    "Duration": 5,
    "AspectRatio": "16:9",
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

2.1 버전은 1080P 필수

Kling 2.1의 첫/끝 프레임 생성은 OutputConfig.Resolution=1080P를 사용합니다.

동작 제어 (motion_control)

참조 영상의 동작을 인물 이미지에 입혀 새 영상을 만듭니다. SceneType=motion_control로 지정하고, 참조 영상과 인물 이미지를 FileInfos로 함께 지정합니다. 버전은 3.0(신버전) 또는 2.6(표준 입구)을 사용합니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "2.6",
  "SceneType": "motion_control",
  "Prompt": "참조 영상의 동작으로 새 영상 생성",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Video",
      "Url": "https://<cdn>/ref_motion.mp4"
    },
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://<cdn>/person.webp"
    }
  ],
  "ExtInfo": "{\"AdditionalParameters\":\"{\\\"keep_original_sound\\\":\\\"no\\\",\\\"character_orientation\\\":\\\"video\\\"}\"}",
  "OutputConfig": {
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

ExtInfo 주요 파라미터

keep_original_sound: yes(원본 소리 유지)/no. character_orientation: image(이미지 인물 방향, 참조 영상 ≤10초)/video(영상 인물 방향, 참조 영상 ≤30초).

립싱크 (lip_sync)

인물이 말하는 소스에 오디오를 맞춰 입 모양을 동기화합니다. 먼저 DescribeAigcFaceInfo로 SessionId와 얼굴 정보를 얻은 뒤, SceneType=lip_sync로 호출합니다. 오디오와 영상 정보는 모두 ExtInfo로 전달하고 FileInfos는 비웁니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "2.6",
  "SceneType": "lip_sync",
  "Prompt": "lip sync",
  "ExtInfo": "{\"AdditionalParameters\":\"{\\\"session_id\\\":\\\"845736590818832460\\\",\\\"face_choose\\\":[{\\\"face_id\\\":0,\\\"sound_file\\\":\\\"https://<cdn>/audio.mp3\\\",\\\"sound_start_time\\\":0,\\\"sound_end_time\\\":5000,\\\"sound_insert_time\\\":0,\\\"sound_volume\\\":2,\\\"original_audio_volume\\\":0}]}\"}",
  "OutputConfig": {
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

두 단계 흐름

1단계: DescribeAigcFaceInfo로 session_id와 face_id를 얻습니다. 2단계: lip_sync 호출 시 FileInfos는 비우고, face_choose 배열에 face_id / sound_file, 구간(ms), 볼륨을 지정합니다.

디지털 휴먼 (avatar_i2v)

인물 이미지 1장과 오디오로 말하거나 움직이는 인물 영상을 만듭니다. SceneType=avatar_i2v로 지정하고 인물 이미지를 FileInfos로, 오디오는 ExtInfo의 sound_file로 지정합니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "2.6",
  "SceneType": "avatar_i2v",
  "Prompt": "talking naturally",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://<cdn>/portrait.png"
    }
  ],
  "ExtInfo": "{\"AdditionalParameters\":\"{\\\"sound_file\\\":\\\"https://<cdn>/audio.mp3\\\"}\"}",
  "OutputConfig": {
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

오디오 입력 규칙

sound_file(mp3/wav/m4a/aac, 최대 5MB, 2~300초) 또는 audio_id 중 하나를 입력합니다.

이미지 / 영상 참조 (image_list / video_list)

프롬프트 안에서 <<<...>>> 표기로 참조 목록의 항목을 지목할 수 있습니다. 이미지 목록과 영상 목록은 FileInfos로 전달하고, Category로 종류를 구분합니다. 순서는 FileInfos 배열의 순서를 따릅니다.

표기 대상
<<<image_1>>> / <<<image_2>>> ... Category=Image 항목
<<<video_1>>> / <<<video_2>>> ... Category=Video 항목
<<<element_1>>> / <<<element_2>>> ... SubjectInfos 또는 element_list로 전달한 참조 대상
LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "3.0-Omni",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://<cos>/f0.jpeg",
      "Usage": "Reference"
    },
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://<cos>/f1.jpeg",
      "Usage": "Reference"
    },
    {
      "Type": "Url",
      "Category": "Video",
      "Url": "https://<cos>/1.mp4",
      "Usage": "Reference"
    }
  ],
  "Prompt": "let <<<image_1>>> hold hands with <<<image_2>>> in the environment of <<<video_1>>>",
  "OutputConfig": {
    "Duration": 8,
    "Resolution": "1080P",
    "AspectRatio": "16:9",
    "AudioGeneration": "Disabled",
    "StorageMode": "Temporary"
  },
  "SessionContext": "job-001"
}

ReferenceType: 참조 영상의 성격

Category=Video일 때 ReferenceType으로 용도를 지정합니다. GV, Kling, PixVerse에 적용됩니다.

값 의미
feature 특징 참조. 영상의 스타일이나 움직임 특징만 참조
base 편집 대상. 이 영상 자체를 수정

참조 개수 제한

조건 제한
참조 영상 있음 참조 이미지 수 + 참조 대상 수 합산 4 이하
참조 영상 — 참조 이미지 수 + 참조 대상 수 합산 7 이하
끝 프레임 사용 참조 이미지 최대 2장

등록한 참조 대상 (SubjectInfos)

같은 인물이나 사물을 여러 태스크에서 재사용할 때 사용합니다. 참조 대상를 미리 만들어 두면 ID가 발급되고, 생성 요청에서 그 ID를 참조합니다. Kling은 등록한 참조 대상만 지원합니다.

참조 대상 생성 API

API 설명
CreateAigcAdvancedCustomElement 권장. 비동기. 이미지와 영상 모두 지원. 응답으로 TaskId를 주고 DescribeTaskDetail로 조회
CreateAigcCustomElement 구버전. 동기. 이미지 전용. 하위 호환용으로만 유지
DescribeAigcAdvancedCustomElements 생성한 참조 대상 목록 조회
DeleteAigcAdvancedCustomElement 참조 대상 삭제

해외 참조 대상 라이브러리를 이미 개통한 경우 CreateAigcAdvancedCustomElement에 DisableModeration=True를 넘기면 해외 참조 대상 라이브러리를 사용합니다.

캐릭터 등록

SubjectInfos.N[].Id에 참조 대상 ID를 넣고, 프롬프트에서 <<<element_N>>>으로 지목합니다. Name은 선택이며 붙여도 프롬프트 참조 표기는 동일합니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "3.0-Omni",
  "SubjectInfos": [
    {
      "Id": "858477278396170315"
    },
    {
      "Id": "858477602846711835"
    }
  ],
  "Prompt": "let <<<element_1>>> hold hands with <<<element_2>>> and spin around",
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Resolution": "1080P"
  },
  "SessionContext": "job-001"
}

등록한 참조 대상 (구버전, ExtInfo)

ExtInfo의 element_list로도 같은 동작을 시킬 수 있지만 새 구현에는 SubjectInfos를 권장합니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "3.0-Omni",
  "Prompt": "let <<<element_1>>> hold hands with <<<element_2>>> and spin around",
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Resolution": "1080P"
  },
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"element_list\\\": [{\\\"element_id\\\": 858477278396170315}, {\\\"element_id\\\": 858477602846711835}]}\"}",
  "SessionContext": "job-001"
}

스마트 샷 (multi_shot)

Kling 3.0 계열은 프롬프트 한 문장으로 여러 컷을 자동 구성하거나, 컷별 스크립트를 직접 지정할 수 있습니다. ExtInfo의 AdditionalParameters로 전달합니다.

필드 타입 기본값 설명
multi_shot Bool false true이면 다중 컷 모드. 이때 최상위 Prompt는 무시됩니다
shot_type String 빈 값 customize(직접 지정) / intelligence(자동). multi_shot=true이면 필수
multi_prompt Array 빈 값 컷별 정보. 최대 6개, 최소 1개

multi_prompt 항목 구성:

필드 설명
index 컷 번호
prompt 컷 스크립트. 최대 512자
duration 컷 길이(초). 1 이상, 전체 길이 이하

컷 길이 합계는 전체 길이와 같아야 합니다

각 컷의 duration 합계를 OutputConfig.Duration과 동일하게 지정합니다.

customize: 컷 직접 지정

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "3.0",
  "Prompt": "not used when multi_shot is on",
  "OutputConfig": {
    "StorageMode": "Temporary",
    "Resolution": "1080P",
    "Duration": 5,
    "AspectRatio": "16:9",
    "AudioGeneration": "Enabled"
  },
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"multi_shot\\\": true, \\\"shot_type\\\": \\\"customize\\\", \\\"multi_prompt\\\": [{\\\"index\\\": 1, \\\"prompt\\\": \\\"A person sitting on a park bench, sunlight filtering through trees\\\", \\\"duration\\\": 2}, {\\\"index\\\": 2, \\\"prompt\\\": \\\"A car speeding down a rainy street, headlights glowing. Dynamic angle, focus on motion.\\\", \\\"duration\\\": 3}]}\"}",
  "SessionContext": "job-001"
}

Python으로 ExtInfo를 만드는 예시입니다.

LANGUAGE
import json
kl_ext_info = {
    "multi_shot": True,
    "shot_type": "customize",
    "multi_prompt": [
        {"index": 1, "prompt": "A person sitting on a park bench, sunlight filtering through trees", "duration": 2},
        {"index": 2, "prompt": "A car speeding down a rainy street, headlights glowing. Dynamic angle, focus on motion.", "duration": 3},
    ],
}
inner = json.dumps(kl_ext_info, ensure_ascii=False)
ext_info = json.dumps({"AdditionalParameters": inner}, ensure_ascii=False)

intelligence: 자동 분할

shot_type=intelligence이면 multi_prompt는 무시되고 Prompt를 기준으로 모델이 컷을 구성합니다.

커스텀 음색 (voice_id)

음성을 포함해 생성할 때 목소리를 지정합니다. 지원 버전은 2.6 / 3.0 / 3.0-Omni이며 2.6은 1080P에서만 음색 ID 지정이 가능합니다.

음색은 별도 API로 미리 생성하고, ExtInfo의 voice_list로 전달한 뒤 프롬프트에서 <<<voice_N>>>으로 지목합니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "2.6",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Image",
      "Url": "https://<cos>/portrait.png",
      "Usage": "FirstFrame"
    }
  ],
  "Prompt": "the person in the image says loudly with <<<voice_1>>>: I want to be free",
  "OutputConfig": {
    "StorageMode": "Permanent",
    "Duration": 5,
    "Resolution": "1080P",
    "AspectRatio": "9:16",
    "AudioGeneration": "Enabled"
  },
  "ExtInfo": "{\"AdditionalParameters\": \"{\\\"voice_list\\\": [{\\\"voice_id\\\": 869048851066937391}]}\"}",
  "SessionContext": "job-001"
}

영상 편집 (base 영상)

이미 생성된 영상을 편집 대상으로 삼고, 프롬프트로 내용을 바꿉니다. Category=Video에 ReferenceType=base를 지정합니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "3.0-Omni",
  "FileInfos": [
    {
      "Type": "Url",
      "Category": "Video",
      "Url": "https://<cos>/source.mp4",
      "ReferenceType": "base"
    }
  ],
  "Prompt": "change the color of the main character's dress to white",
  "OutputConfig": {
    "StorageMode": "Permanent",
    "MediaName": "kling-video-edit"
  },
  "SessionContext": "job-001"
}

feature와 base의 차이

feature는 참조 영상의 특징만 가져오고 새 영상을 만듭니다. base는 그 영상 자체를 편집합니다. 편집 목적이면 반드시 base를 지정해야 합니다.

다중 요소 편집 (multi_elements)

영상 속 특정 요소(피사체)를 선택해 삭제하거나 재생성하는 Kling 편집 기능입니다. 선택 영역을 만드는 두 개의 세션 API로 SessionId를 준비한 뒤, CreateAigcVideoTask에 SceneType=multi_elements로 최종 생성 태스크를 제출하는 3단계 흐름입니다.

1단계 InitializeAigcMultiElementsSelection 입력 영상을 업로드하고 해석해 SessionId 발급 2단계 EditAigcMultiElementsSelection 선택 영역 편집(add / delete / clear / preview). 만족할 때까지 반복 3단계 CreateAigcVideoTask SceneType=multi_elements로 최종 영상 생성

입력 영상 제약

입력 영상은 길이 10초 이하, 가로와 세로 각각 720px 이상이어야 합니다. 발급된 SessionId는 24시간 유효합니다.

1단계 선택 세션 초기화 (InitializeAigcMultiElementsSelection)

편집할 영상을 업로드하고 해석해 SessionId를 발급합니다.

파라미터 필수 타입 설명
SubAppId 필수 Integer VOD 애플리케이션 ID
FileInfo 선택 Object 영상 소스
FileInfo.Type 필수 String File 또는 Url
FileInfo.FileId 선택 String Type=File일 때 필수. VOD 파일 ID
FileInfo.Url 선택 String Type=Url일 때 필수. 접근 가능한 영상 URL
LANGUAGE
{
  "SubAppId": 123456789,
  "FileInfo": {
    "Type": "Url",
    "Url": "https://<cdn>/input.mp4"
  }
}

응답 필드:

필드 설명
SessionId 세션 ID. 24시간 유효하며 이후 호출에서 사용
Status 인식 코드. 0이면 성공
Fps 영상 프레임레이트
OriginalDuration 영상 길이(초)
Width / Height 영상 가로 / 세로
TotalFrame 총 프레임 수
NormalizedVideo 정규화된 영상 URL
LANGUAGE
{
  "Response": {
    "SessionId": "<session-id>",
    "Status": 0,
    "Fps": 30.0,
    "OriginalDuration": 5.0,
    "Width": 720,
    "Height": 1280,
    "TotalFrame": 150,
    "NormalizedVideo": "https://<cdn>/normalized.mp4",
    "RequestId": "<request-id>"
  }
}

2단계 선택 영역 편집 (EditAigcMultiElementsSelection)

하나의 API가 SelectionAction으로 네 가지 동작을 구분합니다. add(선택점 추가) / delete(선택점 삭제) / clear(전체 초기화) / preview(마스크 미리보기). 선택이 만족스러울 때까지 반복 호출합니다.

파라미터 필수 타입 설명
SubAppId 필수 Integer VOD 애플리케이션 ID
SelectionAction 필수 String add / delete / clear / preview
SessionId 필수 String 1단계에서 받은 세션 ID
FrameIndex 선택 Integer add/delete 시 필수. 대상 프레임 번호
Points 선택 Array add/delete 시 필수. 정규화 좌표. Point.X / Point.Y는 0~1 범위
LANGUAGE
{
  "SubAppId": 123456789,
  "SelectionAction": "add",
  "SessionId": "<session-id>",
  "FrameIndex": 0,
  "Points": [
    {
      "X": 0.773,
      "Y": 0.297
    }
  ]
}

응답 필드:

필드 출현 설명
Status 공통 인식 코드. 0이면 성공
Result.FrameIndex add / delete 조작 프레임 번호
Result.RleMaskList[].ObjectId add / delete 선택된 객체 ID
Result.RleMaskList[].RleMask add / delete 선택 마스크 RLE(Counts)와 크기(Size)
Result.RleMaskList[].PngMask.Url add / delete PNG 마스크 URL
Result.Video / VideoCover preview 마스크가 표시된 미리보기 영상 / 커버 URL
Result.TrackingOutput preview 프레임별 마스크 추적 결과 URL

동작별 응답

delete의 응답 구조는 add와 동일합니다. clear는 Result 없이 Status만 반환합니다.

3단계 최종 생성 (CreateAigcVideoTask, SceneType=multi_elements)

SceneType=multi_elements로 다중 요소 편집 씬을 트리거합니다. ExtInfo의 AdditionalParameters에 앞서 만든 session_id와 edit_mode를 담고, Prompt에서 편집 대상을 <<<video_1>>>로 참조합니다.

LANGUAGE
{
  "SubAppId": 123456789,
  "ModelName": "Kling",
  "ModelVersion": "1.6",
  "FileInfos": [
    {
      "Type": "Url",
      "Url": "https://<cdn>/ref.jpeg",
      "Usage": "Reference"
    }
  ],
  "Prompt": "<<<video_1>>>에서 특정 피사체 재생성",
  "OutputConfig": {
    "Duration": 10,
    "StorageMode": "Temporary"
  },
  "SceneType": "multi_elements",
  "ExtInfo": "{\"AdditionalParameters\":\"{\\\"session_id\\\":\\\"<session-id>\\\",\\\"edit_mode\\\":\\\"addition\\\"}\"}",
  "SessionContext": "job-001"
}
LANGUAGE
{
  "Response": {
    "TaskId": "<task-id>",
    "RequestId": "<request-id>"
  }
}

반환된 TaskId는 아래 태스크 접수 응답 절차대로 DescribeTaskDetail로 폴링합니다.

Contact us about WAND