Kling

Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-video인증: Tokenhub API Key / Bearer

Kling은 텍스트와 이미지 기반 영상 생성, Omni 멀티모달 생성 및 편집을 지원합니다. 참조 캐릭터와 음성 관리 API를 함께 제공합니다.

기본 정보

항목	값
호출 경로	Tokenhub API
가드레일 해제 지원	미지원

버전별 지원 규격

버전	해상도	비율	길이
kling-video-v3	720p / 1080p / 4k	16:9 / 9:16 / 1:1	3 ~ 15초
kling-video-v3-omni	720p / 1080p / 4k	16:9 / 9:16 / 1:1	3 ~ 15초
kling-video-v3-turbo	720p / 1080p	16:9 / 9:16 / 1:1	3 ~ 15초

입력 모드

버전	입력
kling-video-v3	텍스트-영상/이미지-영상(시작-종료 프레임 및 요소 포함)
kling-video-v3-omni	Omni 영상 생성(텍스트/이미지/영상의 멀티모달 입력 및 영상 편집)
kling-video-v3-turbo	텍스트-영상/이미지-영상

호출 절차

영상 생성은 시간이 오래 걸리는 작업이므로 API는 비동기 호출 방식을 사용하며, 다음 두 단계로 나뉩니다.

1. 작업 제출: 생성 API(텍스트-영상/이미지-영상/Omni)를 호출합니다. 성공하면 data.id(작업 ID)가 반환됩니다.
2. 결과 폴링: data.status = succeeded가 될 때까지 작업 ID로 작업 결과 조회 API를 호출하고, 결과에서 영상 URL을 가져옵니다.

텍스트 기반 영상 생성

API 설명

텍스트 프롬프트만 사용하여 영상을 생성합니다. V3는 멀티샷 템플릿 구문(자세한 내용은 "부록: 멀티샷 프롬프트 구문" 참조), 네이티브 오디오 및 4K 출력을 지원합니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-video

요청 파라미터

파라미터	필수	타입	설명
model	필수	string	모델 버전. 값 범위: kling-video-v3, kling-video-v3-turbo
prompt	필수	string	긍정 및 부정 설명을 포함할 수 있는 프롬프트입니다. V3: ≤ 3072자(≤ 2500 권장), 멀티샷 템플릿 구문 지원. V3 Turbo: ≤ 2500자.
settings	선택	object	출력 구성입니다. 하위 필드는 아래 표를 참조합니다(지원 필드는 모델에 따라 다름).
options	선택	object	일반 구성입니다. 하위 필드는 아래 표를 참조합니다.

settings 하위 필드(모델별):

하위 필드	적용 모델	설명
resolution	전체	해상도. V3: 720p / 1080p / 4k, V3 Turbo: 720p / 1080p. 기본값: 720p.
aspect_ratio	전체	비율. 옵션: 16:9 / 9:16 / 1:1. 기본값: 16:9.
duration	전체	길이(초). 3~15의 정수. 기본값: 5.
multi_shot	V3만 해당	멀티샷 영상 생성 여부. 기본값: true. false로 설정하면 멀티샷 프롬프트가 멀티샷 출력을 생성하지 않습니다.
audio	V3만 해당	오디오. 옵션: native(영상에 맞는 네이티브 오디오 생성) / off(기본값).

참고: kling-video-v3-turbo의 settings는 resolution / aspect_ratio / duration의 세 필드만 지원합니다. multi_shot 및 audio는 지원하지 않습니다.

options 하위 필드:

하위 필드	필수	설명
external_task_id	선택	계정 내에서 고유한 사용자 지정 작업 ID이며, 이 ID로 작업을 조회할 수 있습니다.
watermark_info	선택	워터마크 구성. 구조: {"enabled": true/false}. true이면 워터마크를 활성화합니다.

요청 예시

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "kling-video-v3",
  "prompt": "A girl sat on the train, looking out the window, sunlight streaming across her face",
  "settings": {
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "audio": "native"
  }
}'

참고: 해당 모델을 호출하려면 예시의 model을 kling-video-v3-turbo로 바꾸십시오. V3 Turbo는 audio / multi_shot 필드를 지원하지 않습니다.

응답 파라미터

필드	타입	설명
code	int	비즈니스 오류 코드. 0은 성공을 나타내며, 그 외 값은 부록: 통합 오류 코드를 참조합니다.
message	string	오류 또는 안내 정보. 성공 시 "SUCCEED"입니다.
request_id	string	시스템이 생성한 요청 ID로, 문제 추적 및 해결에 사용됩니다.
data	object	작업 데이터 객체입니다.
data.id	string	시스템이 생성한 작업 ID로, 후속 작업 조회에 사용됩니다.
data.status	string	작업 상태. 제출 성공 시 submitted로 고정되며, 이후 상태는 조회 API를 통해 가져옵니다.
data.message	string	작업 상태 정보. 작업 실패 시 실패 사유를 표시합니다.
data.create_time	long	작업 생성 시간. 밀리초 단위 Unix 타임스탬프입니다.
data.update_time	long	작업 업데이트 시간. 밀리초 단위 Unix 타임스탬프입니다.

