개발가이드AI•LLMKling 영상 생성 AI

Kling 영상 생성 AI API

명세 내보내기
OpenAPI 3.0.3Postman 컬렉션Markdown

3.0·o1·o3 버전과 텍스트·이미지·참조 소재 입력으로 최대 15초 영상을 만드는 생성 API

POSThttps://apick.app/rest/kling/jobs전체 3개 경로
인증
Bearer 키
요청 형식
form-data / GET
응답
JSON · 파일
경로
3개

왜 Kling 영상 생성 AI인가

멈춰 있던 사진, 소재만 넣으면 움직입니다

정지 이미지로는 시선을 붙잡기 어렵고 영상 외주는 느립니다. 텍스트·이미지·참조 소재를 넣고 원하는 버전을 골라 짧은 영상을 바로 만듭니다.

도입 효과

  • 이미지 자산을 영상 자산으로 전환
  • 참조 소재로 등장 요소 일관성 유지
  • 외주 없이 영상 소재 확보

이런 곳에서 많이 씁니다

  • 패션몰 룩북 사진 영상화
  • 캐릭터·웹툰 홍보 영상
  • 이벤트 페이지 움직이는 배너
  • 숏폼 광고 소재 제작
가입하고 API 키 받기API 키 하나로 바로 호출 · 실패한 요청은 과금되지 않습니다

알아둘 점

지원 버전 한눈에 보기

버전
지원 생성 방식과 최대 길이
3.0 · 기본 버전
텍스트→영상 · 이미지+텍스트→영상 · 참조 이미지+텍스트→영상 · 이미지+텍스트+참조 영상→영상
최대 15초 · 참조 영상만 단독 입력할 수 없으며 참조 이미지가 함께 필요합니다.
o3
텍스트→영상 · 이미지+텍스트→영상 · 참조 이미지+텍스트→영상
최대 15초
o1
텍스트→영상
최대 10초

연동 흐름

작업을 접수하고, 진행 상황을 조회하다가, 완료되면 MP4 파일을 내려받습니다. 접수 후에는 취소할 수 없으며, 실패하거나 처리 시간이 초과되면 예약된 포인트가 자동으로 전액 환불됩니다.

Method
URL
기능
성공 결과
POST
/rest/kling/jobs
영상 작업 접수
HTTP 202와 job_id
GET
/rest/kling/jobs/{job_id}
진행 조회(무료)
HTTP 200과 현재 status
GET
/rest/kling/jobs/{job_id}/result
MP4 다운로드(무료, Range 지원)
<job_id>.mp4

결과 다운로드

result_available이 true일 때 GET /rest/kling/jobs/{job_id}/result를 인증 헤더와 함께 호출하면 video/mp4 파일을 받습니다. 완료 후 7일 동안 반복해서 내려받을 수 있고, Range 헤더로 일부 구간만 받을 수 있습니다(HTTP 206). 기간이 지나면 APICK_VIDEO_RESULT_EXPIRED(410)입니다.

요금

등급·해상도
초당 포인트
5초 예시
std
410P
2,050P
pro
550P
2,750P

접수 시 duration × 초당 포인트를 예약 차감합니다. 완료되면 그대로 확정되고, 실패하거나 처리 시간이 초과되면 전액 환불됩니다. 진행 조회와 다운로드는 무료입니다.

MCP

kling_jobs_create로 작업을 접수하고 kling_jobs_status로 진행 상황을 조회합니다. 영상 파일은 MCP 응답으로 직접 받지 않고, 진행 조회 응답의 result_url로 REST 다운로드합니다. 자세한 내용은 MCP 연동 가이드와 /mcp/ai를 확인하세요.

업로드 용량 제한: 100MB
multipart/form-data 요청에 포함된 입력 이미지·참조 영상·참조 오디오의 합계는 최대 100MB입니다. 이미지는 PNG·JPEG·WebP, 영상은 MP4·MOV·WebM, 오디오는 MP3·WAV를 지원하며 모델별 개수·해상도·종횡비 제약은 가이드의 파라미터 표를 따릅니다.
제한을 초과하면 HTTP 413과 REQUEST_TOO_LARGE 오류가 반환되며 과금되지 않습니다.

요청과 응답

