Kling

Endpoint: POST https://mps.intl.tencentcloudapi.comAction: CreateAigcVideoTask

기본 정보

항목	값
ModelName	`Kling`
ModelVersion	`3.0-Omni` / `3.0` / `O1` / `2.6` / `2.5` / `2.1` / `2.0` / `1.6`
가드레일 해제 지원	지원

MPS AIGC에서 기능이 가장 넓은 영상 엔진입니다. text-to-video, image-to-video(첫/끝 프레임), 참조 생성 외에 동작 제어, 립싱크, 디지털 휴먼, 멀티샷, 커스텀 참조 대상, 커스텀 음색을 모두 SceneType과 AdditionalParameters로 처리합니다.

요청 파라미터

파라미터	필수	타입	설명
`ModelName`	필수	String	고정값 `Kling`
`ModelVersion`	선택	String	`3.0-Omni` / `3.0` / `O1` / `2.6` / `2.5` / `2.1` / `2.0` / `1.6`
`Prompt`	필수	String	생성 프롬프트. 텍스트 입력 모드는 최대 `2000`자로 작성
`NegativePrompt`	선택	String	결과에서 제외할 요소. 지원 모델에서 적용
`EnhancePrompt`	선택	Boolean	프롬프트 자동 보정. 기본값 `false`
`ImageUrl`	선택	String	첫 프레임 이미지 URL. 외부 접근 가능해야 하고 `10MB` 이하
`LastImageUrl`	선택	String	끝 프레임 이미지 URL. `ImageUrl`과 함께 사용
`ImageInfos.N`	선택	Array	참조 이미지 배열. `Category` / `Url` / `ReferenceType` 등
`Duration`	선택	Integer	생성 길이(초). 모델별 허용값만 반영
`ExtraParameters`	선택	Object	`Resolution` / `AspectRatio` / `EnableAudio`
`AdditionalParameters`	선택	String	모델 전용 옵션을 담은 JSON 문자열. `seed` 전달 형식은 추가 설정 참조
`SceneType`	선택	String	`motion_control`(동작 제어), `lip_sync`(립싱크), `avatar_i2v`(디지털 휴먼), `multi_elements`(다중 요소 편집)
`ExtraParameters.` `EnablelnputComplianceCheck`	선택	Boolean	`false`를 명시적으로 전달하면 입력 심사 해제. 사용 전 영업담당자 문의
`ExtraParameters.` `EnableOutputComplianceCheck`	선택	Boolean	`false`를 명시적으로 전달하면 출력 심사 해제. 사용 전 영업담당자 문의

요청 예시

text-to-video

텍스트 생성은 Prompt를 입력하고, ExtraParameters로 해상도 / 비율 / 오디오 동시 생성을 지정합니다.

json

{
  "ModelName": "Kling",
  "ModelVersion": "3.0",
  "Prompt": "a cat walking on the beach at sunset",
  "Duration": 5,
  "ExtraParameters": {
    "Resolution": "1080P",
    "AspectRatio": "16:9",
    "EnableAudio": true
  },
  "Operator": "admin",
  "StoreCosParam": {
    "CosBucketName": "<bucket-appid>",
    "CosBucketRegion": "<bucket-region>",
    "CosBucketPath": "/aigc/"
  },
  "EnhancePrompt": false
}

응답 예시

json

{
  "Response": {
    "Status": "DONE",
    "Message": "ok",
    "Resolution": "1920x1080",
    "VideoUrls": [
      "https://aigc-output-video-<id>.cos.<region>.myqcloud.com/<file>.mp4?q-sign-algorithm=sha1&..."
    ],
    "RequestId": "<request-id>"
  }
}

특수 설정

가드레일 해제

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

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

파라미터	해제 값	적용 대상
`ExtraParameters.EnablelnputComplianceCheck`	`false`	입력 심사 해제
`ExtraParameters.EnableOutputComplianceCheck`	`false`	출력 심사 해제

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

json

{
  "ExtraParameters": {
    "EnablelnputComplianceCheck": false,
    "EnableOutputComplianceCheck": false
  }
}

버전별 지원 능력

버전	생성 모드	최대 참조 이미지	오디오	길이
`3.0-Omni`	text / image / 참조 생성	`8장`	원본 사운드, 더빙, 효과음	`3~15초`
`3.0`	text / image	`6장`	지원	`3~15초`
`O1`	text / image / 참조 생성	`4장`	지원	`3~10초`
`2.6`	text / image	`4장`	참조 생성 + pro 모드(`1080P`)에서 지원	`5초`, `10초`
`2.1` / `2.0` / `1.6`	text, 기본 image	—	단순 배경음만	`5초`, `10초`

image-to-video (첫 / 끝 프레임)

ImageUrl로 첫 프레임을 지정하면 image-to-video입니다. LastImageUrl을 함께 넣으면 두 프레임 사이를 이어 붙입니다. 첫 프레임만 넣으면 출력 비율은 그 이미지 비율을 따릅니다. 끝 프레임은 2.0 / O1 / 3.0 / 3.0-Omni에서 지원합니다.