응답 예시

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "message": "",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}

오류 코드

요청이 실패하면 code는 0이 아닙니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다. 작업이 성공적으로 제출된 후 생성 단계의 작업 상태는 "작업 결과 조회" API를 통해 가져올 수 있습니다.

status	설명	처리 권장 사항
processing	처리 중(대기열 포함)	상태 조회를 계속합니다.
succeeded	생성 성공	결과의 영상 URL을 사용합니다.
failed	생성 실패	실패 원인을 확인하고 수정한 후 재시도합니다. 실패가 지속되면 기술 지원에 문의하고 request_id를 제공합니다.

이미지-영상

API 설명

이미지를 시작 프레임으로 사용하고(V3는 선택적으로 종료 프레임 지원) 텍스트 프롬프트와 결합하여 영상을 생성합니다. V3는 요소 참조도 지원합니다. 이미지는 공개 URL 또는 Base64로 직접 전달할 수 있으며, 출력 비율은 입력 이미지를 따릅니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/image-to-video

요청 파라미터

파라미터	필수	타입	설명
model	필수	string	모델 버전. 값 범위: kling-video-v3, kling-video-v3-turbo
contents	필수	array	참조 자료 모음입니다. 같은 자료의 필드는 동일한 객체에 배치합니다. prompt와 first_frame이 각각 하나 이상 포함되어야 합니다. 하위 필드는 아래 표를 참조합니다.
settings	선택	object	출력 구성입니다. 하위 필드는 아래 표를 참조합니다. 참고: 이미지-영상에는 aspect_ratio 파라미터가 없으며, 비율은 입력 이미지에 따라 결정됩니다.
options	선택	object	일반 구성으로, 텍스트-영상과 동일합니다.

contents 배열 요소의 하위 필드:

파라미터	필수	타입	설명
type	필수	string	자료 유형. 모델별 지원 범위: V3: prompt / first_frame / last_frame / element, V3 Turbo: prompt / first_frame.
text	조건부 필수	string	텍스트 프롬프트. type=prompt일 때 필수입니다. ≤ 2500자. V3는 멀티샷 템플릿 구문과 @element 참조를 지원합니다.
url	조건부 필수	string	이미지 자산(URL 또는 Base64). type=first_frame / last_frame일 때 필수입니다. 제약 조건: .jpg/.jpeg/.png, ≤ 50 MB, 너비와 높이 모두 ≥ 300 px, 비율 1:2.5~2.5:1.
element_id	조건부 필수	string	요소 참조(JSON 정의). type=element일 때 필수이며 V3에서만 지원합니다. 최대 3개이며, 프롬프트에서 @xxx로 참조합니다.

settings 하위 필드(모델별):

하위 필드	적용 모델	설명
resolution	전체	해상도. V3: 720p / 1080p / 4k, V3 Turbo: 720p / 1080p. 기본값: 720p.
duration	전체	길이(초). 3~15의 정수. 기본값: 5.
multi_shot	V3만 해당	멀티샷 영상 생성 여부. 기본값: true.
audio	V3만 해당	오디오. 옵션: native / off(기본값: off).

참고: 시작 및 종료 프레임은 "시작 프레임만"과 "시작 프레임 + 종료 프레임"만 지원합니다. "종료 프레임만"은 지원하지 않습니다. 서로 부분 문자열 관계인 요소 이름(예: @Zhang 및 @ZhangSan)은 사용하지 마십시오.

요청 예시

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/image-to-video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "kling-video-v3",
  "contents": [
    {
      "type": "prompt",
      "text": "Make the subject in the image turn its head naturally while the camera slowly zooms in"
    },
    {
      "type": "first_frame",
      "url": "https://example.com/start.jpg"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "duration": 5
  }
}'

응답 파라미터

"텍스트-영상"의 출력 파라미터와 동일합니다.

응답 예시

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "message": "",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}

오류 코드

요청이 실패하면 code는 0이 아닙니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다. 작업 상태 설명은 "텍스트-영상"와 동일합니다.

Omni 영상 생성

API 설명

V3 Omni의 통합 멀티모달 생성 진입점입니다. 프롬프트, 참조 이미지(시작/종료 프레임, 참조 이미지), 참조 영상(특징 영상/편집할 기본 영상) 및 요소를 종합적으로 사용하여 영상을 생성하거나 편집할 수 있습니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video

요청 파라미터

파라미터	필수	타입	설명
model	필수	string	모델 버전. 값: kling-video-v3-omni
contents	필수	array	멀티모달 참조 자료 모음입니다. 같은 자료의 필드는 동일한 객체에 배치합니다. 하위 필드는 아래 표를 참조합니다.
settings	선택	object	출력 구성입니다. 하위 필드는 아래 표를 참조합니다.
options	선택	object	일반 구성으로, 텍스트-영상과 동일합니다.

contents 배열 요소의 하위 필드:

