Kling Videos Generation API 연동 안내

본 문서는 Kling Videos Generation API 연동 방법에 대해 소개합니다. 이 API는 사용자 지정 파라미터를 입력하여 Kling 공식 영상 생성이 가능합니다.

신청 절차

API를 사용하려면 먼저 Kling Videos Generation API 페이지에서 해당 서비스를 신청해야 합니다. 페이지에 접속 후 「Acquire」 버튼을 클릭하세요. 아래와 같이 표시됩니다:

로그인 또는 회원가입이 필요할 경우, 자동으로 로그인 페이지로 이동하며 가입 후 다시 현재 페이지로 돌아옵니다. 처음 신청 시 무료 할당량이 제공되어 무료로 API를 사용할 수 있습니다.

기본 사용 방법

먼저 기본적인 사용 방식은 입력하는 키워드 prompt, 영상 생성 행동 action, 첫 프레임 참고 이미지 start_image_url, 그리고 모델 model을 전달하여 처리된 결과를 받는 것입니다. 우선 action 필드에 값으로 text2video를 간단히 지정하며, 세 가지 행동이 포함됩니다: 텍스트 기반 영상(text2video), 이미지 기반 영상(image2video), 확장 영상(extend). 또한 사용할 모델 model을 지정하는데, 현재 주요 모델은 kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-video-o1이며, 구체 내용은 아래와 같습니다.

이때 Request Headers에는 다음과 같이 세팅됩니다:

accept: 응답 형식을 지정하며, 여기에는 application/json으로 JSON 형식을 입력합니다.
authorization: API 호출용 키. 신청 후 바로 선택 가능.

Request Body에는 다음 항목이 포함됩니다:

model: 영상 생성 모델이며, kling-v1, kling-v1-6, kling-v2-master 등.
mode: 영상 생성 모드로, 표준 std, 고속 pro, 4K 원본 4k 옵션이 있으며, 4k는 kling-v3와 kling-v3-omni에만 지원되고 camera_control과는 호환되지 않습니다.
action: 이번 영상 생성 작업에 대한 행동으로, text2video, image2video, extend.
start_image_url: image2video 행동 선택시 필수로 업로드하는 첫 번째 프레임 참고 이미지 링크.
end_image_url: image2video 시 선택적, 마지막 프레임 지정.
duration: 영상 길이(초), kling-v3, kling-v3-omni 모델은 3~15초(정수), 나머지는 5 또는 10초 지원.
generate_audio: 오디오 동기 생성 여부(Boolean), kling-v3, kling-v3-omni, kling-v2-6(pro) 지원. 기본값은 false.
aspect_ratio: 영상 가로 세로 비율(16:9, 9:16, 1:1), 기본값 16:9.
cfg_scale: 관련성 강도 (0~1), 값이 클수록 입력 프롬프트와 더 밀접.
camera_control: 카메라 움직임 제어 옵션, type/simple 사전설정, horizontal, vertical, pan, tilt, roll, zoom 등 구성.
negative_prompt: 촬영에서 제외할 키워드, 최대 200자.
element_list: 주체 참조 리스트 (kling-video-o1 모델에 한함). 상세 내용은 공식 문서.
video_list: 참고 영상 URL, kling-video-o1 모델에만 적용, 자세한 내용은 위와 동일.
prompt: 생성에 사용할 키워드.
callback_url: 결과 콜백을 받을 URL.

설정 후, 오른쪽에는 대응하는 코드도 자동 생성됩니다:

「Try」버튼을 클릭하면 테스트 수행 가능하며, 아래와 같은 응답이 반환됩니다:

{
  "success": true,
  "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0"
}

여기서 반환하는 여러 필드에 대해 설명하면:

success: 영상 생성 작업 성공 여부.
task_id: 작업 ID.
video_id: 생성된 영상 ID.
video_url: 영상 링크.
duration: 영상 길이.
state: 작업 상태.

이 정보들을 참고하여 video_url에서 생성된 Kling 영상을 확인할 수 있습니다. 또한, 연동용 코드 예시로 CURL 명령어도 제공됩니다:

curl -X POST 'https://api.xhuoapi.ai/v1/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v1",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

모델 능력 매트릭스

모델별 파라미터 지원 내용은 차이가 큽니다. Kling 공식 video models 문서를 참고하여, model / mode / duration 조합이 현재 요구하는 기능을 지원하는지 사전 체크하세요. 지원 안 될 경우 model/mode/duration(...) is not supported with image_tail 등의 오류가 발생할 수 있습니다.