json

{
  "ModelName": "Kling",
  "ModelVersion": "3.0",
  "Prompt": "smooth transition between two scenes",
  "ImageUrl": "https://<cdn>/first.png",
  "LastImageUrl": "https://<cdn>/last.png",
  "Duration": 10,
  "Operator": "admin",
  "StoreCosParam": {
    "CosBucketName": "<bucket-appid>",
    "CosBucketRegion": "<bucket-region>",
    "CosBucketPath": "/aigc/"
  },
  "EnhancePrompt": false
}

참조 생성 (멀티 이미지)

ImageInfos.N에 참조 이미지를 여러 장 넣고, Prompt에서 <<<image_1>>> / <<<image_2>>> 형태로 각 이미지를 지목합니다. O1과 3.0-Omni는 1~7장, 1.6은 1~4장까지 받습니다.

json

{
  "ModelName": "Kling",
  "ModelVersion": "3.0-Omni",
  "Prompt": "<<<image_1>>> and <<<image_2>>> in the same scene",
  "ImageInfos": [
    {
      "Category": "Image",
      "Url": "https://<cdn>/ref1.png"
    },
    {
      "Category": "Image",
      "Url": "https://<cdn>/ref2.png"
    }
  ],
  "Duration": 10,
  "Operator": "admin",
  "StoreCosParam": {
    "CosBucketName": "<bucket-appid>",
    "CosBucketRegion": "<bucket-region>",
    "CosBucketPath": "/aigc/"
  },
  "EnhancePrompt": false
}

동작 제어 (motion_control)

참조 이미지의 인물이 지정한 자세와 동작을 따라가도록 생성합니다. SceneType=motion_control을 지정하고, 동작 제어 세부 옵션은 AdditionalParameters에 JSON 문자열로 지정합니다. keep_original_sound / character_orientation 등을 지원합니다. 최신 동작 제어는 ModelVersion=3.0, 표준 경로는 2.6을 사용합니다.

json

{
  "ModelName": "Kling",
  "ModelVersion": "3.0-Omni",
  "SceneType": "motion_control",
  "Prompt": "a person waves hand and turns around",
  "ImageUrl": "https://<cdn>/first-frame.png",
  "Duration": 5,
  "ExtraParameters": {
    "Resolution": "1080P",
    "AspectRatio": "16:9"
  },
  "AdditionalParameters": "{\"keep_original_sound\":\"yes\"}",
  "Operator": "admin",
  "StoreCosParam": {
    "CosBucketName": "<bucket-appid>",
    "CosBucketRegion": "<bucket-region>",
    "CosBucketPath": "/aigc/"
  },
  "EnhancePrompt": false
}

립싱크 (lip_sync)

두 단계로 진행합니다. 먼저 얼굴 정보 조회 API로 session_id와 face_id를 받고, 그 값을 AdditionalParameters에 넣어 생성 태스크를 만듭니다. 짧고 단순한 영상은 동기 API DescribeAigcFaceInfo, 길고 복잡한 영상은 비동기 API DescribeAigcFaceInfoAsync를 사용합니다. 버전은 무관하며 아무 값이나 넣어도 동작합니다.

bash

curl -X POST https://mps.tencentcloudapi.com \
  -H "X-TC-Action: DescribeAigcFaceInfo" \
  -H "Content-Type: application/json" \
  -H "X-TC-Version: 2019-06-12" \
  -H "X-TC-Region: ap-guangzhou" \
  -H "Authorization: TC3-HMAC-SHA256 Credential=<SecretId>/<Date>/mps/tc3_request, SignedHeaders=content-type;host, Signature=<Signature>" \
  -d '{
  "ImageUrl": "https://<cdn>/portrait.png",
  "ModelName": "Kling",
  "ModelVersion": "3.0"
}'

bash

curl -X POST https://mps.tencentcloudapi.com \
  -H "X-TC-Action: CreateAigcVideoTask" \
  -H "Content-Type: application/json" \
  -H "X-TC-Version: 2019-06-12" \
  -H "X-TC-Region: ap-guangzhou" \
  -H "Authorization: TC3-HMAC-SHA256 Credential=<SecretId>/<Date>/mps/tc3_request, SignedHeaders=content-type;host, Signature=<Signature>" \
  -d '{
  "ModelName": "Kling",
  "ModelVersion": "3.0",
  "SceneType": "lip_sync",
  "ImageUrl": "https://<cdn>/portrait.png",
  "AdditionalParameters": "{\"session_id\":\"<session-id>\",\"face_choose\":\"<face-id>\"}",
  "Operator": "admin"
}'

디지털 휴먼 (avatar_i2v)

인물 이미지와 음성 파일로 말하는 영상을 만듭니다. SceneType=avatar_i2v를 지정하고 이미지는 ImageInfos.N의 Category=Image로, 음성은 AdditionalParameters의 sound_file로 전달합니다. 음성은 mp3, wav, m4a, aac를 지원하고 5MB 이하, 2~300초 범위입니다. 버전은 무관합니다.

json