1작업 접수
POST/rest/kling/jobs
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 15개 · 필수 1
파라미터
설명
promptstring필수
생성할 영상의 장면·동작·카메라 움직임을 설명합니다. 최대 2,000자이며, 구체적인 피사체와 배경을 적을수록 의도에 가까운 결과가 나옵니다.
최대 길이
2000자
예시
도심 야경 속을 걷는 인물의 뒷모습, 네온 반사
versionstring선택
영상 모델 버전. 생략 시 3.0. 등급·해상도·길이·오디오·파일 제약과 요금은 선택 버전별 개발가이드 표를 확인하세요. 가능한 값은 3가지입니다. 3.0 = 3.0 버전을 선택한 값입니다. 같은 제품이라도 버전별 지원 등급·길이·해상도·오디오·요금이 다르므로 이 문서의 버전 표와 대조하세요. o3 = o3 버전을 선택한 값입니다. 같은 제품이라도 버전별 지원 등급·길이·해상도·오디오·요금이 다르므로 이 문서의 버전 표와 대조하세요. o1 = o1 버전을 선택한 값입니다. 같은 제품이라도 버전별 지원 등급·길이·해상도·오디오·요금이 다르므로 이 문서의 버전 표와 대조하세요.
허용값
3.0 o3 o1
modestring선택
입력 방식 — 'text'(텍스트만) | 'image'(첫 프레임 이미지 지정) | 'reference'(참조 이미지·영상으로 주체 지정). 기본 text 가능한 값은 3가지입니다. text = 텍스트 프롬프트만으로 결과를 만드는 값입니다. 이미지 입력 없이 문장 묘사만 사용합니다. image = 이미지 1장을 첫 프레임·기준 이미지로 쓰는 값입니다. 이미지와 프롬프트를 함께 보냅니다. reference = 참조 이미지·영상을 스타일 기준으로 쓰는 값입니다. 여러 장을 보낼 수 있고, 제품별 최대 장수가 다릅니다.
허용값
text image reference
tierstring선택
품질·속도 등급. 지원 등급과 생략 시 기본값은 version과 mode에 따라 다릅니다. 가능한 값은 5가지입니다. std = 표준 품질 등급입니다. 표기만 std이며 standard와 같은 뜻으로 쓰는 제품이 많습니다. pro = 상위 품질 등급입니다. 표준보다 화질·디테일이 좋고 처리 시간과 요금이 더 큽니다. turbo = 가장 빠른 생성 등급입니다. 짧은 대기 시간을 우선할 때 쓰며 화질은 표준보다 낮을 수 있습니다. 4k = 4K 해상도 출력을 전제로 한 고화질 등급입니다. 지원 버전이 제한되고 단가가 가장 높습니다. standard = 표준 품질·속도 등급입니다. 대부분 제품의 기본값이며 품질과 처리 시간의 균형을 맞춘 등급입니다.
허용값
std pro turbo 4k standard
예시
std
durationinteger선택
영상 길이(초), 전체 버전 범위 3~15. 허용 값과 기본값은 버전·등급별로 다릅니다.
범위
3 ~ 15
예시
5
aspect_ratiostring선택
출력 영상의 가로:세로 비율입니다. 예: 16:9, 9:16, 1:1. 선택한 버전·등급·모드에서 허용하는 값만 사용할 수 있으며, 다른 값은 접수 전에 거부됩니다. 가능한 값은 3가지입니다. 16:9 = 가로가 긴 와이드 비율입니다. 유튜브·TV처럼 가로 화면에 맞습니다. 9:16 = 세로로 긴 비율입니다. 숏폼·모바일 세로 화면에 맞습니다. 1:1 = 가로·세로가 같은 정사각 비율입니다. 피드·프로필 이미지에 맞습니다.
허용값
16:9 9:16 1:1
resolutionstring선택
출력 해상도. 전체 버전의 값 목록이며 허용 조합·기본값·요금은 버전별 개발가이드를 따릅니다. 가능한 값은 6가지입니다. 720p = 가로 1280픽셀급의 HD 해상도입니다. 일반적인 웹 재생에 적합합니다. 1080p = 가로 1920픽셀급의 Full HD 해상도입니다. 화질을 우선할 때 사용하며 단가가 더 높습니다. 720P = 가로 1280픽셀급의 HD 해상도입니다. 표기만 대문자이며 720p와 같은 뜻입니다. 1080P-SR = Full HD(1080p) 입력을 초해상도(SR)로 확대한 해상도입니다. 원본보다 선명하지만 단가가 더 높습니다. 1440P-SR = QHD(1440p)급으로 초해상도(SR) 처리한 해상도입니다. Full HD보다 큰 화면에 맞고 단가가 가장 높습니다. 1080P = 가로 1920픽셀급의 Full HD 해상도입니다. 표기만 대문자이며 1080p와 같은 뜻입니다.
허용값
720p 1080p 720P 1080P-SR 1440P-SR 1080P
audioboolean선택
오디오 생성 여부. 선택 가능한 버전은 기본 true, 무음 전용 버전은 false, 오디오 필수 버전은 true만 허용합니다. true = 오디오가 포함된 영상을 만든 경우, false = 무음 영상인 경우입니다. 제품이 오디오 생성을 지원하지 않으면 항상 false입니다.
negative_promptstring선택
결과에서 빼고 싶은 요소를 적습니다. 예: text, watermark, blurry. negative_prompt를 지원하지 않는 제품에서는 무시됩니다.
최대 길이
1000자
cfg_scalenumber선택
프롬프트를 얼마나 강하게 반영할지 정합니다. 0~1 범위이며, 생략하면 0.5입니다. 값이 높을수록 지시에 가깝지만 과하면 부자연스러울 수 있습니다.
범위
0 ~ 1
idempotency_keystring선택
같은 요청을 다시 보낼 때 중복 접수·과금을 막는 고유 키입니다. 요청 내용이 같으면 같은 키를 유지하고, 내용이 바뀌면 새 키를 만드세요.
최대 길이
128자
형식
^[A-Za-z0-9_-]+$
imagefile조건부
분석할 이미지 파일입니다. JPG·PNG·WEBP를 지원하며, 파일 크기·해상도 제한은 요청 표를 확인하세요.
last_imagefile선택
image 모드에서 마지막 프레임 이미지 1장. multipart/form-data로 전송하며, 파일 경로가 아니라 파일 본문을 첨부합니다.
reference_imagefile조건부
reference 모드 필수. 주체를 참조할 이미지 1~6장. multipart/form-data로 전송하며, 파일 경로가 아니라 파일 본문을 첨부합니다.
reference_videofile선택
reference 모드에서 동작을 참조할 영상 0~4개. MP4·MOV·WebM, 50MB 이하.
응답 필드 27개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.job_idstring
접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.
data.modelstring
응답을 생성한 모델 ID입니다. 요청에서 지정한 모델과 같으며, 모델 목록 API의 id 값과 비교해 확인합니다. 가능한 값은 3가지입니다. seedance = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다. veo = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다. kling = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다.
허용값
seedance veo kling
data.versionstring
요청한 제품의 세대·버전입니다. 같은 제품이라도 버전에 따라 지원 길이·해상도·가격이 달라지므로 견적 응답의 값과 대조하세요.
data.modestring
영상 생성에 사용한 입력 방식입니다. text는 텍스트만, image는 이미지 1장, reference는 참조 이미지 여러 장을 쓰는 방식입니다. 가능한 값은 3가지입니다. text = 텍스트 프롬프트만으로 결과를 만드는 값입니다. 이미지 입력 없이 문장 묘사만 사용합니다. image = 이미지 1장을 첫 프레임·기준 이미지로 쓰는 값입니다. 이미지와 프롬프트를 함께 보냅니다. reference = 참조 이미지·영상을 스타일 기준으로 쓰는 값입니다. 여러 장을 보낼 수 있고, 제품별 최대 장수가 다릅니다.
허용값
text image reference
data.tierstring
영상 생성 품질 등급입니다. 등급이 높을수록 해상도·디테일이 좋아지고 초당 포인트 단가도 높아집니다.
data.statusstring
현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 가능한 값은 4가지입니다. waiting = 접수만 되고 처리는 시작되지 않은 상태입니다. 결과가 비어 있으므로 같은 작업 ID로 잠시 후 다시 조회합니다. processing = 처리 중인 상태입니다. 결과가 아직 확정되지 않았으므로 완료 상태가 될 때까지 조회를 반복합니다. completed = 정상 완료된 상태입니다. 결과 필드나 파일 경로에서 실제 결과를 사용할 수 있습니다. failed = 작업이 실패한 상태입니다. error의 code·message로 원인을 확인하고 재시도 가능 여부를 판단합니다.
허용값
waiting processing completed failed
data.durationinteger
요청한 영상 길이(초)입니다. 제품·등급별 허용 범위가 다르며, 접수 후에는 변경할 수 없습니다.
data.aspect_ratiostring
출력 영상의 가로:세로 비율입니다. 예: 16:9, 9:16, 1:1. 입력 이미지 비율과 다르면 일부가 잘릴 수 있습니다.
data.resolutionstring
출력 영상의 해상도입니다. 720p·1080p 등 제품별 지원 값이 다르며, 높을수록 포인트 단가가 높아집니다.
data.audioboolean
영상에 오디오를 함께 생성했는지 여부입니다. false면 무음 영상이며, 제품에 따라 오디오 생성이 지원되지 않을 수 있습니다. true = 오디오가 포함된 영상을 만든 경우, false = 무음 영상인 경우입니다. 제품이 오디오 생성을 지원하지 않으면 항상 false입니다.
data.point_per_secondnumber
접수 시 적용한 초당 포인트 단가입니다. 영상 길이와 곱하면 차감 포인트를 계산할 수 있으며, 실시간 견적 여부에 따라 달라집니다.
data.charged_pointnumber
최종 차감된 포인트입니다. 실패·부분 성공 시 환급이 반영된 값입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.result_availableboolean
결과 파일을 지금 내려받을 수 있는지 여부입니다. false면 아직 처리 중이거나 결과가 만료·삭제된 상태입니다. true = 결과 파일을 지금 내려받을 수 있는 경우, false = 처리 중이거나 실패·만료된 경우입니다.
data.result_expires_atstring
결과 만료 ISO 8601 일시. 결과가 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
data.result_urlstring
완료·미만료 상태에서만 제공되는 에이픽 결과 다운로드 주소. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.created_atstring
작업이 접수된 일시입니다. ISO 8601 형식이며, 결과 만료 시각을 계산할 때 기준으로 사용합니다.
data.completed_atstring
작업이 완료된 일시입니다. 완료 전에는 null이며, 처리 시간을 계산할 때 created_at과 함께 사용합니다. null 허용.
data.errorobject
작업 실패 원인을 담은 객체입니다. 공개 오류코드(code)와 사람이 읽을 설명(message)이 들어 있으며, 성공한 작업에는 없습니다.
data.idempotent_replayboolean
같은 멱등 키로 기존 작업을 반환하면 true. 재전송의 api.cost는 0입니다. true = 같은 멱등 키로 기존 작업을 그대로 돌려준 경우(재전송이라 추가 차감 없음), false = 새로 처리한 경우입니다.
data.price_sourcestring
신규 접수 단가 기준. live=실시간 견적, table=기본 단가표. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. 가능한 값은 2가지입니다. live = 접수 시점의 실시간 견적으로 단가를 정한 경우입니다. 같은 요청이라도 견적이 바뀌면 단가가 달라질 수 있습니다. table = 실시간 견적을 받지 못해 기본 단가표로 계산한 경우입니다. 실제 차감액은 api.cost로 확인하세요.
허용값
live table
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costnumber
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.pl_idinteger
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.
하위 필드 2개 더 보기
응답 필드
설명
data.error.codestring
작업 실패의 공개 오류코드입니다. 같은 코드는 같은 원인을 뜻하며, 재시도 가능 여부는 오류 문서를 확인하세요.
data.error.messagestring
작업 실패 내용을 사람이 읽을 수 있게 설명합니다. 상세 원인은 서버 로그에만 남으며, 고객에게는 이 문구를 안내하세요. null 허용.
2상태·목록 조회
GET/rest/kling/jobs/:job_id
  • Bearer 인증
  • 요청 본문 없음
  • JSON 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 25개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.job_idstring
