Kling Motion Generation API 연동 안내

​

신청 절차

📘 전체 문서: Kling Motion Generation API →

​

기본 사용법

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

• image_url: 인물 외형 참조 이미지 URL입니다. JPG/JPEG/PNG를 지원하며, 파일은 ≤50MB, 너비와 높이는 모두 ≥300px, 종횡비는 1:2.5～2.5:1이어야 합니다. 인물의 상반신 또는 전신과 머리가 선명하게 표시되어야 합니다.
• video_url: 동작 참조 비디오 URL입니다. MP4/MOV를 지원하며, 파일은 ≤100MB, 너비와 높이는 각각 340–3850px, 최소 3초여야 합니다. character_orientation=image일 때는 최대 10초, character_orientation=video일 때는 최대 30초입니다. 인물이 항상 화면 안에 있는 연속된 단일 샷 비디오 사용을 권장합니다.
• mode: 비디오 생성 모드이며, 주로 표준 모드 std와 초고속 모드 pro 두 가지가 있습니다.
• keep_original_sound: 비디오 원본 사운드 유지 여부를 선택할 수 있으며, 열거값은 yes, no입니다.
• character_orientation: 생성 비디오에서 인물의 방향이며, 이미지와 동일하게 또는 비디오와 동일하게 선택할 수 있고, 열거값은 image, video입니다.
• prompt: 프롬프트입니다.
• callback_url: 결과를 콜백으로 받을 URL입니다.
• async: 선택 사항이며, true로 설정하면 인터페이스가 즉시 task_id를 반환하고 callback_url을 제공할 필요가 없습니다. 이후 해당 작업 조회 인터페이스를 통해 폴링하여 결과를 가져옵니다.

{
  "success": true,
  "video_id": "842578800134742051",
  "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "5.066",
  "state": "succeed",
  "task_id": "363c7a84-e880-472e-a4d4-098e50cfc292"
}

• success: 이때 비디오 생성 작업의 상태입니다.
• task_id: 이때 비디오 생성 작업 ID입니다.
• video_id: 이때 비디오 생성 작업의 비디오 ID입니다.
• video_url: 이때 비디오 생성 작업의 비디오 링크입니다.
• duration: 이때 비디오 생성 작업의 비디오 링크 길이입니다.
• state: 이때 비디오 생성 작업의 상태입니다.

curl -X POST 'https://api.acedata.cloud/kling/motion' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
  "video_url": "https://cdn.acedata.cloud/odwfm5.mp4",
  "prompt": "让画面生动起来",
  "mode": "std",
  "character_orientation": "image"
}'

​

비동기 콜백

{
  "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"
}

​

결론