{
  "ModelName": "Kling",
  "ModelVersion": "3.0",
  "SceneType": "avatar_i2v",
  "Prompt": "a digital human talking",
  "ImageInfos": [
    {
      "Category": "Image",
      "Url": "https://<cdn>/avatar.png"
    }
  ],
  "AdditionalParameters": "{\"sound_file\":\"https://<cdn>/voice.mp3\"}",
  "Duration": 5,
  "Operator": "admin",
  "StoreCosParam": {
    "CosBucketName": "<bucket-appid>",
    "CosBucketRegion": "<bucket-region>",
    "CosBucketPath": "/aigc/"
  },
  "EnhancePrompt": false
}

멀티샷 (스토리보드)

3.0 계열에서 한 태스크로 여러 컷을 생성합니다. AdditionalParameters에 multi_shot / shot_type / multi_prompt를 지정합니다.

json

{
  "ModelName": "Kling",
  "ModelVersion": "3.0",
  "Prompt": "a short cinematic sequence in three shots",
  "Duration": 15,
  "AdditionalParameters": "{\"multi_shot\":\"true\"}",
  "Operator": "admin",
  "StoreCosParam": {
    "CosBucketName": "<bucket-appid>",
    "CosBucketRegion": "<bucket-region>",
    "CosBucketPath": "/aigc/"
  },
  "EnhancePrompt": false
}

커스텀 음색 (voice_id)

커스텀 음색 생성 API로 음색을 만들고, 생성 요청의 AdditionalParameters에서 voice_list로 voice_id를 지정합니다. 2.6 / 3.0 / 3.0-Omni에서 지원하며 2.6은 1080P에서만 음색 지정이 반영됩니다.

json

{
  "ModelName": "Kling",
  "ModelVersion": "3.0",
  "Prompt": "a narrator introduces the product",
  "Duration": 10,
  "ExtraParameters": {
    "Resolution": "1080P",
    "EnableAudio": true
  },
  "AdditionalParameters": "{\"voice_list\":[{\"voice_id\":\"<voice-id>\"}]}",
  "Operator": "admin",
  "StoreCosParam": {
    "CosBucketName": "<bucket-appid>",
    "CosBucketRegion": "<bucket-region>",
    "CosBucketPath": "/aigc/"
  },
  "EnhancePrompt": false
}

다중 요소 편집 (multi_elements)

MPS CreateAigcVideoTask도 SceneType=multi_elements를 지원합니다. AdditionalParameters에 session_id와 edit_mode를 담아 전달합니다.

선택 세션은 VOD 전용

선택 영역을 만드는 InitializeAigcMultiElementsSelection / EditAigcMultiElementsSelection 세션 API는 VOD 전용입니다. 따라서 선택 세션은 VOD 경로에서 먼저 생성하고, 발급된 session_id를 MPS 생성 요청에 사용합니다. 전체 3단계 흐름과 세션 API의 파라미터는 VOD Kling 문서의 다중 요소 편집 절을 참고하십시오.

json

{
  "ModelName": "Kling",
  "ModelVersion": "1.6",
  "SceneType": "multi_elements",
  "Prompt": "<<<video_1>>>에서 특정 피사체 재생성",
  "Duration": 10,
  "AdditionalParameters": "{\"session_id\":\"<session-id>\",\"edit_mode\":\"addition\"}",
  "Operator": "admin",
  "StoreCosParam": {
    "CosBucketName": "<bucket-appid>",
    "CosBucketRegion": "<bucket-region>",
    "CosBucketPath": "/aigc/"
  },
  "EnhancePrompt": false
}

추가 옵션

커스텀 참조 대상

Kling 커스텀 참조 대상는 별도 API로 생성, 조회, 삭제합니다. CreateKlingCustomElement / CreateAigcCustomElement / DescribeKlingCustomElement / DeleteAigcAdvancedCustomElement를 사용하고 국내 참조 대상 라이브러리와 해외 참조 대상 라이브러리를 구분해서 관리합니다.

Kling ​

기본 정보 ​

요청 파라미터 ​

요청 예시 ​

text-to-video ​

응답 예시 ​

특수 설정 ​

가드레일 해제 ​

버전별 지원 능력 ​

image-to-video (첫 / 끝 프레임) ​

참조 생성 (멀티 이미지) ​

동작 제어 (motion_control) ​

립싱크 (lip_sync) ​

디지털 휴먼 (avatar_i2v) ​

멀티샷 (스토리보드) ​

커스텀 음색 (voice_id) ​

다중 요소 편집 (multi_elements) ​

추가 옵션 ​

Kling

기본 정보

요청 파라미터

요청 예시

text-to-video

응답 예시

특수 설정

가드레일 해제

버전별 지원 능력

image-to-video (첫 / 끝 프레임)

참조 생성 (멀티 이미지)

동작 제어 (motion_control)

립싱크 (lip_sync)

디지털 휴먼 (avatar_i2v)

멀티샷 (스토리보드)

커스텀 음색 (voice_id)

다중 요소 편집 (multi_elements)

추가 옵션