접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.
data.modelstring
응답을 생성한 모델 ID입니다. 요청에서 지정한 모델과 같으며, 모델 목록 API의 id 값과 비교해 확인합니다. 가능한 값은 3가지입니다. seedance = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다. veo = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다. kling = 영상 생성 제품 값입니다. 제품별 버전·등급·길이·해상도 지원 범위가 다릅니다.
허용값
seedance veo kling
data.versionstring
요청한 제품의 세대·버전입니다. 같은 제품이라도 버전에 따라 지원 길이·해상도·가격이 달라지므로 견적 응답의 값과 대조하세요.
data.modestring
영상 생성에 사용한 입력 방식입니다. text는 텍스트만, image는 이미지 1장, reference는 참조 이미지 여러 장을 쓰는 방식입니다. 가능한 값은 3가지입니다. text = 텍스트 프롬프트만으로 결과를 만드는 값입니다. 이미지 입력 없이 문장 묘사만 사용합니다. image = 이미지 1장을 첫 프레임·기준 이미지로 쓰는 값입니다. 이미지와 프롬프트를 함께 보냅니다. reference = 참조 이미지·영상을 스타일 기준으로 쓰는 값입니다. 여러 장을 보낼 수 있고, 제품별 최대 장수가 다릅니다.
허용값
text image reference
data.tierstring
영상 생성 품질 등급입니다. 등급이 높을수록 해상도·디테일이 좋아지고 초당 포인트 단가도 높아집니다.
data.statusstring
현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 가능한 값은 4가지입니다. waiting = 접수만 되고 처리는 시작되지 않은 상태입니다. 결과가 비어 있으므로 같은 작업 ID로 잠시 후 다시 조회합니다. processing = 처리 중인 상태입니다. 결과가 아직 확정되지 않았으므로 완료 상태가 될 때까지 조회를 반복합니다. completed = 정상 완료된 상태입니다. 결과 필드나 파일 경로에서 실제 결과를 사용할 수 있습니다. failed = 작업이 실패한 상태입니다. error의 code·message로 원인을 확인하고 재시도 가능 여부를 판단합니다.
허용값
waiting processing completed failed
data.durationinteger
요청한 영상 길이(초)입니다. 제품·등급별 허용 범위가 다르며, 접수 후에는 변경할 수 없습니다.
data.aspect_ratiostring
출력 영상의 가로:세로 비율입니다. 예: 16:9, 9:16, 1:1. 입력 이미지 비율과 다르면 일부가 잘릴 수 있습니다.
data.resolutionstring
출력 영상의 해상도입니다. 720p·1080p 등 제품별 지원 값이 다르며, 높을수록 포인트 단가가 높아집니다.
data.audioboolean
영상에 오디오를 함께 생성했는지 여부입니다. false면 무음 영상이며, 제품에 따라 오디오 생성이 지원되지 않을 수 있습니다. true = 오디오가 포함된 영상을 만든 경우, false = 무음 영상인 경우입니다. 제품이 오디오 생성을 지원하지 않으면 항상 false입니다.
data.point_per_secondnumber
접수 시 적용한 초당 포인트 단가입니다. 영상 길이와 곱하면 차감 포인트를 계산할 수 있으며, 실시간 견적 여부에 따라 달라집니다.
data.charged_pointnumber
최종 차감된 포인트입니다. 실패·부분 성공 시 환급이 반영된 값입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.result_availableboolean
결과 파일을 지금 내려받을 수 있는지 여부입니다. false면 아직 처리 중이거나 결과가 만료·삭제된 상태입니다. true = 결과 파일을 지금 내려받을 수 있는 경우, false = 처리 중이거나 실패·만료된 경우입니다.
data.result_expires_atstring
결과 만료 ISO 8601 일시. 결과가 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
data.result_urlstring
완료·미만료 상태에서만 제공되는 에이픽 결과 다운로드 주소. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.created_atstring
작업이 접수된 일시입니다. ISO 8601 형식이며, 결과 만료 시각을 계산할 때 기준으로 사용합니다.
data.completed_atstring
작업이 완료된 일시입니다. 완료 전에는 null이며, 처리 시간을 계산할 때 created_at과 함께 사용합니다. null 허용.
data.errorobject
작업 실패 원인을 담은 객체입니다. 공개 오류코드(code)와 사람이 읽을 설명(message)이 들어 있으며, 성공한 작업에는 없습니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costnumber
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.pl_idinteger
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.
하위 필드 2개 더 보기
응답 필드
설명
data.error.codestring
작업 실패의 공개 오류코드입니다. 같은 코드는 같은 원인을 뜻하며, 재시도 가능 여부는 오류 문서를 확인하세요.
data.error.messagestring
작업 실패 내용을 사람이 읽을 수 있게 설명합니다. 상세 원인은 서버 로그에만 남으며, 고객에게는 이 문구를 안내하세요. null 허용.
3결과 받기
GET/rest/kling/jobs/:job_id/result
  • Bearer 인증
  • 요청 본문 없음
  • 파일 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 파일