파라미터	필수	타입	설명
type	필수	string	자료 유형. 열거형 값: prompt / first_frame / last_frame / refer_image / feature_video(특징 참조 영상) / base_video(편집할 기본 영상) / element / voice(음색).
text	조건부 필수	string	텍스트 프롬프트. type=prompt일 때 필수입니다. ≤ 3072자(≤ 2500 권장). @xxx 자료 참조 및 멀티샷 구문을 지원하며, @id를 통해 음성 자료를 참조할 수 있습니다.
url	조건부 필수	string	이미지/영상 자산. 이미지는 URL 또는 Base64를 지원하며, 영상은 URL만 지원합니다. 이미지 제약 조건: jpg/jpeg/png, ≤ 50 MB, 너비와 높이 ≥ 300 px, 비율 1:2.5~2.5:1. 영상 제약 조건: mp4/mov, ≤ 200 MB, 길이 3~15.5초.
element_id	조건부 필수	string	요소 ID(요소 관리 API를 통해 생성). type=element일 때 필수입니다.
voice_id	조건부 필수	string	음성 ID. type=voice일 때 필수입니다. "음성 관리"에서 생성 후 조회하여 가져오거나 시스템 사전 설정 음성을 사용합니다.
id	조건부 필수	string	자료 인덱스 ID. type=voice일 때 필수이며 동일 작업 내에서 고유해야 합니다. 이 음성을 사용하려면 프롬프트에서 @id로 참조합니다.

settings 하위 필드:

하위 필드	필수	설명
resolution	선택	해상도. 720p / 1080p / 4k. 기본값: 720p.
aspect_ratio	조건부 필수	비율: 16:9 / 9:16 / 1:1, 기본값 16:9. 시작 프레임과 참조 영상가 모두 없으면 필수입니다.
duration	선택	길이(초). 3~15의 정수. 기본값: 5.
multi_shot	선택	멀티샷 영상 생성 여부. 기본값: true.
audio	선택	오디오. 옵션: native / original / off(기본값: off). original=참조 영상의 원본 오디오를 유지합니다.

**참고:**입력 조합 제한: 시작 및 종료 프레임은 "시작 프레임만"과 "시작 프레임 + 종료 프레임"만 지원합니다. 참조 영상은 최대 1개만 제공할 수 있습니다. feature_video는 종료 프레임을 지원하지 않으며, base_video는 시작/종료 프레임 또는 멀티샷을 지원하지 않습니다. 참조 이미지와 요소의 합계는 참조 영상가 없을 때 7개 이하, 참조 영상가 있을 때 4개 이하여야 합니다. 음성(type=voice)은 최대 2개까지 참조할 수 있습니다. 음성을 지정하면 settings.audio를 off로 설정할 수 없습니다. feature_video 사용 시 audio는 off만 가능하고 multi_shot은 true만 가능합니다. base_video 사용 시 audio는 native일 수 없으며(original 또는 off 가능), 멀티샷은 지원하지 않습니다.

요청 예시

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "kling-video-v3-omni",
  "contents": [
    {
      "type": "prompt",
      "text": "Change the color of the parrots feathers to blue, keeping the background unchanged"
    },
    {
      "type": "base_video",
      "url": "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "duration": 5,
    "audio": "original"
  }
}'

응답 파라미터

"텍스트-영상"의 출력 파라미터와 동일합니다.

응답 예시

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "message": "",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}

오류 코드

요청이 실패하면 code는 0이 아닙니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다. 작업 상태 설명은 "텍스트-영상"와 동일합니다.

요소 관리

요소 관리는 사용자 지정 참조 대상(사용자 지정 캐릭터)을 생성, 조회 및 삭제하는 데 사용됩니다. 여러 참조 이미지(image_refer) 또는 참조 영상(video_refer)를 기반으로 참조 대상을 생성할 수 있습니다. 생성 후 이미지-영상 및 Omni 영상 생성 API에서 element_id로 참조하여 사용자 지정 캐릭터를 재사용할 수 있습니다.

참조 대상 생성

API 설명

사용자 지정 참조 대상을 생성합니다. 생성은 비동기 작업입니다. 제출 후 "참조 대상 조회" API를 통해 작업 상태를 폴링하십시오. 성공하면 element_id를 가져옵니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements

요청 파라미터

