> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Kling Videos Generation API 연동 안내 > Kling video generation 集成指南 - XHuoAPI 본 문서는 Kling Videos Generation API 연동 방법에 대해 소개합니다. 이 API는 사용자 지정 파라미터를 입력하여 Kling 공식 영상 생성이 가능합니다. ## 신청 절차 API를 사용하려면 먼저 [Kling Videos Generation API](https://api.xhuoapi.ai/documents/3b921a16-a411-4557-8335-53f21d3f9e46) 페이지에서 해당 서비스를 신청해야 합니다. 페이지에 접속 후 「Acquire」 버튼을 클릭하세요. 아래와 같이 표시됩니다: ![](https://cdn.xhuoapi.ai/q6ytrc.png) 로그인 또는 회원가입이 필요할 경우, 자동으로 로그인 페이지로 이동하며 가입 후 다시 현재 페이지로 돌아옵니다. 처음 신청 시 무료 할당량이 제공되어 무료로 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` 모델에 한함). 상세 내용은 [공식 문서](https://docs.qingque.cn/d/home/eZQAyImcbaS0fz-8ANjXvU5ed?identityId=1oEG9JKKMFv#section=h.5t7wme23nn6z). * `video_list`: 참고 영상 URL, `kling-video-o1` 모델에만 적용, 자세한 내용은 위와 동일. * `prompt`: 생성에 사용할 키워드. * `callback_url`: 결과 콜백을 받을 URL. 설정 후, 오른쪽에는 대응하는 코드도 자동 생성됩니다:

「Try」버튼을 클릭하면 테스트 수행 가능하며, 아래와 같은 응답이 반환됩니다: ```json theme={null} { "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 명령어도 제공됩니다: ```shell theme={null} 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 문서](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels)를 참고하여, `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`: 키워드. 예제 입력 화면은 다음과 같습니다:

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

파이썬 코드 예시: ```python theme={null} 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) ``` 응답 예시는 다음과 같습니다: ```json theme={null} { "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분 가량 소요됩니다. 일정 시간 동안 응답이 없다면, 연결이 유지되어 시스템 자원이 비효율적으로 사용될 수 있으므로, 비동기 콜백 기능도 지원됩니다. 전체 흐름은 다음과 같습니다: 1. 클라이언트가 요청 시 `callback_url` 필드를 지정. 2. API는 즉시 결과 `{task_id}`를 반환. 3. 작업이 완료되면, 영상 생성 결과를 POST JSON 형식으로 `callback_url`로 전송하며, 이때도 `task_id`를 포함. 4. 클라이언트는 `task_id`로 결과를 매칭 가능. 예를 들어, 웹훅 URL (개발자가 서버 구축 필요)을 공개 테스트 사이트 [https://webhook.site/를](https://webhook.site/를) 이용하는 방법은 다음과 같습니다: 1. 해당 사이트에 접속 후 Webhook URL 복사 (`https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3` 등). 2. 요청 시 `callback_url` 필드에 이 URL 입력 후 요청. 3. 요청 성공시 아래와 같이 `task_id` 값 반환: ``` { "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` 4. 잠시 후, Webhook 사이트에서 영상 결과를 확인하면 다음과 같습니다: ![](https://cdn.xhuoapi.ai/zv5u2q.png) 내용 예시: ```json theme={null} { "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`: 서버 내부 오류. ### 오류 응답 예제 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## 결론 이 문서를 통해 Kling Videos Generation API를 활용하여, 입력 키워드와 첫 프레임 참고 이미지를 통해 영상을 생성하는 방법을 이해하셨을 겁니다. 원활한 연동 및 활용에 도움이 되길 바랍니다. 궁금한 점은 언제든 고객 지원팀에 문의하시기 바랍니다.