정상 응답은 파일 본문입니다. 실패 시 JSON 오류가 올 수 있으므로 HTTP 상태와 Content-Type을 먼저 확인하세요.

입력 조건·전송 규칙
입력 조건 전체 펼쳐 보기

입력 방식부터 고르기

같은 제품이라도 버전에 따라 받을 수 있는 소재가 다릅니다. 여기서 ‘영상 참조’는 기존 영상을 그대로 편집하는 기능이 아니라, 업로드한 영상의 동작과 흐름을 참고해 새 영상을 만드는 기능입니다.

원하는 작업
선택할 모드와 입력
텍스트로 영상 생성
mode=text · prompt만 입력
이미지로 영상 생성
mode=image · 첫 프레임 이미지와 텍스트 입력, 지원 버전은 마지막 프레임도 선택 가능
영상으로 영상 생성
mode=reference · 참조 영상을 받아 새 영상을 만드는 버전만 가능
여러 소재로 영상 생성
mode=reference · 지원 버전에서 참조 이미지·영상·오디오를 조합해 입력

버전별 세부 옵션과 요금

version은 선택 입력입니다. 생략하면 3.0을 사용하며 다른 버전으로 자동 변경하지 않습니다. 아래 표의 모드·등급 조합만 사용할 수 있습니다. 기존 요청 설명은 기본 버전 기준이며 다른 버전은 이 표를 따릅니다.