모델	모드	`end_image_url`(첫/끝 프레임)	`generate_audio` (음성 동기)	`camera_control`(운맛 제어)	비고
`kling-v1`	std / pro	✅ `duration=5`만	❌	✅ `duration=5`만	`extend`는 `negative_prompt`, `cfg_scale` 미지원
`kling-v1-6`	std	❌	❌	❌	다중이미지 영상, `extend` 전체 모드 지원
`kling-v1-6`	pro	✅	❌	❌
`kling-v2-master`	—	❌	❌	❌	단일 모드, `duration=5/10`만 지원
`kling-v2-1-master`	—	❌	❌	❌	동일
`kling-v2-5-turbo`	std	❌	❌	❌
`kling-v2-5-turbo`	pro	✅	❌	❌
`kling-v2-6`	std	❌	❌	❌
`kling-v2-6`	pro	✅	✅	❌	유일하게 음성 지원하는 비 v3 모델
`kling-v3`	std / pro	✅	✅	✅	`duration` 3~15초 범위 지원
`kling-v3`	4k	✅	✅	❌	4K 모드와 `camera_control` 호환 불가
`kling-v3-omni`	std / pro / 4k	✅	✅	❌
`kling-video-o1`	std / pro	✅	❌	❌	`duration=5/10`만 지원

주의사항:

mode=4k는 오직 kling-v3와 kling-v3-omni만 지원하며, camera_control과는 호환되지 않습니다.
end_image_url는 action=image2video일 때만 start_image_url과 함께 사용 가능하며, 단독으로 전달 시 거부됩니다.
kling-v3와 kling-v3-omni는 3~15초 사이 정수값 duration을 허용하며, 기타 모델은 5 또는 10초만 지원.
generate_audio 기본값은 false. kling-v3, kling-v3-omni, kling-v2-6(pro모드)만 지원됩니다.

확장 영상 기능

생성된 Kling 영상을 계속해서 연장하려면, action을 extend로 설정하고, 연장할 영상 ID를 입력합니다. 영상 ID는 기본 사용 방법처럼 video_id를 통해 얻을 수 있으며, 예시는 아래와 같습니다.

이때 영상 ID는:

"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"

참고로, 여기 video_id는 생성 후 영상의 ID입니다. 영상 생성 방법은 앞서 설명한 기본 사용을 참고하세요.

이후, 특정 프롬프트를 입력하여 다음 단계 연장 영상도 생성할 수 있는데, 예시는 다음과 같습니다.

model: kling-v1, kling-v1-5, kling-v1-6.
mode: std, pro, 4k(kling-v3, kling-v3-omni 한정).
duration: 5초 또는 10초.
start_image_url: image2video 행동 시 필수.
prompt: 키워드.

예제 입력 화면은 다음과 같습니다:

입력 완료 후, 자동으로 생성된 코드는 다음과 같습니다:

파이썬 코드 예시:

import requests

url = "https://api.xhuoapi.ai/v1/kling/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "model": "kling-v1",
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "duration": 10
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

응답 예시는 다음과 같습니다:

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

위 내용은 이전과 동일하며, 영상 연장 기능이 구현됩니다.

비동기 콜백

Kling Videos Generation API는 영상 생성에 다소 시간이 소요되므로, 요청 후 1~2분 가량 소요됩니다. 일정 시간 동안 응답이 없다면, 연결이 유지되어 시스템 자원이 비효율적으로 사용될 수 있으므로, 비동기 콜백 기능도 지원됩니다. 전체 흐름은 다음과 같습니다:

클라이언트가 요청 시 callback_url 필드를 지정.
API는 즉시 결과 {task_id}를 반환.
작업이 완료되면, 영상 생성 결과를 POST JSON 형식으로 callback_url로 전송하며, 이때도 task_id를 포함.
클라이언트는 task_id로 결과를 매칭 가능.

예를 들어, 웹훅 URL (개발자가 서버 구축 필요)을 공개 테스트 사이트 https://webhook.site/를 이용하는 방법은 다음과 같습니다:

해당 사이트에 접속 후 Webhook URL 복사 (https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3 등).
요청 시 callback_url 필드에 이 URL 입력 후 요청.
요청 성공시 아래와 같이 task_id 값 반환:

{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

잠시 후, Webhook 사이트에서 영상 결과를 확인하면 다음과 같습니다:

내용 예시:

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

이로써 task_id로 작업 결과를 연결할 수 있습니다.

오류 처리

API 호출 시 오류 발생 시, 오류 코드와 메시지가 반환됩니다. 예시:

400 token_mismatched: 잘못된 요청, 파라미터 누락 또는 무효.
400 api_not_implemented: 지원되지 않거나 잘못된 파라미터.
401 invalid_token: 인증 토큰 무효 또는 누락.
429 too_many_requests: 요청 초과, 요청 제한 초과.
500 api_error: 서버 내부 오류.

오류 응답 예제

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

결론

이 문서를 통해 Kling Videos Generation API를 활용하여, 입력 키워드와 첫 프레임 참고 이미지를 통해 영상을 생성하는 방법을 이해하셨을 겁니다. 원활한 연동 및 활용에 도움이 되길 바랍니다. 궁금한 점은 언제든 고객 지원팀에 문의하시기 바랍니다.

Documentation Index

​신청 절차

​기본 사용 방법

​모델 능력 매트릭스

​확장 영상 기능

​비동기 콜백

​오류 처리

​오류 응답 예제

​결론