파라미터	필수	타입	설명
element_name	필수	string	요소 이름, 최대 20자. 예: "my_hero".
element_description	필수	string	요소 설명, 최대 100자.
reference_type	필수	string	참조 방식. 값: image_refer(다중 이미지 참조 대상) / video_refer(영상 참조 대상).
element_image_list	조건부 필수	object	다중 이미지 참조 객체로, reference_type=image_refer일 때 필수입니다. frontal_image(정면 이미지 1개 이상) 및 refer_images[].image_url(다른 각도 또는 클로즈업 이미지 1~3개)을 포함합니다. 이미지는 공개 URL 또는 Base64로 전달할 수 있습니다. 제약 조건: jpg/jpeg/png, 10 MB 이하, 너비와 높이 모두 300 px 이상, 비율 1:2.5~2.5:1.
element_video_list	조건부 필수	object	영상 참조 객체로, reference_type=video_refer일 때 필수입니다. 구조: {"refer_videos": [{"video_url": "..."}]}. 제약 조건: MP4/MOV, 길이 3~8초, 1080P, 비율 16:9 또는 9:16, 200 MB 이하.
element_voice_id	선택	string	음성 라이브러리에 있는 기존 음성의 ID를 연결합니다. 비어 있으면 음성을 연결하지 않습니다.
tag_list	선택	array	태그 구성, 구조 [{ "tag_id": "o_101" }]. tag_id 열거형: o_101 밈 / o_102 인물 / o_103 동물 / o_104 소품 / o_105 의류 / o_106 장면 / o_107 효과 / o_108 기타.
external_task_id	선택	string	계정 내에서 고유한 사용자 지정 작업 ID입니다.

요청 예시

다중 이미지 참조 대상(image_refer):

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "element_name": "my_hero",
  "element_description": "A young man with short hair, wearing a blue jacket",
  "reference_type": "image_refer",
  "element_image_list": {
    "frontal_image": "https://example.com/front.jpg",
    "refer_images": [
      {
        "image_url": "https://example.com/side.jpg"
      }
    ]
  }
}'

영상 참조 대상(video_refer):

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "element_name": "my_hero",
  "element_description": "A young man with short hair, wearing a blue jacket",
  "reference_type": "video_refer",
  "element_video_list": {
    "refer_videos": [
      {
        "video_url": "https://example.com/demo.mp4"
      }
    ]
  }
}'

응답 파라미터

필드	타입	설명
code	int	비즈니스 오류 코드. 0은 성공을 나타냅니다.
message	string	오류 또는 안내 정보. 성공 시 "SUCCEED"입니다.
request_id	string	시스템이 생성한 요청 ID로, 문제 추적 및 해결에 사용됩니다.
data.task_id	string	시스템이 생성한 작업 ID입니다.
data.task_status	string	작업 상태: submitted / processing / succeed / failed.
data.task_info.external_task_id	string	사용자 지정 작업 ID(생성 시 제공한 경우 반환).
data.task_status_msg	string	작업 실패 시 실패 사유를 표시하며, 정상인 경우 빈 문자열입니다.
data.created_at	number	작업 생성 시간. 밀리초 단위 Unix 타임스탬프입니다.
data.updated_at	number	작업의 마지막 업데이트 시간. 밀리초 단위 Unix 타임스탬프입니다.
data.final_unit_deduction	string	작업에서 최종 차감된 포인트 값입니다.
data.final_balance_deduction.quota	string	할당량 차감의 할인 가격입니다.
data.final_balance_deduction.list_price	string	할당량 차감의 정가입니다.

응답 예시

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "02f9537c-9319-4cfb-b347-8f22cb73ffc8",
  "data": {
    "task_id": "921939922066997283",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1787836125041,
    "updated_at": 1787836125041
  }
}

오류 코드

요청이 실패하면 code는 0이 아닙니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다.

참조 대상 조회

API 설명

참조 대상 생성 작업의 상태와 결과를 조회합니다. 생성 작업을 제출하고 작업 ID를 받은 후 data.task_status = succeed가 될 때까지 이 API를 폴링하고, data.task_result.elements에서 참조 대상 정보를 가져옵니다.

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements/{id}

참고: 경로의 {id}는 작업 생성 시 반환된 data.task_id이며, 생성 시 전달한 external_task_id로 대체할 수도 있습니다.

요청 파라미터

파라미터	필수	타입	설명
task_id	필수	string	요소 생성 작업의 작업 ID로, 조회 경로의 {id}에 입력합니다. 또는 생성 시 사용한 external_task_id로 대체할 수 있습니다.

요청 예시

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

응답 파라미터

필드	타입	설명
code	int	비즈니스 오류 코드. 0은 성공을 나타냅니다.
message	string	오류 또는 안내 정보. 성공 시 "SUCCEED"입니다.
request_id	string	시스템이 생성한 요청 ID로, 문제 추적 및 해결에 사용됩니다.
data.task_id	string	시스템이 생성한 작업 ID입니다.
data.task_status	string	작업 상태: submitted / processing / succeed / failed.
data.task_info.external_task_id	string	사용자 지정 작업 ID(생성 시 제공한 경우 반환).
data.task_status_msg	string	작업 실패 시 실패 사유를 표시하며, 정상인 경우 빈 문자열입니다.
data.task_result.elements[]	array	참조 대상 목록. task_status=succeed일 때 반환됩니다.
data.task_result.elements[].element_id	number	전역적으로 고유한 참조 대상 ID입니다.
data.task_result.elements[].element_name	string	참조 대상 이름입니다.
data.task_result.elements[].element_description	string	참조 대상 설명입니다.
data.task_result.elements[].element_type	string	참조 방식: image_refer(다중 이미지 참조 대상) / video_refer(영상 참조 대상).
data.task_result.elements[].element_image_list	object	이미지 참조 정보(image_refer에서 사용 가능). frontal_image 및 refer_images[].image_url을 포함합니다.
data.task_result.elements[].element_video_list	object	영상 참조 정보(video_refer에서 사용 가능).
data.task_result.elements[].owned_by	string	참조 대상 출처. kling은 공식 참조 대상 라이브러리를 나타내며, 그 외 값은 생성자 ID를 나타냅니다.
data.task_result.elements[].status	string	참조 대상 상태: succeed(정상) / deleted.
data.created_at	number	작업 생성 시간. 밀리초 단위 Unix 타임스탬프입니다.
data.updated_at	number	작업의 마지막 업데이트 시간. 밀리초 단위 Unix 타임스탬프입니다.
data.final_unit_deduction	string	작업에서 최종 차감된 포인트 값입니다.
data.final_balance_deduction.quota	string	할당량 차감의 할인 가격입니다.
data.final_balance_deduction.list_price	string	할당량 차감의 정가입니다.