요금은 접수 시점에 실시간으로 확정됩니다. 표의 금액은 기준 단가이며, 실제 차감 포인트는 접수 응답의 charged_point·point_per_second로 확인할 수 있습니다.

버전 · 모드 · 등급
지원 옵션과 초당 포인트
3.0 · 텍스트→영상 (text) · std

길이3~15초기본 5초

해상도·요금자동410P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

추가 옵션negative_prompt, cfg_scale

3.0 · 텍스트→영상 (text) · pro

길이3~15초기본 5초

해상도·요금자동550P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

추가 옵션negative_prompt, cfg_scale

3.0 · 텍스트→영상 (text) · turbo

길이3~15초기본 5초

해상도·요금720p430P/초1080p430P/초

화면 비율16:9 · 9:16 · 1:1

오디오미지원 (audio=false)

추가 옵션없음

3.0 · 텍스트→영상 (text) · 4k

길이3~15초기본 5초

해상도·요금자동1,610P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

추가 옵션negative_prompt, cfg_scale

3.0 · 이미지+텍스트→영상 (image) · std

길이3~15초기본 5초

해상도·요금720P410P/초1080P-SR410P/초1440P-SR410P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

마지막 프레임선택 가능

추가 옵션negative_prompt, cfg_scale

3.0 · 이미지+텍스트→영상 (image) · pro

길이3~15초기본 5초

해상도·요금1080P550P/초1440P-SR550P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

마지막 프레임선택 가능

추가 옵션negative_prompt, cfg_scale

3.0 · 이미지+텍스트→영상 (image) · turbo

길이3~15초기본 5초

해상도·요금720p430P/초1080p430P/초

화면 비율입력 이미지 기준, 지정값 무시

오디오미지원 (audio=false)

추가 옵션없음

3.0 · 이미지+텍스트→영상 (image) · 4k

길이3~15초기본 5초

해상도·요금자동1,610P/초

화면 비율입력 이미지 기준, 지정값 무시

오디오선택 가능 (기본 true)

마지막 프레임선택 가능

추가 옵션negative_prompt, cfg_scale

3.0 · 참조 소재→영상 (reference) · std

길이3~15초기본 5초

해상도·요금자동410P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

참조 이미지1~6개

참조 영상최대 4개

추가 옵션negative_prompt, cfg_scale

3.0 · 참조 소재→영상 (reference) · pro

길이3~15초기본 5초

해상도·요금자동550P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

참조 이미지1~6개

참조 영상최대 4개

추가 옵션negative_prompt, cfg_scale

o3 · 텍스트→영상 (text) · std

길이3~15초기본 5초

해상도·요금자동320P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

추가 옵션없음

o3 · 텍스트→영상 (text) · pro

길이3~15초기본 5초

해상도·요금자동430P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

추가 옵션없음

o3 · 텍스트→영상 (text) · 4k

길이3~15초기본 5초

해상도·요금자동1,610P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

추가 옵션없음

o3 · 이미지+텍스트→영상 (image) · std

