Kling Videos Generation API 연동 설명

​

신청 절차

📘 전체 문서: Kling Videos Generation API →

​

기본 사용

• accept: 어떤 형식의 응답 결과를 받을지 지정합니다. 여기서는 JSON 형식인 application/json으로 작성합니다.
• authorization: API 호출 키이며, 신청 후 직접 드롭다운에서 선택할 수 있습니다.

• 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-o1 모델이 있습니다.
• mode: 동영상 생성 모드로, 표준 모드 std, 고속 모드 pro, 네이티브 4K 모드 4k를 선택할 수 있습니다. 그중 4k는 kling-v3 및 kling-v3-omni만 지원하며, camera_control(카메라 움직임 제어)과 호환되지 않습니다.
• action: 이번 동영상 생성 작업의 동작으로, 주로 세 가지 동작을 포함합니다: 텍스트-동영상(text2video), 이미지-동영상(image2video), 동영상 확장(extend).
• start_image_url: 이미지-동영상 동작 image2video를 선택한 경우 반드시 업로드해야 하는 첫 프레임 참조 이미지 링크입니다.
• end_image_url: 이미지-동영상 생성 시 선택 사항이며, 마지막 프레임을 지정합니다.
• duration: 동영상 길이이며, 단위는 초입니다. kling-v3 및 kling-v3-omni는 3~15초의 정수 길이를 지원하며, kling-o1은 5초만 지원하고, 기타 모델은 5초 또는 10초를 지원합니다.
• generate_audio: 오디오를 동시에 생성할지 여부이며, 선택 사항이고 불리언 값입니다. 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자입니다.
• image_list: Omni 참조 이미지 목록으로, kling-o1 및 kling-v3-omni 모델에 적용되며 사용법은 아래 「Omni 전능 참조」를 참고하세요.
• video_list: Omni 참조 동영상 목록(동영상 편집 지원)으로, kling-o1 및 kling-v3-omni 모델에 적용되며 사용법은 아래 「Omni 전능 참조」를 참고하세요.
• prompt: 프롬프트입니다.
• callback_url: 결과 콜백이 필요한 URL입니다.
• async: 선택 사항으로, true로 설정하면 인터페이스가 즉시 task_id를 반환하며 callback_url을 제공할 필요가 없습니다. 이후 해당 작업 조회 인터페이스를 통해 폴링하여 결과를 가져옵니다.

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4",
  "duration": "5.041",
  "state": "succeed",
  "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5"
}

• success: 현재 동영상 생성 작업의 상태입니다.
• task_id: 현재 동영상 생성 작업 ID입니다.
• video_id: 현재 동영상 생성 작업의 동영상 ID입니다.
• video_url: 현재 동영상 생성 작업의 동영상 링크입니다.
• duration: 현재 동영상 생성 작업의 동영상 길이입니다.
• state: 현재 동영상 생성 작업의 상태입니다.

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v3",
  "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."
}'

​

모델 기능 매트릭스

• mode=4k는 kling-v3 및 kling-v3-omni만 지원하며, camera_control（카메라 워크）과 상호 배타적입니다.
• end_image_url은 action=image2video일 때만 start_image_url과 함께 사용할 수 있습니다. end_image_url만 전달하면（start_image_url 없음）거부됩니다.
• kling-v3 / kling-v3-omni는 임의의 3–15초 정수 duration을 허용합니다；kling-o1은 5만 허용합니다；나머지 모델은 5 또는 10만 허용합니다.
• generate_audio의 기본값은 false입니다. kling-v3、kling-v3-omni 및 kling-v2-6（pro 모드）만 지원합니다.

​

비디오 확장 기능

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

주의, 여기의 비디오 video_id는 생성된 비디오의 ID입니다. 비디오를 생성하는 방법을 모른다면, 위의 기본 사용법을 참고하여 비디오를 생성할 수 있습니다.