응답 예시

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "656ee178-de4f-48ea-9763-166bbaa3e4cc-query-1787836129",
  "data": {
    "task_id": "921939922066997283",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {
      "elements": [
        {
          "element_id": 319807609263140,
          "element_name": "Advanced Subject_Image Test",
          "element_description": "A young man with short hair, wearing a blue jacket",
          "element_type": "image_refer",
          "element_image_list": {
            "frontal_image": "https://example.com/front.jpg",
            "refer_images": [
              {
                "image_url": "https://example.com/side.jpg"
              }
            ]
          },
          "element_video_list": {},
          "owned_by": "826925436873121851",
          "status": "succeed"
        }
      ]
    },
    "task_status_msg": "",
    "created_at": 1787836125041,
    "updated_at": 1787836128102,
    "final_unit_deduction": "0",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}

오류 코드

요청이 실패하면 code는 0이 아닙니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다. 작업 실패 사유는 data.task_status_msg를 참조합니다.

참조 대상 삭제

API 설명

사용자 지정 참조 대상을 삭제합니다. 사용자 지정 요소만 삭제할 수 있습니다. 공식 요소(owned_by=kling)는 삭제할 수 없습니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-advanced-elements

요청 파라미터

파라미터	필수	타입	설명
element_id	필수	string	삭제할 요소의 ID입니다.

요청 예시

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-advanced-elements' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "element_id": "319807609263140"
}'

응답 파라미터

필드	타입	설명
code	int	비즈니스 오류 코드. 0은 성공을 나타냅니다.
message	string	오류 또는 안내 정보. 성공 시 "SUCCEED"입니다.
request_id	string	시스템이 생성한 요청 ID로, 문제 추적 및 해결에 사용됩니다.
data.task_id	string	시스템이 생성한 작업 ID입니다.
data.task_status	string	작업 상태: submitted / processing / succeed / failed.
data.task_status_msg	string	작업 실패 시 실패 사유를 표시하며, 정상인 경우 빈 문자열입니다.
data.created_at	number	작업 생성 시간. 밀리초 단위 Unix 타임스탬프입니다.
data.updated_at	number	작업의 마지막 업데이트 시간. 밀리초 단위 Unix 타임스탬프입니다.

응답 예시

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "dd4a503f-8afd-415d-b3e8-de4c26d4f87a",
  "data": {
    "task_id": "921939922066997283",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {},
    "task_status_msg": "",
    "created_at": 1787836125041,
    "updated_at": 1787836128102,
    "final_unit_deduction": "0",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}

오류 코드

요청이 실패하면 code는 0이 아닙니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다.

음성 관리

음성 관리는 사용자 지정 음성을 생성, 조회 및 삭제하는 데 사용됩니다. 참조 오디오(또는 오디오가 포함된 영상)를 기반으로 음성을 생성합니다. 생성 후 Omni 영상 생성(contents에서 type=voice인 자료), 디지털 휴먼(avatar), 립싱크(advanced-lip-sync) 등의 API에서 voice_id로 참조할 수 있습니다.

음성 생성은 비동기 작업이며 다음 두 단계로 나뉩니다.

1. 작업 제출: 생성 API를 호출합니다. 성공하면 data.task_id(작업 ID)가 반환됩니다.
2. 결과 폴링: data.task_status = succeed가 될 때까지 작업 ID로 음성 작업 조회 API를 호출하고, data.task_result.voices에서 voice_id를 가져옵니다.

음성 생성

API 설명

참조 오디오(또는 오디오가 포함된 영상)를 기반으로 사용자 지정 음성을 생성합니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices

요청 파라미터

파라미터	필수	타입	설명
voice_name	필수	string	음성 이름입니다.
voice_url	조건부 필수	string	참조 오디오의 공개 URL입니다. 이 파라미터와 video_id 중 하나를 선택하십시오.
video_id	조건부 필수	string	대상 오디오가 포함된 영상의 영상 ID(영상 생성 작업에서 생성된 영상)입니다. 이 파라미터와 voice_url 중 하나를 선택하십시오.
external_task_id	선택	string	계정 내에서 고유한 사용자 지정 작업 ID입니다.