길이3~15초기본 5초

해상도·요금자동320P/초

화면 비율입력 이미지 기준, 지정값 무시

오디오선택 가능 (기본 true)

마지막 프레임선택 가능

추가 옵션없음

o3 · 이미지+텍스트→영상 (image) · pro

길이3~15초기본 5초

해상도·요금자동430P/초

화면 비율입력 이미지 기준, 지정값 무시

오디오선택 가능 (기본 true)

마지막 프레임선택 가능

추가 옵션없음

o3 · 이미지+텍스트→영상 (image) · 4k

길이3~15초기본 5초

해상도·요금자동1,610P/초

화면 비율입력 이미지 기준, 지정값 무시

오디오선택 가능 (기본 true)

마지막 프레임선택 가능

추가 옵션없음

o3 · 참조 소재→영상 (reference) · std

길이3~15초기본 5초

해상도·요금자동320P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

참조 이미지1~7개

추가 옵션없음

o3 · 참조 소재→영상 (reference) · pro

길이3~15초기본 5초

해상도·요금자동430P/초

화면 비율16:9 · 9:16 · 1:1

오디오선택 가능 (기본 true)

참조 이미지1~7개

추가 옵션없음

o1 · 텍스트→영상 (text) · standard

길이5초 · 10초기본 5초

해상도·요금자동430P/초

화면 비율16:9 · 9:16 · 1:1

오디오미지원 (audio=false)

추가 옵션없음

요청 예: {"version":"3.0","mode":"text","prompt":"바닷가를 달리는 자전거"}. 생성·상태 응답의 version에서 실제 선택 버전을 확인할 수 있습니다. 미지원 버전은 APICK_VIDEO_VERSION_INVALID, 미지원 옵션 조합은 해당 옵션 오류로 과금 전에 거절됩니다.

요청 — 작업 접수

form-data로 보냅니다. 파일은 같은 요청에 첨부하며, 같은 항목 이름을 반복하면 여러 파일이 됩니다(예: reference_image 3번). 표의 범위는 기본 버전 기준이며 다른 버전은 위 버전별 표를 따릅니다. 지원하지 않는 옵션·조합은 과금 전에 거절됩니다.

이미지는 PNG·JPEG, 가로·세로 300~8,192px, 종횡비 0.4~2.5, 10MB 이하입니다(다른 영상 제품보다 한도가 낮습니다).

사용 예시

상황별로 보내는 값과 응답에서 확인할 값을 모았습니다. 언어 탭에서 그대로 복사해 쓸 수 있습니다.

예시 1. 텍스트로 5초 영상

기본 버전 std 등급으로 텍스트만 보내 영상을 만듭니다.

요청POST/rest/kling/jobs
curl --fail-with-body --request POST 'https://apick.app/rest/kling/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=도심 야경 속을 걷는 인물의 뒷모습, 네온 반사' \
  --form-string 'duration=5' \
  --form-string 'tier=std'
  • HTTP 202와 data.job_id를 받고, data.charged_point가 예약 차감됩니다.
예시 2. 이미지로 영상 만들고 해상도 지정

해상도는 image 모드에서만 고를 수 있습니다.

요청POST/rest/kling/jobs
curl --fail-with-body --request POST 'https://apick.app/rest/kling/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'duration=5' \
  --form-string 'mode=image' \
  --form 'image=@./first_frame.png' \
  --form-string 'prompt=바람에 머리카락이 흩날리는 장면' \
  --form-string 'resolution=720P'
  • 이미지는 PNG·JPEG, 10MB 이하입니다. 넘으면 APICK_VIDEO_SOURCE_INVALID로 접수 전에 거절됩니다.
  • text·reference 모드에서 resolution을 보내면 APICK_VIDEO_OPTION_NOT_SUPPORTED입니다.
예시 3. 참조 이미지와 동작 영상

주체 이미지(1~6장)와 동작 참고 영상(0~4개)을 함께 첨부합니다.

요청POST/rest/kling/jobs
curl --fail-with-body --request POST 'https://apick.app/rest/kling/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'mode=reference' \
  --form 'reference_image=@./character.png' \
  --form 'reference_video=@./walk.mp4' \
  --form-string 'prompt=참조 이미지의 인물이 참조 영상처럼 걸으며 공원을 지나가는 장면' \
  --form-string 'duration=5'
  • 참조 영상은 MP4·MOV·WebM, 50MB 이하입니다.
예시 4. pro 등급 10초, 프롬프트 반영 강도 조절

프롬프트를 더 엄격히 따르게 하려면 cfg_scale을 높이고, 빼고 싶은 요소는 negative_prompt에 적습니다.

요청POST/rest/kling/jobs
curl --fail-with-body --request POST 'https://apick.app/rest/kling/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'prompt=도심 야경 속을 걷는 인물의 뒷모습, 네온 반사' \
  --form-string 'tier=pro' \
  --form-string 'duration=10' \
  --form-string 'cfg_scale=0.7' \
  --form-string 'negative_prompt=흐림, 글자, 워터마크'
  • data.point_per_second가 등급에 따라 다릅니다. 실제 예약액은 data.charged_point로 확인합니다.
예시 5. 진행 조회

접수한 job_id로 진행 상황을 조회합니다.

