Kling Motion Generation API 연동 설명

​

신청 절차

📘 전체 문서: Kling Motion Generation API →

​

기본 사용

• accept: 어떤 형식의 응답 결과를 받을지, 여기서는 application/json으로 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://platform2.cdn.acedata.cloud/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee.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://platform2.cdn.acedata.cloud/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee.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"
}

​

결론