요청 예시

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "voice_name": "Test voice",
  "voice_url": "https://example.com/reference.mp3"
}'

응답 파라미터

필드	타입	설명
code	int	비즈니스 오류 코드. 0은 성공을 나타냅니다.
message	string	오류 또는 안내 정보. 성공 시 "SUCCEED"입니다.
request_id	string	시스템이 생성한 요청 ID로, 문제 추적 및 해결에 사용됩니다.
data.task_id	string	시스템이 생성한 작업 ID로, 후속 작업 조회에 사용됩니다.
data.task_status	string	작업 상태: submitted / processing / succeed / failed.
data.task_info.external_task_id	string	사용자 지정 작업 ID(생성 시 제공한 경우 반환).
data.created_at	number	작업 생성 시간. 밀리초 단위 Unix 타임스탬프입니다.
data.updated_at	number	작업의 마지막 업데이트 시간. 밀리초 단위 Unix 타임스탬프입니다.

응답 예시

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a90bd11c-f272-4686-bad9-72310898a217",
  "data": {
    "task_id": "917124237444943953",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1786687976483,
    "updated_at": 1786687976483
  }
}

오류 코드

요청이 실패하면 code는 0이 아닙니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다.

음성 작업 조회

API 설명

생성 API에서 반환된 작업 ID로 음성 생성 작업을 폴링합니다. 작업이 성공하면 결과에서 voice_id와 미리보기 URL을 가져옵니다.

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices/{task_id}

참고: 경로의 {task_id}는 생성 API에서 반환된 data.task_id입니다. 생성 시 전달한 external_task_id로 대체할 수도 있습니다. 2~3초마다 폴링하는 것이 권장됩니다.

요청 파라미터

파라미터	필수	타입	설명
task_id	필수	string	작업 ID(경로 파라미터)로, 생성 API에서 반환된 data.task_id입니다.

요청 예시

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

응답 파라미터

필드	타입	설명
code	int	비즈니스 오류 코드. 0은 성공을 나타냅니다.
message	string	오류 또는 안내 정보. 성공 시 "SUCCEED"입니다.
request_id	string	요청 ID입니다.
data.task_id	string	작업 ID입니다.
data.task_status	string	작업 상태: submitted / processing / succeed / failed.
data.task_status_msg	string	작업 상태 정보. 작업 실패 시 실패 사유를 표시합니다.
data.task_info.external_task_id	string	사용자 지정 작업 ID(생성 시 제공한 경우 반환).
data.task_result.voices[]	array	음성 목록. task_status=succeed일 때 반환됩니다.
data.task_result.voices[].voice_id	string	음성 ID로, 디지털 휴먼 및 립싱크 등의 API에서 참조하는 데 사용됩니다.
data.task_result.voices[].voice_name	string	음성 이름입니다.
data.task_result.voices[].trial_url	string	음성 미리보기 오디오 URL은 임시 URL입니다. 즉시 다운로드하여 저장합니다.
data.task_result.voices[].owned_by	string	음성 소유자 식별자입니다.
data.task_result.voices[].status	string	음성 상태: succeed(정상) / deleted.
data.created_at	number	작업 생성 시간. 밀리초 단위 Unix 타임스탬프입니다.
data.updated_at	number	작업의 마지막 업데이트 시간. 밀리초 단위 Unix 타임스탬프입니다.
data.final_unit_deduction	string	이 작업에서 차감된 단위 수입니다.
data.final_balance_deduction.quota	string	할당량 차감의 할인 가격입니다.
data.final_balance_deduction.list_price	string	할당량 차감의 정가입니다.

응답 예시

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "8efcf51b-4637-4616-a21b-436501eaef96-query-1786687983",
  "data": {
    "task_id": "917124237444943953",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {
      "voices": [
        {
          "voice_id": "917124264959582304",
          "voice_name": "Test voice",
          "trial_url": "https://example.com/voice-trial.wav",
          "owned_by": "826925436873121851",
          "status": "succeed"
        }
      ]
    },
    "task_status_msg": "",
    "created_at": 1786687976483,
    "updated_at": 1786687982942,
    "final_unit_deduction": "0.05",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}

오류 코드

요청이 실패하면 code는 0이 아닙니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다. 작업 실패 사유는 data.task_status_msg를 참조합니다.

음성 삭제

API 설명

지정된 사용자 지정 음성을 삭제합니다. 사용자 지정 음성만 삭제할 수 있습니다. 삭제 후에는 생성 API에서 해당 음성을 더 이상 참조할 수 없습니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-voice

요청 파라미터

파라미터	필수	타입	설명
voice_id	필수	string	삭제할 음성 ID(조회 API에서 반환된 voice_id).

요청 예시

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-voice' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "voice_id": "917124264959582304"
}'

응답 파라미터