요청GET/rest/kling/jobs/:job_id
curl --fail-with-body --request GET "https://apick.app/rest/kling/jobs/${APICK_JOB_ID}" \
  --header "Authorization: Bearer $APICK_API_KEY"
  • data.status가 completed면 data.result_url로 MP4를 내려받고, failed면 data.error.code를 확인합니다(포인트는 환불됨).
  • waiting·processing이면 5초 뒤 다시 조회합니다. 조회는 무료입니다.

응답 처리

HTTP 성공과 업무 결과를 구분하세요. 경로별 응답 필드와 예시는 위 요청과 응답에 함께 있습니다.

응답 — 접수와 진행 조회

접수 응답과 진행 조회 응답은 같은 필드를 씁니다. 진행 조회는 5초 간격을 권장하며, status가 completed나 failed가 되면 멈춥니다. image 모드가 아니면 resolution은 null입니다.

{
  "data": {
    "job_id": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f",
    "status": "waiting",
    "model": "kling",
    "mode": "image",
    "version": "3.0",
    "tier": "std",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720P",
    "audio": true,
    "point_per_second": 410,
    "charged_point": 2050,
    "price_source": "live"
  },
  "api": { "success": true, "cost": 2050 }
}
{
  "data": {
    "job_id": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f",
    "model": "kling",
    "version": "3.0",
    "mode": "image",
    "tier": "std",
    "status": "completed",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720P",
    "audio": true,
    "point_per_second": 410,
    "charged_point": 2050,
    "result_available": true,
    "result_expires_at": "2026-10-28T12:00:00.000Z",
    "result_url": "https://apick.app/rest/kling/jobs/9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f/result",
    "created_at": "2026-10-21T11:57:00.000Z",
    "completed_at": "2026-10-21T12:00:00.000Z"
  },
  "api": { "success": true, "cost": 0 }
}
{
  "data": {
    "job_id": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f",
    "status": "failed",
    "result_available": false,
    "result_expires_at": null,
    "error": { "code": "APICK_VIDEO_GENERATION_FAILED", "message": "영상 생성에 실패했습니다. 포인트는 환불되었습니다." }
  },
  "api": { "success": true, "cost": 0 }
}
원문 응답 필드 표 보기
필드
타입
설명
data.job_id
String
작업 ID. 진행 조회·다운로드 경로에 넣습니다.
data.status
String
waiting(대기)·processing(제작 중)·completed(완료)·failed(실패, 환불됨)
data.version
String
실제로 쓴 버전
data.point_per_second
Number
적용된 초당 포인트
data.charged_point
Number
접수 때 예약 차감한 전체 포인트(duration × 초당 포인트)
data.result_available
Boolean
true면 지금 내려받을 수 있습니다.
data.result_url
String
완료 후 다운로드 주소. 인증 헤더를 붙여 요청합니다.
data.result_expires_at
String/null
다운로드 만료 시각(완료 후 7일)
data.error.code
String
실패 시 오류 코드. 사유는 data.error.message
data.idempotent_replay
Boolean
같은 idempotency_key로 이미 접수된 작업을 돌려준 경우 true(이때 api.cost는 0)

오류 코드

응답을 아래 순서로 확인하세요. 결과 유무와 과금 여부는 서로 다릅니다.

  1. HTTP 상태전송·인증·입력 오류
  2. api.successAPI 처리 여부
  3. data · result업무 결과와 오류 문구
  4. api.cost이번 요청의 과금