• model：비디오를 생성하는 모델로, 주로 kling-v1、kling-v1-5 및 kling-v1-6 모델이 있습니다.
• mode：비디오 생성 모드이며, 선택 가능한 값은 표준 모드 std、고속 모드 pro 및 네이티브 4K 모드 4k입니다（kling-v3 및 kling-v3-omni만 지원하며, 카메라 워크 제어와 호환되지 않음）。
• duration：이번 비디오 생성 작업의 비디오 길이로, 주로 5s와 10s를 포함합니다.
• start_image_url：이미지-비디오 생성 동작 image2video를 선택하면 반드시 업로드해야 하는 첫 프레임 참조 이미지 링크입니다.
• prompt：프롬프트.

import requests

url = "https://api.acedata.cloud/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.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

​

Omni 만능 참조（비디오 편집 / 참조 비디오 / 다중 이미지 참조）

보안 설명：현재 API는 element_list를 공개하지 않습니다. Kling Element Library의 ID는 테넌트별로 격리되지 않으므로, 테넌트 격리를 제공하는 Element Management API 이전에는 image_list를 사용하여 주체 참조 이미지를 전달하십시오.

​

참조 비디오 및 비디오 편집（video_list）

• video_url: 참조 비디오 링크이며, 비워둘 수 없습니다. 최대 1개의 MP4/MOV 비디오, 파일 크기 ≤200MB, 프레임 레이트 24–60fps입니다. kling-o1은 길이 3–10초, 너비와 높이가 각각 700–2160px여야 하며, kling-v3-omni는 길이 3–15.5초, 너비와 높이가 각각 700–4553px, 총 픽셀 ≤8,294,400, 종횡비 0.4–2여야 합니다.
• refer_type: 참조 유형으로, base(기본값, 편집할 기본 비디오, 즉 “비디오를 직접 편집”하며 요소 추가/삭제/수정, 구도 변경, 스타일 변경, 색상 변경, 날씨 변경 등을 할 수 있음) 또는 feature(특징 참조, 스타일 / 카메라 워크 / 다음 샷 이어찍기 참조)를 선택할 수 있습니다.
• keep_original_sound: 원본 비디오 오디오를 유지할지 여부로, yes(유지) 또는 no(제거)를 선택할 수 있습니다.

참고: 참조 비디오가 있는 경우 generate_audio는 false여야 합니다. refer_type=base인 비디오는 첫 프레임 / 마지막 프레임을 다시 지정할 수 없습니다.

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "把 <<<video_1>>> 改成电影级动漫风格，保留原有的运动和构图",
  "video_list": [
    {
      "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4",
      "refer_type": "base",
      "keep_original_sound": "no"
    }
  ]
}'

​

다중 이미지 참조(image_list)

• image_url: 참조 이미지 링크이며, 비워둘 수 없습니다. 요구 사항: 형식 .jpg/.jpeg/.png, 파일 크기 ≤10MB, 짧은 변 ≥300px, 종횡비 1:2.5 ~ 2.5:1.
• type: 선택 사항입니다. 전달하지 않으면 순수 참조 이미지로 사용되며, first_frame / end_frame을 전달하면 각각 첫 프레임 / 마지막 프레임으로 사용됩니다(start_image_url / end_image_url과 동일).

참고: start_image_url / end_image_url과 image_list를 동시에 전달하면 첫 / 마지막 프레임이 image_list보다 앞에 배치되어 &lt;&lt;<image_N>>>의 번호 대응 관계에 영향을 줄 수 있습니다. 둘 중 하나를 선택하는 것이 좋습니다. 첫 / 마지막 프레임이 필요한 경우 image_list에서 직접 type으로 지정하고, start_image_url / end_image_url과 혼용하지 마세요.

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "让 <<<image_1>>> 里的人物站在 <<<image_2>>> 的场景中，电影感光线",
  "image_list": [
    { "image_url": "https://cdn.acedata.cloud/subject.png" },
    { "image_url": "https://cdn.acedata.cloud/scene.png" }
  ]
}'

​

비동기 콜백

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

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

​

오류 처리

• 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 3.0 Turbo

​

멀티 샷 비디오