필드	타입	설명
code	int	비즈니스 오류 코드. 0은 성공을 나타냅니다.
message	string	오류 또는 안내 정보. 성공 시 "SUCCEED"입니다.
request_id	string	요청 ID입니다.
data.task_id	string	음성에 해당하는 생성 작업 ID입니다.
data.task_status	string	작업 상태: submitted / processing / succeed / failed.
data.task_result	object	삭제 결과 객체(일반적으로 빈 객체 {}이며 삭제 성공을 나타냄).
data.task_status_msg	string	작업 실패 시 실패 사유를 표시하며, 정상인 경우 빈 문자열입니다.
data.created_at	number	작업 생성 시간. 밀리초 단위 Unix 타임스탬프입니다.
data.updated_at	number	작업의 마지막 업데이트 시간. 밀리초 단위 Unix 타임스탬프입니다.

응답 예시

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "b641fc55-7f23-41e5-8155-2fa371c3d871",
  "data": {
    "task_id": "917124237444943953",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {},
    "task_status_msg": "",
    "created_at": 1786687976483,
    "updated_at": 1786687982942,
    "final_unit_deduction": "0.05",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}

오류 코드

요청이 실패하면 code는 0이 아닙니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다.

작업 결과 조회

API 설명

모든 생성 API(텍스트-영상/이미지-영상/통합형)가 공유하는 작업 조회 방식입니다. 작업을 제출하고 작업 ID를 반환받은 후 통합 작업 조회 엔드포인트를 통해 작업 상태를 폴링합니다. 성공하면 결과에서 영상 URL을 가져옵니다.

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/tasks/{task_id}

참고: 경로의 {task_id}는 작업 제출 시 반환된 data.id입니다. 영상 생성에는 약 몇 분이 걸리므로 3~5초마다 폴링하는 것이 권장됩니다. 응답 필드는 공식 Kling API 구조에 따라 제공되며, 실제 반환 응답이 우선합니다.

요청 파라미터

파라미터	필수	타입	설명
task_id	필수	string	작업 ID(경로 파라미터)로, 작업 제출 시 반환된 data.id입니다.

요청 예시

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/tasks/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

응답 파라미터

필드	타입	설명
code	int	비즈니스 오류 코드. 0은 성공을 나타냅니다.
message	string	오류 또는 안내 정보입니다.
request_id	string	요청 ID입니다.
data	array	작업 결과 목록입니다.
data[].id	string	작업 ID입니다.
data[].status	string	작업 상태: processing / succeeded / failed.
data[].message	string	작업 상태 정보. 작업 실패 시 실패 사유를 표시합니다.
data[].outputs	array	영상 결과 목록입니다.
data[].outputs[].type	string	생성 결과 유형. 현재 영상 결과는 video입니다.
data[].outputs[].id	string	영상 ID입니다.
data[].outputs[].url	string	영상 파일 URL은 임시 URL입니다. 즉시 다운로드하여 저장합니다.
data[].outputs[].duration	string	영상 길이(초)입니다.
data[].create_time	long	작업 생성 시간. 밀리초 단위 Unix 타임스탬프입니다.
data[].update_time	long	작업 업데이트 시간. 밀리초 단위 Unix 타임스탬프입니다.
tokenhub_usage	object	사용량입니다.
tokenhub_usage.total_tokens	integer	이 작업에서 소비한 토큰 수로, 청구/정산에 사용됩니다.

응답 예시

{
  "code": 0,
  "data": [
    {
      "update_time": 1786429168170,
      "create_time": 1786428992000,
      "id": "251435731-WandVideo-7d1997fb7ad74bfabd2814b4a9962571",
      "message": "",
      "outputs": [
        {
          "duration": "10.041",
          "id": "916037982829322296",
          "type": "video",
          "url": "https://example.com/output-video.mp4?q-sign-algorithm=sha1&q-signature=xxxxxx"
        }
      ],
      "status": "succeeded"
    }
  ],
  "message": "SUCCEED",
  "request_id": "5d0b35d5-da56-4dae-8e6c-81035122e716-query-1786429167",
  "tokenhub_usage": {
    "total_tokens": 600000
  }
}

오류 코드

요청이 실패하면 code는 0이 아닙니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다. 작업 상태 설명은 "텍스트-영상"와 동일합니다.

부록

통합 오류 코드