이 API의 오류 코드 31개
코드
HTTP
의미·조치
APICK_VIDEO_AUTH_FAILED
401
인증에 실패했습니다.
APICK_VIDEO_ACCESS_DISABLED
403
API 이용이 제한된 계정입니다.
APICK_VIDEO_PAYMENT_REQUIRED
403
최소 1회 결제 후 이용할 수 있습니다.
APICK_VIDEO_POINTS_INSUFFICIENT
402
사용 가능한 포인트가 부족합니다.
APICK_VIDEO_INVALID_REQUEST
400
요청 내용을 확인해 주세요.
APICK_VIDEO_PROMPT_REQUIRED
400
prompt를 입력해 주세요.
APICK_VIDEO_PROMPT_TOO_LONG
400
prompt는 최대 2,000자입니다.
APICK_VIDEO_MODE_INVALID
400
mode는 text, image, reference 중 하나여야 합니다.
APICK_VIDEO_MODE_NOT_SUPPORTED
400
이 모델에서는 지원하지 않는 mode입니다.
APICK_VIDEO_DURATION_INVALID
400
duration 값이 허용 범위를 벗어났습니다.
APICK_VIDEO_ASPECT_RATIO_INVALID
400
aspect_ratio 값이 허용 목록에 없습니다.
APICK_VIDEO_RESOLUTION_INVALID
400
resolution 값이 허용 목록에 없습니다.
APICK_VIDEO_TIER_INVALID
400
tier 값이 허용 목록에 없습니다.
APICK_VIDEO_VERSION_INVALID
400
지원하지 않는 영상 모델 버전입니다.
APICK_VIDEO_OPTION_NOT_SUPPORTED
400
이 모델·mode에서는 지원하지 않는 옵션입니다.
APICK_VIDEO_SOURCE_REQUIRED
400
이 mode에는 입력 파일이 필요합니다.
APICK_VIDEO_SOURCE_TOO_MANY
400
입력 파일 개수가 허용 범위를 초과했습니다.
APICK_VIDEO_SOURCE_INVALID
400
입력 파일 형식이나 크기를 확인해 주세요.
APICK_VIDEO_IDEMPOTENCY_CONFLICT
409
같은 idempotency_key에 다른 요청을 사용할 수 없습니다.
APICK_VIDEO_TOO_MANY_ACTIVE_JOBS
429
동시에 진행할 수 있는 작업 수를 초과했습니다.
APICK_VIDEO_CONTENT_REJECTED
422
요청한 영상을 생성할 수 없습니다. 프롬프트나 입력 파일을 확인해 주세요.
APICK_VIDEO_RATE_LIMITED
429
현재 요청이 많습니다. 잠시 후 다시 시도해 주세요.
APICK_VIDEO_TEMPORARILY_UNAVAILABLE
503
현재 영상 서비스를 이용할 수 없습니다. 잠시 후 다시 시도해 주세요.
APICK_VIDEO_TIMEOUT
408
처리 시간이 초과됐습니다. 포인트는 환불되었습니다.
APICK_VIDEO_GENERATION_FAILED
500
영상 생성에 실패했습니다. 포인트는 환불되었습니다.
APICK_VIDEO_JOB_NOT_FOUND
404
작업을 찾을 수 없습니다.
APICK_VIDEO_JOB_CONFLICT
409
현재 작업 상태에서는 요청을 처리할 수 없습니다.
APICK_VIDEO_RESULT_EXPIRED
410
결과 보관 기간이 만료되었습니다.
APICK_VIDEO_RESULT_INVALID
502
생성 결과를 확인할 수 없습니다.
APICK_VIDEO_BILLING_FAILED
424
결제 원장을 완료하지 못했습니다.
APICK_VIDEO_INTERNAL_ERROR
500
영상 서비스 내부 오류가 발생했습니다.
서비스 코드·조건

오류 대처

코드
대처
APICK_VIDEO_SOURCE_INVALID
이미지가 PNG·JPEG, 10MB 이하, 300~8,192px, 종횡비 0.4~2.5인지 확인하세요.
APICK_VIDEO_OPTION_NOT_SUPPORTED
image 모드가 아닌데 resolution을 보냈거나, 선택한 버전·모드에서 지원하지 않는 옵션입니다.
APICK_VIDEO_CONTENT_REJECTED
프롬프트·입력 파일·생성된 오디오가 정책(저작권·안전) 검수에서 거부됐습니다. 예약 포인트는 환불됩니다. 표현을 바꾸거나, 오디오 때문이라면 audio=false로 다시 접수하세요(지원 버전).
APICK_VIDEO_TOO_MANY_ACTIVE_JOBS
동시에 진행할 수 있는 작업 수를 넘었습니다. 진행 중인 작업이 끝난 뒤 접수하세요.
APICK_VIDEO_IDEMPOTENCY_CONFLICT
같은 idempotency_key로 다른 내용을 보냈습니다. 새 작업에는 새 키를 쓰세요.
APICK_VIDEO_TIMEOUT · APICK_VIDEO_GENERATION_FAILED
포인트는 환불됐습니다. 같은 내용으로 다시 접수할 수 있으며, 새 접수는 다시 예약 차감됩니다.
APICK_VIDEO_RATE_LIMITED · APICK_VIDEO_TEMPORARILY_UNAVAILABLE
접수되지 않았습니다. Retry-After 헤더가 있으면 그 시간 뒤에 다시 보내세요.
폼 입력 오류 error.code
코드
HTTP
의미·조치
FORM_DATA_INVALID
400
필드 이름·값의 타입·배열 인덱스를 확인하세요. 인덱스는 0부터 연속으로 사용합니다.
FORM_DATA_FIELD_CONFLICT
400
같은 값과 중첩 경로를 동시에 지정하지 마세요.
MULTIPART_LIMIT_OR_PARSE_ERROR
400·413
boundary·파일 크기·필드 개수를 확인하세요. 서비스별 제한이 우선 적용됩니다.

요금·이용 조건

기본 요금초당 std 410P·pro 550P무료 포인트로는 이용할 수 없으며 최소 1회 결제 후 이용할 수 있습니다.

실제 차감 금액은 응답의 api.cost로 확인하세요. 상세 요금은 요금정책에서 볼 수 있습니다.

연동 팁

  • 요청 예제의 오류 처리 포함 모드는 시간 제한과 업무 실패 판정을 함께 보여줍니다.
  • 인증키는 서버 환경변수에 두고 브라우저·앱에 넣지 마세요.
  • HTTP 성공과 업무 결과를 구분하고, 실패 응답의 오류 문구를 그대로 기록하세요.
추가 예제·서비스별 연동 안내

호출 예시

같은 요청을 JavaScript와 Python으로 옮긴 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다.

JavaScript 예시
Python 예시

개발가이드 검색

API 이름·경로·파라미터·오류 코드로 찾을 수 있습니다.

표시 가격은 기본 단가입니다. 상세 과금 조건은 각 가이드에서 확인하세요.