HTTP 상태 코드	비즈니스 코드	오류 메시지	설명
200	0	success	요청 성공
401	1000	인증 실패	Authorization이 없거나 apikey가 유효하지 않습니다.
401	1001	Authorization이 비어 있음	Authorization 헤더가 포함되지 않았습니다.
401	1002	Authorization이 유효하지 않음	apikey가 유효하지 않거나 만료되었습니다.
401	1003	Authorization이 아직 유효하지 않음	apikey가 아직 유효하지 않습니다.
401	1004	Authorization 만료	apikey가 만료되었습니다.
429	1100	계정 이상	계정 이상(결제 연체, 정지 또는 차단 가능)
429	1101	계정 연체(후불)	후불 계정의 결제가 연체되었습니다.
429	1102	리소스 패키지 소진 또는 만료	리소스 패키지가 모두 사용되었거나 만료되었습니다.
403	1103	요청한 리소스에 대한 액세스 거부	요청한 리소스에 액세스할 수 없습니다(해당 모델/기능을 구독하지 않음).
400	1200	잘못된 요청 파라미터	요청 파라미터가 잘못되었습니다(필수 필드 누락, 잘못된 타입, 범위를 벗어난 열거형 값 등).
400	1201	잘못된 파라미터	파라미터 값이 잘못되었습니다. 문서에서 유효한 값 범위를 확인합니다.
404	1202	요청한 메서드가 유효하지 않음	HTTP 메서드가 잘못되었습니다.
404	1203	요청한 리소스가 존재하지 않음	엔드포인트 경로가 잘못되었거나 리소스가 존재하지 않습니다.
400	1300	플랫폼 정책 트리거	플랫폼 정책을 트리거했습니다(콘텐츠 검토 실패 또는 규정을 준수하지 않는 입력 등).
400	1301	플랫폼 민감 단어 목록 트리거	민감 단어 또는 규정을 준수하지 않는 프롬프트가 감지되었습니다.
429	1302	API 호출이 너무 빈번함	호출 빈도가 너무 높아 속도 제한이 적용되었습니다.
429	1303	동시성 또는 QPS 제한 초과	동시성 또는 QPS가 사전 설정된 할당량을 초과했습니다.
400	1304	IP 정책 트리거	IP 주소 정책 기반 차단이 트리거되었습니다.
500	5000	내부 서버 오류	내부 서버 오류
503	5001	서버를 일시적으로 사용할 수 없음	서비스를 일시적으로 사용할 수 없습니다(일반적으로 높은 부하 또는 유지 보수 때문).
504	5002	서버 내부 시간 초과	내부 서버 시간 초과

멀티샷 프롬프트 구문

• 형식: shot n, m, words; shot n, m, words;. 각 샷은 반각 세미콜론으로 구분하십시오.
• n: 샷 번호. 최소 1개, 최대 6개의 샷을 지원합니다.
• m: 샷 길이(초). 각 샷은 최소 1초여야 하며, 모든 샷 길이의 합은 전체 영상 길이와 같아야 합니다.
• words: 이 샷의 프롬프트. 최대 길이: 512자.
• 전체 프롬프트의 최대 길이는 3072자입니다(2500자 이하 권장). 긍정 및 부정 설명을 모두 지원합니다.
• kling-video-v3 및 kling-video-v3-omni만 이 기능을 지원하며, 적용하려면 multi_shot=true(기본값)가 필요합니다.

이미지 자산의 일반 제약 조건

형식: .jpg / .jpeg / .png(투명 채널은 지원하지 않음). 파일 크기: 50 MB 이하. 너비와 높이: 각각 최소 300 px. 비율: 1:2.5~2.5:1. URL 또는 Base64 입력을 지원합니다.

FAQ

1. 세 모델 중 어떤 모델을 선택해야 합니까?

• 4K / 네이티브 오디오 / 멀티샷 / 요소 지원을 포함해 기능이 가장 포괄적인 옵션: kling-video-v3.
• 멀티모달 혼합 입력 및 영상 편집(참조 영상, 기본 영상 재작성): kling-video-v3-omni.
• 속도와 비용을 우선하는 일괄 생성: kling-video-v3-turbo(오디오 및 멀티샷은 지원하지 않음).

2. 이미지-영상의 비율을 지정할 수 있습니까?

아니요. 이미지-영상의 출력 비율은 입력 이미지에 따라 결정되며 aspect_ratio 파라미터를 사용할 수 없습니다. 텍스트-영상 및 Omni 영상 생성만 이 파라미터를 지원하며, Omni 영상 생성에서는 시작 프레임과 참조 영상가 모두 없을 때 필수입니다.

3. 사용자 지정 요소란 무엇이며 어떻게 사용합니까?

요소는 여러 참조 이미지(image_refer) 또는 참조 영상(video_refer)로 생성한 사용자 지정 시각적 참조 대상(예: 캐릭터)입니다. 요소 관리 API를 통해 생성하면 element_id를 가져오며, 이미지-영상 및 Omni 영상 생성에서 참조하여 작업 간 캐릭터 일관성을 유지할 수 있습니다. 프롬프트에서 @ElementName으로 요소를 참조하고, 서로 부분 문자열 관계인 요소 이름은 사용하지 마십시오.

4. 사용자 지정 음성이란 무엇이며 어떻게 사용합니까?

음성은 참조 오디오(또는 오디오가 포함된 영상)로 생성한 사용자 지정 사운드 참조 대상입니다. 음성 관리 API를 통해 생성하면 voice_id를 가져오며, Omni 영상 생성, 디지털 휴먼(avatar), 립싱크(advanced-lip-sync) 등의 API에서 참조할 수 있습니다. 조회 결과의 trial_url은 임시 미리보기 URL이므로 즉시 다운로드하여 저장합니다.