Kling 4.0 | BeatAPI API Documentation

텍스트, 시간순 프레임, 또는 참조 이미지·영상·음성과 이름 있는 요소로 생성 오디오가 포함된 720p 또는 1080p의 3~30초 영상을 생성합니다. 초 단위로 과금됩니다.

비동기: 생성 호출은 작업 ID를 반환하며, 작업이 성공하면 영상이 준비됩니다.
네 가지 입력 방식: 텍스트만, 프레임(시간순 images), 참조 이미지·영상·음성, 이름 있는 elements 최대 7개. 프레임은 참조나 요소와 함께 쓸 수 없습니다.
프롬프트에서 모든 입력을 지칭하세요: @image_1, @video_1, @voice_1, @ + 요소 이름, @first_frame, @keyframe_1, @last_frame. 모든 @는 같은 요청의 입력을 가리켜야 합니다.
오디오는 항상 생성됩니다. keep_original_sound를 쓰면 대신 참조 영상의 원래 소리를 유지합니다.
duration은 3~30초(기본값 5)이며, 720p(기본값) 또는 1080p로 렌더링합니다. 선택한 해상도에서 초 단위로 과금되며, 실패한 작업은 비용이 들지 않습니다.

POST/v1/videos/tasks실행해 보기

API Explorer에서 이 모델을 엽니다. BeatAPI API 키를 입력해 작업을 만드세요. 실제 호출이며 본인 잔액에서 과금됩니다.

모델 ID

Kling 생성 모델 두 개가 이 엔드포인트를 함께 씁니다. 아래 값은 게이트웨이 계약에서 그대로 가져왔으며, 참조 입력, 세 장 이상의 프레임, 최대 7개의 요소는 Kling 4.0만 받습니다.

모델 ID	`duration` (s)	`resolution`	최대 프레임 수	최대 참조 이미지 수	최대 요소 수	이럴 때 선택하세요
`kling-v4`	3–30	`720p`, `1080p`	10	10	7	최대 30초, 참조 이미지·영상·음성, 중간 프레임, 또는 요소가 3개보다 많이 필요한 경우.
`kling-v3`	3–15	`std`, `pro`	2	—	3	멀티샷 스토리보드, 소리 없는 영상, 또는 더 낮은 초당 가격이 필요한 경우.

엔드포인트와 인증

POST https://api.beatapi.io/v1/videos/tasks

`Authorization` string 필수

BeatAPI API 키를 Bearer <BEATAPI_API_KEY>로 보내세요. 키는 대시보드에서 만듭니다. 키는 서버에 보관하고, 브라우저나 모바일 앱에 포함하지 마세요.

본문은 Content-Type: application/json과 함께 JSON으로 보냅니다. Idempotency-Key는 선택 사항입니다. 논리적 요청마다 고유한 값(최대 255자)을 보내고, 완전히 같은 본문을 재시도할 때만 다시 사용하세요. 24시간 안에 같은 키와 본문으로 재시도하면 첫 응답을 Idempotent-Replayed: true와 함께 다시 반환하고, 같은 키에 다른 본문을 보내면 409 idempotency_conflict를 반환합니다. 2xx 이외의 응답은 저장되지 않으므로 400이나 402 이후의 재시도는 다시 실행됩니다.

요청 처리 방식

작업 만들기

아래 파라미터를 엔드포인트로 POST하세요. 201은 작업이 접수되었고 가격만큼 잔액이 보류되었다는 뜻이며, 작업은 백그라운드에서 실행됩니다. data.id를 저장하세요.

완료 기다리기

status가 succeeded 또는 failed가 될 때까지 GET /v1/tasks/{task_id}를 호출하고, 호출 사이에 data.poll_after_seconds만큼 기다리세요(이미지 5초, 영상 8초). 또는 task.succeeded와 task.failed에 대한 웹훅을 등록하세요. 처리 시간 초과로 중단된 작업은 이벤트를 보내지 않으므로 폴링은 대비책으로 유지하세요.

결과 저장하기

succeeded이면 모든 data.output.media[].url을 다운로드해 필요한 파일을 저장하세요. BeatAPI는 결과 URL을 얼마 동안 사용할 수 있는지 보장하지 않습니다. failed이면 data.error_code와 data.error_message를 확인하세요. 보류된 금액은 잔액으로 돌아왔으며, data.retryable은 같은 요청을 다시 보내면 성공할 수 있는지 알려 줍니다.

입력 모드

모드	필수 입력	참고
텍스트로 영상 생성	`model`, `prompt`	미디어를 보내지 않습니다. `aspect_ratio`가 없으면 영상은 16:9입니다.
첫 프레임	`model`, `prompt`, `images`(링크 1개)	이미지에서 영상이 시작되며 이미지의 모양을 따릅니다.
첫 프레임과 마지막 프레임	`model`, `prompt`, `images`(링크 2개)	`images[0]`은 첫 프레임, `images[1]`은 마지막 프레임입니다.
프레임	`model`, `prompt`, `images`(링크 3~10개)	시간순으로 첫 프레임, 중간 프레임, 마지막 프레임. 이미지는 영상 초 수보다 최대 한 장 더 보낼 수 있습니다.
참조와 요소	`model`, `prompt`, 그리고 `reference_images`, `reference_videos`, `reference_audios`, `elements` 중 아무것이나	아래 제한 안에서 자유롭게 조합할 수 있습니다. `images`와 함께 쓸 수 없습니다. 프롬프트에서 각 입력을 지칭하세요.

요청 파라미터

`model` string 필수

실행할 모델입니다.

값: kling-v4

값이 잘못된 경우

누락: "model" is required
이 엔드포인트에 이미지 모델을 보낸 경우: "model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint

`prompt` string 필수

영상에서 일어나는 일: 피사체, 동작, 카메라 움직임, 스타일, 소리. 각 입력은 @ 멘션으로 지칭합니다.

길이: 1–5000자

길이는 문자 수로 계산합니다(한중일 문자 하나는 1자).
멘션: reference_images는 @image_1, @image_2 …, reference_videos는 @video_1 …, reference_audios는 @voice_1 …이며, 요소는 @ 뒤에 name을 붙입니다. 프레임은 @first_frame, @keyframe_1, @keyframe_2 …, @last_frame입니다.
모든 @는 같은 요청의 입력을 가리켜야 합니다. 참조 이미지가 두 장인데 @image_3을 쓰거나 이미지가 한 장인데 @last_frame을 쓰는 등, 대응하는 입력이 없는 번호·프레임 멘션은 작업 생성 시 거부됩니다.

값이 잘못된 경우

누락: "prompt" is required
비어 있거나 한도보다 긴 경우: "prompt" has an unsupported length
요청에 없는 입력을 가리키는 멘션: the prompt names @image_3, which this request does not send

`images` string[] 선택

시간순 프레임: 링크 하나는 첫 프레임, 두 개는 첫 프레임과 마지막 프레임이며, 더 보내면 그 사이에 중간 프레임이 추가됩니다.

항목 수: 1–10
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

링크가 셋 이상이면 images[0]이 첫 프레임, 마지막 링크가 마지막 프레임이고, 그 사이의 링크는 중간 프레임입니다. 즉 images[1]은 @keyframe_1, images[2]는 @keyframe_2입니다.
영상에는 초 수보다 최대 한 장 많은 이미지를 넣을 수 있으며(duration + 1, duration을 생략하면 5초로 계산), 10장을 넘을 수 없습니다.
프레임은 reference_images, reference_videos, reference_audios, elements, aspect_ratio와 함께 보낼 수 없습니다. 영상은 첫 프레임의 모양을 따릅니다.

값이 잘못된 경우

링크가 10개 초과: "images" accepts at most 10 items
링크가 duration + 1개보다 많은 경우(여기서는 5초 영상에 링크 7개): Kling V4 takes at most 6 images for a 5-second video
reference_* 필드와 함께 보낸 경우: Cannot combine "images" with reference inputs in one task
elements와 함께 보낸 경우: Kling V4 cannot combine elements with images
aspect_ratio와 함께 보낸 경우: Kling V4 takes the first frame's shape; do not send aspect_ratio with images
https:// 링크가 아닌 경우: "images[0]" must be a public HTTPS URL

`reference_images` string[] 선택

영상의 내용, 인물, 제품, 스타일을 안내하는 이미지입니다. 프롬프트에서는 목록 순서대로 @image_1, @image_2 …로 지칭하세요.

항목 수: 1–10
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

images와 함께 쓸 수 없습니다.
참조 입력과 요소를 합쳐 15개 제한에 포함됩니다.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_images" accepts at most 10 items
참조 입력과 요소를 합쳐 15개 초과: Kling V4 takes at most 15 reference inputs and elements together

`reference_videos` string[] 선택

움직임, 카메라 워크, 내용을 가져올 영상입니다. 프롬프트에서는 목록 순서대로 @video_1, @video_2 …로 지칭하세요.

항목 수: 1–5
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

클립마다 2~30초, 모든 클립 합계 최대 30초입니다. 게이트웨이는 작업 생성 전에 각 클립을 측정하고, 제한을 벗어난 클립은 해당 클립을 명시해 거부합니다.
참조 영상과 영상 요소는 합쳐서 최대 5개이며, 참조 입력과 요소의 15개 제한에 포함됩니다.
keep_original_sound: true를 보내지 않으면 완성된 영상에는 생성 오디오가 들어가며, 보내면 참조 영상의 원래 소리를 유지합니다.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_videos" accepts at most 5 items
2초보다 짧거나 30초보다 긴 클립: reference_videos[0] is 35 seconds long; this model takes reference video of 2 to 30 seconds.
합계가 30초를 넘는 클립: The reference videos run 36 seconds in total; this model takes at most 30.
참조 영상과 영상 요소 합계 5개 초과: Kling V4 takes at most 5 reference videos and video elements together

`reference_audios` string[] 선택

영상에 쓸 음성입니다. 프롬프트에서는 목록 순서대로 @voice_1, @voice_2 …로 지칭하세요.

항목 수: 1–3
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

images와 함께 쓸 수 없습니다.
참조 입력과 요소를 합쳐 15개 제한에 포함됩니다.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_audios" accepts at most 3 items

`elements` object[] 선택

인물, 동물, 소품, 의상, 장면, 이펙트 같은 이름 있는 피사체를 최대 7개까지 둘 수 있습니다. 각각 한 번 정의하고 프롬프트에서 @ 뒤에 name을 붙여 지칭합니다.

항목 수: 7개 이하

객체를 최대 7개까지 담은 배열입니다. 각 객체는 다음 키만 받습니다.
elements[].name(string, 필수): 영문자, 숫자, 밑줄 또는 한자 1~20자이며, 요청 안에서 대소문자 구분 없이 고유해야 합니다. image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame, last_frame은 쓸 수 없습니다.
elements[].element_input_urls(문자열 배열): 요소 이미지의 공개 HTTPS 링크 2~4개. 첫 번째가 대표 이미지입니다.
elements[].element_input_video_urls(문자열 배열): 인물이 나오는 3~8초 단일 샷 영상의 공개 HTTPS 링크 정확히 하나. 이것과 element_input_urls 중 하나만 보내세요.
elements[].element_input_audio_urls(문자열 배열, 선택): 인물 요소의 음성인 공개 HTTPS 오디오 링크 정확히 하나.
elements[].tag(string, 선택): 요소의 종류. 영상 요소나 음성이 있는 요소는 인물이어야 하므로 tag를 생략하거나 character를 보내세요.
elements[].description(string, 선택): 요소에 대한 설명, 최대 100자.
영상 요소는 최대 3개, reference_videos와 합쳐 최대 5개입니다. 모든 요소는 참조 입력과 요소의 15개 제한에 포함됩니다.
요소는 images와 함께 보낼 수 없습니다.

값이 잘못된 경우

요소가 7개 초과: "elements" accepts at most 7 items
객체가 아닌 요소: "elements[0]" must be an object
name이 없는 요소: "name" is required in "elements[0]"
비어 있거나 20자보다 긴 name: "elements[0].name" has an unsupported length
다른 문자가 들어 있거나 예약된 이름인 name: elements[0].name "image_1" is not a name Kling V4 accepts
대소문자를 무시하면 같은 name이 두 번: elements[1].name "Hero" is used twice
이미지와 영상이 모두 있거나 둘 다 없음: elements[0] takes either element_input_urls or element_input_video_urls
이미지가 두 장 미만: "elements[0].element_input_urls" requires at least 2 item
이미지가 네 장 초과: "elements[0].element_input_urls" accepts at most 4 items
tag가 character가 아닌 영상 요소: elements[0] is a video element, which is always a character
tag가 character가 아닌 요소에 음성: elements[0] has a voice, which only a character element takes
목록에 없는 tag: "elements[0].tag" must be one of: [character animal prop costume scene effect others]
100자보다 긴 description: "elements[0].description" has an unsupported length
요소가 받지 않는 키: field "start_time" is not supported in "elements[0]"
영상 요소가 3개 초과: Kling V4 takes at most 3 video elements
images와 함께 보낸 경우: Kling V4 cannot combine elements with images

`duration` integer 선택기본값: `5`

영상 길이(초)이며 정수입니다. 이 값으로 과금됩니다.

기본값: 5
범위: 3–30

생략하면 5가 사용되어 과금됩니다.
프레임을 쓸 때는 이미지 수의 상한도 정합니다. 최대 duration + 1장이며 10장을 넘을 수 없습니다.

값이 잘못된 경우

범위 밖, 정수가 아님, 또는 문자열로 보낸 경우: "duration" is outside its supported range

`aspect_ratio` string 선택기본값: `16:9`

가로:세로로 나타낸 영상 모양입니다.

허용 값: 16:9, 9:16, 1:1, 21:9
기본값: 16:9

생략하면 16:9가 사용됩니다.
images와 함께 보내지 마세요. 영상은 첫 프레임의 모양을 따릅니다.

값이 잘못된 경우

목록에 없는 값: "aspect_ratio" must be one of: [16:9 9:16 1:1 21:9]
images와 함께 보낸 경우: Kling V4 takes the first frame's shape; do not send aspect_ratio with images

`resolution` string 선택기본값: `720p`

출력 해상도입니다. 1080p는 720p보다 초당 가격이 높습니다.

허용 값: 720p, 1080p
기본값: 720p

생략하면 720p가 사용되어 과금됩니다.
이 모델에서는 4K를 사용할 수 없습니다.

값이 잘못된 경우

목록에 없는 값(예: 4K 또는 pro): "resolution" must be one of: [720p 1080p]

`keep_original_sound` boolean 선택

완성된 영상에 생성 오디오 대신 참조 영상의 원래 소리를 유지합니다.

reference_videos가 있을 때만 유효합니다. 없이 보내면 false라도 거부됩니다.
이 필드가 없으면 영상에 생성 오디오가 들어갑니다. 오디오를 끄는 필드는 없습니다.

값이 잘못된 경우

true나 false가 아닌 경우: "keep_original_sound" must be a boolean
reference_videos 없이 보낸 경우: "keep_original_sound" needs reference_videos

게이트웨이는 작업을 만들기 전에 다음 조합도 검사합니다.

images는 참조 입력과 함께 쓸 수 없습니다
images는 시간순 프레임입니다. 하나는 첫 프레임, 두 개는 첫 프레임과 마지막 프레임이며, 더 보내면 그 사이에 중간 프레임이 추가됩니다. 프롬프트에서는 @first_frame, @keyframe_1, @keyframe_2 …, @last_frame으로 지칭합니다
영상에는 초 수보다 최대 한 장 많은 이미지를 넣을 수 있으며, 10장을 넘을 수 없습니다
프롬프트에서 reference_images는 @image_1, @image_2 …, reference_videos는 @video_1 …, reference_audios는 @voice_1 …, elements는 @ 뒤에 이름을 붙여 지칭합니다. 프롬프트의 모든 @는 같은 요청의 입력을 가리켜야 합니다
참조 영상은 각각 2-30초, 합계 30초입니다. 참조 영상과 영상 요소는 합쳐서 최대 5개, 영상 요소는 최대 3개이며, reference_images, reference_videos, reference_audios, elements는 합쳐서 최대 15개입니다
요소는 element_input_urls의 이미지 2-4장(첫 번째가 대표 이미지) 또는 element_input_video_urls의 3-8초 단일 샷 인물 영상 하나입니다. element_input_audio_urls로 인물 요소에 음성을 지정합니다
요소 이름은 영문자, 숫자, 밑줄 또는 한자 1-20자이며, 대소문자 구분 없이 고유해야 하고 image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame, last_frame은 쓸 수 없습니다
elements와 aspect_ratio는 images와 함께 보낼 수 없습니다. 출력은 첫 프레임의 모양을 따르며, images가 없으면 aspect_ratio 기본값은 16:9입니다
keep_original_sound는 참조 영상의 원래 오디오를 유지하며 reference_videos가 필요합니다. 그렇지 않으면 영상에 생성 오디오가 들어갑니다

입력 미디어 제한

게이트웨이는 작업을 만들기 전에 모든 입력을 읽고, 아래 제한을 벗어난 입력은 해당 입력을 명시한 400 bad_request로 거부합니다. 과금되지 않습니다.

미디어	작업 생성 전에 검사하는 제한
이미지	가로·세로 300–65536 px, 화면비(가로 ÷ 세로) 0.4–2.5
영상	각각 2–30초, 합계 30초

게이트웨이는 작업 생성 전에 images, reference_images, reference_videos를 측정하고, 제한을 벗어난 입력은 목록과 위치를 명시한 메시지로 거부합니다(예: reference_videos[0] is 35 seconds long; this model takes reference video of 2 to 30 seconds.). 비용은 청구되지 않습니다.
요소 링크와 reference_audios는 작업 생성 전에 공개 HTTPS 링크인지만 검사합니다. 요소 영상은 3~8초여야 합니다.
로컬 파일이 있다면 POST /v1/files로 업로드하고 반환된 data.url을 전달하세요.

프롬프트 멘션

입력 종류마다 고유한 멘션이 있으며, 목록 순서대로 1부터 번호를 매깁니다.

멘션	대상	사용 조건
`@image_1`, `@image_2` …	`reference_images`	참조 이미지를 그 수 이상 보낸 경우
`@video_1`, `@video_2` …	`reference_videos`	참조 영상을 그 수 이상 보낸 경우
`@voice_1`, `@voice_2` …	`reference_audios`	참조 오디오 링크를 그 수 이상 보낸 경우
`@` + 요소 이름	해당 `name`을 가진 요소	요소가 `elements`에 있는 경우
`@first_frame`	`images[0]`	이미지를 하나 이상 보낸 경우
`@keyframe_1`, `@keyframe_2` …	`images[1]`부터의 중간 프레임	이미지를 셋 이상 보낸 경우
`@last_frame`	`images`의 마지막 링크	이미지를 둘 이상 보낸 경우

대응하는 입력이 없는 번호·프레임 멘션은 작업 생성 시 거부됩니다(예: the prompt names @last_frame, which this request does not send).

조합 규칙

작업 생성 시 검사하며, 위반한 요청은 400 bad_request로 거부되고 비용이 들지 않습니다.

규칙	메시지
`reference_*` 필드와 함께 보낸 `images`	`Cannot combine "images" with reference inputs in one task`
`elements`와 함께 보낸 `images`	`Kling V4 cannot combine elements with images`
`aspect_ratio`와 함께 보낸 `images`	`Kling V4 takes the first frame's shape; do not send aspect_ratio with images`
이미지가 `duration` + 1장보다 많음(여기서는 5초 영상)	`Kling V4 takes at most 6 images for a 5-second video`
`reference_videos` 없는 `keep_original_sound`	`"keep_original_sound" needs reference_videos`
영상 요소가 3개 초과	`Kling V4 takes at most 3 video elements`
참조 영상과 영상 요소 합계 5개 초과	`Kling V4 takes at most 5 reference videos and video elements together`
참조 이미지, 영상, 오디오 링크, 요소 합계 15개 초과	`Kling V4 takes at most 15 reference inputs and elements together`

이 모델이 받지 않는 필드

다음 필드를 보내면 무시되지 않고 과금 전에 거부됩니다.

sound, generate_audio, seed, multi_shots, multi_prompt, quality, watermark, task_type, output_format → field "sound" is not supported by model kling-v4(보낸 필드 포함).
그 밖의 알 수 없는 필드 → unknown field: <name>.

요청 예시

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections, a low ambient synth tone",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

텍스트로 영상 생성

생성 오디오가 포함된 720p 16:9 5초 클립입니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections, a low ambient synth tone",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

첫 프레임과 마지막 프레임

1080p로 첫 번째 이미지에서 두 번째 이미지로 이어지며, 첫 프레임의 모양을 따릅니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "The camera moves from the bottle in @first_frame to the singer on a neon stage in @last_frame in one continuous shot",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "resolution": "1080p"
}'

참조 이미지와 음성

참조 이미지 두 장과 음성 하나이며, 각각 프롬프트에서 지칭합니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "The singer from @image_1 lifts the bottle from @image_2 toward the camera and says a short line in the voice of @voice_1",
  "reference_images": [
    "https://cdn.beatapi.io/samples/neon-singer.png",
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "reference_audios": [
    "https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
  ],
  "duration": 8,
  "aspect_ratio": "9:16",
  "resolution": "720p"
}'

원래 소리를 유지하는 참조 영상

자리 표시자를 직접 준비한 2~30초 클립으로 바꾸세요. keep_original_sound는 생성 오디오 대신 원래 소리를 유지합니다.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "Restyle @video_1 as a neon-lit night scene and keep its camera movement",
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "keep_original_sound": true,
  "duration": 10,
  "resolution": "720p"
}'

이름 있는 요소

인물과 소품을 각각 이미지 두 장(첫 번째가 대표 이미지)으로 정의합니다. 자리 표시자 링크를 직접 준비한 이미지로 바꾸세요.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "@singer walks across a neon stage holding @bottle and smiles at the camera",
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "elements": [
    {
      "name": "singer",
      "tag": "character",
      "description": "A performer in a silver jacket",
      "element_input_urls": [
        "https://your-cdn.example.com/elements/singer-front.png",
        "https://your-cdn.example.com/elements/singer-side.png"
      ]
    },
    {
      "name": "bottle",
      "tag": "prop",
      "element_input_urls": [
        "https://your-cdn.example.com/elements/bottle-front.png",
        "https://your-cdn.example.com/elements/bottle-back.png"
      ]
    }
  ]
}'

응답

작업 생성(201)

작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-v4",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v4",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.75,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.75,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

필드	타입	설명
`data.id`	`string`	작업 ID: `task_` 뒤에 영문자와 숫자 32자가 붙습니다. 폴링과 웹훅 이벤트 매칭에 사용합니다.
`data.object`	`string`	항상 `task`.
`data.task_kind`	`string`	`image` 또는 `video`.
`data.capability_id`	`string`	보낸 모델 ID입니다.
`data.capability_version`	`integer`	모델의 계약 버전으로, 현재 `1`입니다.
`data.media_type`	`string`	`image` 또는 `video`.
`data.model`	`string`	보낸 모델 ID입니다(`capability_id`와 같음).
`data.status`	`string`	`queued`, `processing`, `succeeded` 또는 `failed`. 마지막 두 개만 최종 상태입니다.
`data.stage`	`string`	`status`와 같은 값으로, 오래된 클라이언트를 위해 유지합니다.
`data.created_at`	`integer`	작업 생성 시각(Unix 초)입니다.
`data.updated_at`	`integer`	마지막 변경 시각(Unix 초)입니다.
`data.completed_at`	`integer \| null`	작업 완료 시각(Unix 초)입니다. 실행 중에는 `null`입니다.
`data.poll_after_seconds`	`integer`	실행 중: 다음 폴링까지 기다릴 시간입니다(이미지 5, 영상 8).
`data.typical_seconds`	`object`	실행 중이며 최근 작업이 충분할 때: 최근 `window` 동안 `samples`개 작업의 `p50` 및 `p90` 완료 시간(초)입니다.
`data.output`	`object \| null`	결과입니다. `status`가 `succeeded`가 될 때까지 `null`입니다. 아래 출력 필드를 참고하세요.
`data.usage.credits_reserved`	`number`	작업 생성 시 잔액에서 보류한 USD 금액입니다.
`data.usage.credits_charged`	`number`	이 작업의 비용(USD)입니다. 실패한 작업에서는 `0`입니다.
`data.usage.credits_settled`	`number`	최종 청구 금액(USD)입니다. 작업이 성공하면 설정되고, 그렇지 않으면 `0`입니다.
`data.usage.credits_refunded`	`number`	잔액으로 환불된 금액(USD)입니다. 실패한 작업에서는 환불이 기록되면 보류 금액과 같아집니다.
`data.usage.billable_duration_seconds`	`integer`	영상만 해당: 가격 산정의 기준이 되는 초입니다. 모델이 길이를 보고하지 않으면 없습니다.
`data.request_id`	`string`	요청 ID입니다. 지원팀에 문의할 때 함께 알려 주세요.
`data.error_code`	`string \| null`	실패 코드입니다. 작업이 실패하지 않았다면 `null`입니다.
`data.error_message`	`string \| null`	무엇이 잘못되었고 무엇을 바꿔야 하는지 설명합니다. 작업이 실패하지 않았다면 `null`입니다.

완료된 작업

GET /v1/tasks/{task_id}는 HTTP 200과 함께 status: "succeeded", 그리고 data.output에 결과를 반환합니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-v4",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v4",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 0.75,
      "credits_settled": 0.75,
      "credits_refunded": 0,
      "credits_charged": 0.75,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

출력 필드

필드	타입	설명
`output.media`	`object[]`	생성된 파일입니다. 이 모델은 영상 하나를 만듭니다.
`output.media[].type`	`string`	항상 `video`.
`output.media[].url`	`string`	저장된 영상의 HTTPS 링크입니다. 내려받아 보관하세요. 보관 기간은 보장하지 않습니다.
`output.media[].mime_type`	`string`	파일의 미디어 형식이며 보통 `video/mp4`입니다.
`output.r2_url`	`string`	이전 클라이언트를 위해 다시 넣은 영상 URL입니다. 대신 `media`를 읽으세요.

실패한 작업

실패한 작업도 GET /v1/tasks/{task_id}에서는 HTTP 200입니다. 실패 정보는 본문에 있습니다. 보류 금액이 전액 환불되므로 과금되지 않습니다.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-v4",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v4",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.75,
      "credits_settled": 0,
      "credits_refunded": 0.75,
      "credits_charged": 0,
      "billable_duration_seconds": 5
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

필드	타입	설명
`data.error_code`	`string`	`bad_request`, `content_policy_violation`(요청 수정 필요) 또는 `processing_unavailable`, `processing_timeout`, `processing_failed`, `result_transfer_failed`(나중에 재시도) 중 하나입니다. 오류를 참고하세요.
`data.error_message`	`string`	문제와 해결 방법을 설명하는 문장입니다.
`data.retryable`	`boolean`	실패한 작업에만 있습니다. 같은 요청을 다시 보내면 성공할 수 있을 때 `true`입니다.
`data.usage`	`object`	환불이 기록되면(보통 작업이 실패하는 시점): `credits_charged`와 `credits_settled`는 `0`이고, `credits_refunded`는 `credits_reserved`와 같습니다.

전체 예시

작업을 만들고, 서버의 폴링 안내에 따라 기다린 뒤 결과 URL을 출력합니다. 환경 변수에 BEATAPI_API_KEY를 설정하고 requests를 설치하세요.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "kling-v4",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections, a low ambient synth tone",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

과금

가격은 선택한 해상도의 영상 초당 요금입니다. 720p는 초당 $0.15, `1080p`는 초당$ 0.23입니다. 아래 목록은 8초 클립 기준입니다.
초 수는 duration이며, 생략하면 5입니다. 작업의 usage.billable_duration_seconds에 표시됩니다.
영상 입력(reference_videos 또는 영상으로 만든 요소)이 있으면 요금은 720p 초당 $0.09, `1080p` 초당$ 0.14이며, 출력 초 수에 입력 영상 초 수를 더한 값으로 과금되고 출력 초 수의 두 배보다 적게 과금되지 않습니다. 영상 요소는 각각 8초로 계산합니다. keep_original_sound에는 reference_videos가 필요하므로 항상 이 방식으로 과금됩니다. 아래 영상 입력 행은 8초 참조로 만든 8초 클립 기준입니다.
모든 영상에는 생성되었거나 참조 영상에서 유지된 오디오가 별도 요금 없이 포함됩니다.
가격은 작업 생성 시 보류되고 영상이 준비되면 정산됩니다. 실패한 작업은 제출 후 콘텐츠 검수에서 거부된 경우를 포함해 전액 환불됩니다.

현재 정가이며 가격 페이지와 같습니다. 별도 할인 계약이 있는 계정은 더 적게 지불하며, 실제 청구 금액은 항상 작업의 data.usage에서 확인할 수 있습니다.

옵션	정가(USD)
8초 · 720p	$1.2
8초 · 720p · 영상 입력 포함 · 8초 참조	$1.44
8초 · 1080p	$1.84
8초 · 1080p · 영상 입력 포함 · 8초 참조	$2.24

자주 발생하는 오류

오류 또는 증상	원인	해결 방법
400 `the prompt names @image_3, which this request does not send`	요청에 없는 입력을 가리키는 멘션이 있습니다(예: 참조 이미지를 두 장 보냈는데 세 번째를 지칭).	모든 `@`를 같은 요청의 입력과 맞추세요. 번호는 목록 순서대로 1부터입니다.
400 `Cannot combine "images" with reference inputs in one task`	`images`의 프레임을 `reference_images`, `reference_videos` 또는 `reference_audios`와 함께 보냈습니다.	프레임과 참조 중 하나만 사용하세요. 프레임이 아니라 영상을 안내할 이미지는 `reference_images`에 넣으세요.
400 `Kling V4 cannot combine elements with images`	프레임과 함께 `elements`를 보냈습니다.	`images`를 삭제하거나 `elements`를 삭제하세요.
400 `Kling V4 takes the first frame's shape; do not send aspect_ratio with images`	프레임과 함께 `aspect_ratio`를 보냈습니다.	`aspect_ratio`를 삭제하고 첫 프레임을 원하는 모양으로 자르세요.
400 `Kling V4 takes at most 6 images for a 5-second video`	프레임이 `duration` + 1장보다 많습니다.	프레임 수를 줄이거나 `duration`을 늘리세요. 어떤 경우든 프레임은 최대 10장입니다.
400 `elements[0] takes either element_input_urls or element_input_video_urls`	요소에 이미지와 영상이 모두 있거나 둘 다 없습니다.	요소마다 이미지 2~4장 또는 인물 영상 하나를 지정하세요.
400 `"elements[0].element_input_urls" requires at least 2 item`	요소에 이미지가 한 장뿐입니다.	요소 이미지를 2~4장 보내세요. 대표 이미지가 첫 번째입니다.
400 `elements[0].name "image_1" is not a name Kling V4 accepts`	이름에 영문자, 숫자, 밑줄, 한자 이외의 문자가 있거나 `image_1`, `first_frame` 같은 예약된 이름입니다.	요소 이름을 바꾸고(예: `singer`, `hero_bottle`) 그 이름으로 지칭하세요.
400 `"keep_original_sound" needs reference_videos`	`reference_videos` 없이 `keep_original_sound`를 보냈습니다.	삭제하거나, 소리를 유지할 참조 영상을 추가하세요.
400 `reference_videos[0] is 35 seconds long; this model takes reference video of 2 to 30 seconds.`	참조 클립이 2초보다 짧거나 30초보다 깁니다. 모든 클립 합계는 최대 30초입니다.	필요한 부분만 남도록 클립을 자르세요.
400 `field "sound" is not supported by model kling-v4`	오디오는 항상 생성되며 사운드 스위치는 없습니다(`generate_audio`, `seed`, `multi_shots`도 거부됨).	해당 필드를 삭제하세요. 참조 영상의 원래 소리를 유지하려면 `keep_original_sound: true`를 보내세요.
400 `"resolution" must be one of: [720p 1080p]`	`4K` 또는 `pro` 같은 등급 이름을 보냈습니다.	`720p` 또는 `1080p`를 보내세요.
400 `"duration" is outside its supported range`	3~30 사이의 정수가 아니거나 문자열로 보냈습니다.	`5` 같은 정수를 보내세요.
작업이 `content_policy_violation`과 함께 `failed`	프롬프트, 입력 또는 결과가 콘텐츠 검수에서 거부되었습니다.	프롬프트나 입력을 바꾸세요. 그대로 재시도하면 다시 실패하며, 비용은 청구되지 않습니다.
402 `insufficient_credits`	잔액이 이 길이와 해상도의 보류 금액보다 적습니다.	충전하거나, `duration`을 줄이거나, `720p`를 사용하세요.

HTTP 오류 요약

작업이 생성되기 전의 오류는 2xx가 아닌 응답으로 오며 과금되지 않습니다. error.code 또는 error.retryable로 분기하세요. message에 문제가 표시됩니다. 전체 목록과 재시도 정책은 오류에 있습니다.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}

HTTP 상태	`error.code`	조치
400	`bad_request`, `content_policy_violation`	요청을 수정하세요. 메시지에 해당 필드가 표시됩니다. 그대로 재시도하지 마세요.
401	`missing_api_key`, `invalid_api_key`(오래된 클라이언트에서는 `unauthorized`가 보일 수 있음)	유효한 키를 `Authorization: Bearer <key>`로 보내세요.
402	`insufficient_credits`	충전하거나 키 한도를 올린 뒤 다시 보내세요.
403	`forbidden`	이 키나 계정으로는 이 모델을 사용할 수 없습니다(예: 무료 크레딧은 일부 모델만 지원). 그대로 재시도하지 마세요.
404	`not_found`	`GET /v1/tasks/{task_id}`에서: 이 키의 계정에 해당 작업이 없습니다. ID를 확인하세요.
409	`idempotency_conflict`	새 `Idempotency-Key`를 사용하거나, 이 키를 쓴 첫 요청이 끝날 때까지 기다리세요.
429	`rate_limit_exceeded`	`Retry-After`에 표시된 시간(또는 `error.retry_after_seconds`초)만큼 기다린 뒤 재시도하세요.
500	`internal_error`	백오프를 적용해 재시도하고, 계속되면 `request_id`와 함께 지원팀에 문의하세요.
503	`processing_unavailable`, `processing_timeout`, `processing_failed`, `result_transfer_failed`	과금되지 않았습니다. 지수 백오프를 적용해 재시도하세요.

인증

AuthorizationBearer

API 키를 Authorization: Bearer <BEATAPI_API_KEY>로 보내세요.

헤더

Idempotency-Keystring선택 사항<=255 characters

요청

This endpoint expects an object.

modelenum필수

실행할 모델입니다.

값: kling-v4

값이 잘못된 경우

누락: "model" is required
이 엔드포인트에 이미지 모델을 보낸 경우: "model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint

허용된 값:

promptstring필수1-5000 characters

영상에서 일어나는 일: 피사체, 동작, 카메라 움직임, 스타일, 소리. 각 입력은 @ 멘션으로 지칭합니다.

길이: 1–5000자

길이는 문자 수로 계산합니다(한중일 문자 하나는 1자).
멘션: reference_images는 @image_1, @image_2 …, reference_videos는 @video_1 …, reference_audios는 @voice_1 …이며, 요소는 @ 뒤에 name을 붙입니다. 프레임은 @first_frame, @keyframe_1, @keyframe_2 …, @last_frame입니다.
모든 @는 같은 요청의 입력을 가리켜야 합니다. 참조 이미지가 두 장인데 @image_3을 쓰거나 이미지가 한 장인데 @last_frame을 쓰는 등, 대응하는 입력이 없는 번호·프레임 멘션은 작업 생성 시 거부됩니다.

값이 잘못된 경우

누락: "prompt" is required
비어 있거나 한도보다 긴 경우: "prompt" has an unsupported length
요청에 없는 입력을 가리키는 멘션: the prompt names @image_3, which this request does not send

aspect_ratioenum선택 사항기본값 16:9

가로:세로로 나타낸 영상 모양입니다.

허용 값: 16:9, 9:16, 1:1, 21:9

기본값: 16:9

생략하면 16:9가 사용됩니다.
images와 함께 보내지 마세요. 영상은 첫 프레임의 모양을 따릅니다.

값이 잘못된 경우

목록에 없는 값: "aspect_ratio" must be one of: [16:9 9:16 1:1 21:9]
images와 함께 보낸 경우: Kling V4 takes the first frame's shape; do not send aspect_ratio with images

허용된 값:

durationinteger선택 사항3-30기본값 5

영상 길이(초)이며 정수입니다. 이 값으로 과금됩니다.

기본값: 5

범위: 3–30

생략하면 5가 사용되어 과금됩니다.
프레임을 쓸 때는 이미지 수의 상한도 정합니다. 최대 duration + 1장이며 10장을 넘을 수 없습니다.

값이 잘못된 경우

범위 밖, 정수가 아님, 또는 문자열로 보낸 경우: "duration" is outside its supported range

elementslist of objects선택 사항

항목 수: 7개 이하

객체를 최대 7개까지 담은 배열입니다. 각 객체는 다음 키만 받습니다.
elements[].name(string, 필수): 영문자, 숫자, 밑줄 또는 한자 1~20자이며, 요청 안에서 대소문자 구분 없이 고유해야 합니다. image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame, last_frame은 쓸 수 없습니다.
elements[].element_input_urls(문자열 배열): 요소 이미지의 공개 HTTPS 링크 2~4개. 첫 번째가 대표 이미지입니다.
elements[].element_input_video_urls(문자열 배열): 인물이 나오는 3~8초 단일 샷 영상의 공개 HTTPS 링크 정확히 하나. 이것과 element_input_urls 중 하나만 보내세요.
elements[].element_input_audio_urls(문자열 배열, 선택): 인물 요소의 음성인 공개 HTTPS 오디오 링크 정확히 하나.
elements[].tag(string, 선택): 요소의 종류. 영상 요소나 음성이 있는 요소는 인물이어야 하므로 tag를 생략하거나 character를 보내세요.
elements[].description(string, 선택): 요소에 대한 설명, 최대 100자.
영상 요소는 최대 3개, reference_videos와 합쳐 최대 5개입니다. 모든 요소는 참조 입력과 요소의 15개 제한에 포함됩니다.
요소는 images와 함께 보낼 수 없습니다.

값이 잘못된 경우

요소가 7개 초과: "elements" accepts at most 7 items
객체가 아닌 요소: "elements[0]" must be an object
name이 없는 요소: "name" is required in "elements[0]"
비어 있거나 20자보다 긴 name: "elements[0].name" has an unsupported length
다른 문자가 들어 있거나 예약된 이름인 name: elements[0].name "image_1" is not a name Kling V4 accepts
대소문자를 무시하면 같은 name이 두 번: elements[1].name "Hero" is used twice
이미지와 영상이 모두 있거나 둘 다 없음: elements[0] takes either element_input_urls or element_input_video_urls
이미지가 두 장 미만: "elements[0].element_input_urls" requires at least 2 item
이미지가 네 장 초과: "elements[0].element_input_urls" accepts at most 4 items
tag가 character가 아닌 영상 요소: elements[0] is a video element, which is always a character
tag가 character가 아닌 요소에 음성: elements[0] has a voice, which only a character element takes
목록에 없는 tag: "elements[0].tag" must be one of: [character animal prop costume scene effect others]
100자보다 긴 description: "elements[0].description" has an unsupported length
요소가 받지 않는 키: field "start_time" is not supported in "elements[0]"
영상 요소가 3개 초과: Kling V4 takes at most 3 video elements
images와 함께 보낸 경우: Kling V4 cannot combine elements with images

imageslist of strings선택 사항

시간순 프레임: 링크 하나는 첫 프레임, 두 개는 첫 프레임과 마지막 프레임이며, 더 보내면 그 사이에 중간 프레임이 추가됩니다.

항목 수: 1–10

각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

링크가 셋 이상이면 images[0]이 첫 프레임, 마지막 링크가 마지막 프레임이고, 그 사이의 링크는 중간 프레임입니다. 즉 images[1]은 @keyframe_1, images[2]는 @keyframe_2입니다.
영상에는 초 수보다 최대 한 장 많은 이미지를 넣을 수 있으며(duration + 1, duration을 생략하면 5초로 계산), 10장을 넘을 수 없습니다.
프레임은 reference_images, reference_videos, reference_audios, elements, aspect_ratio와 함께 보낼 수 없습니다. 영상은 첫 프레임의 모양을 따릅니다.

값이 잘못된 경우

링크가 10개 초과: "images" accepts at most 10 items
링크가 duration + 1개보다 많은 경우(여기서는 5초 영상에 링크 7개): Kling V4 takes at most 6 images for a 5-second video
reference_* 필드와 함께 보낸 경우: Cannot combine "images" with reference inputs in one task
elements와 함께 보낸 경우: Kling V4 cannot combine elements with images
aspect_ratio와 함께 보낸 경우: Kling V4 takes the first frame's shape; do not send aspect_ratio with images
https:// 링크가 아닌 경우: "images[0]" must be a public HTTPS URL

keep_original_soundboolean선택 사항

완성된 영상에 생성 오디오 대신 참조 영상의 원래 소리를 유지합니다.

reference_videos가 있을 때만 유효합니다. 없이 보내면 false라도 거부됩니다.
이 필드가 없으면 영상에 생성 오디오가 들어갑니다. 오디오를 끄는 필드는 없습니다.

값이 잘못된 경우

true나 false가 아닌 경우: "keep_original_sound" must be a boolean
reference_videos 없이 보낸 경우: "keep_original_sound" needs reference_videos

reference_audioslist of strings선택 사항

영상에 쓸 음성입니다. 프롬프트에서는 목록 순서대로 @voice_1, @voice_2 …로 지칭하세요.

항목 수: 1–3

각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

images와 함께 쓸 수 없습니다.
참조 입력과 요소를 합쳐 15개 제한에 포함됩니다.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_audios" accepts at most 3 items

reference_imageslist of strings선택 사항

영상의 내용, 인물, 제품, 스타일을 안내하는 이미지입니다. 프롬프트에서는 목록 순서대로 @image_1, @image_2 …로 지칭하세요.

항목 수: 1–10

각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

images와 함께 쓸 수 없습니다.
참조 입력과 요소를 합쳐 15개 제한에 포함됩니다.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_images" accepts at most 10 items
참조 입력과 요소를 합쳐 15개 초과: Kling V4 takes at most 15 reference inputs and elements together

reference_videoslist of strings선택 사항

움직임, 카메라 워크, 내용을 가져올 영상입니다. 프롬프트에서는 목록 순서대로 @video_1, @video_2 …로 지칭하세요.

항목 수: 1–5

각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.

클립마다 2~30초, 모든 클립 합계 최대 30초입니다. 게이트웨이는 작업 생성 전에 각 클립을 측정하고, 제한을 벗어난 클립은 해당 클립을 명시해 거부합니다.
참조 영상과 영상 요소는 합쳐서 최대 5개이며, 참조 입력과 요소의 15개 제한에 포함됩니다.
keep_original_sound: true를 보내지 않으면 완성된 영상에는 생성 오디오가 들어가며, 보내면 참조 영상의 원래 소리를 유지합니다.

값이 잘못된 경우

최대 개수를 넘은 경우: "reference_videos" accepts at most 5 items
2초보다 짧거나 30초보다 긴 클립: reference_videos[0] is 35 seconds long; this model takes reference video of 2 to 30 seconds.
합계가 30초를 넘는 클립: The reference videos run 36 seconds in total; this model takes at most 30.
참조 영상과 영상 요소 합계 5개 초과: Kling V4 takes at most 5 reference videos and video elements together

resolutionenum선택 사항기본값 720p

출력 해상도입니다. 1080p는 720p보다 초당 가격이 높습니다.

허용 값: 720p, 1080p

기본값: 720p

생략하면 720p가 사용되어 과금됩니다.
이 모델에서는 4K를 사용할 수 없습니다.

값이 잘못된 경우

목록에 없는 값(예: 4K 또는 pro): "resolution" must be one of: [720p 1080p]

허용된 값:

응답

작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.

오류

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error

모델 ID

엔드포인트와 인증

Authorization string 필수

요청 처리 방식

작업 만들기

완료 기다리기

결과 저장하기

입력 모드

요청 파라미터

model string 필수

prompt string 필수

images string[] 선택

reference_images string[] 선택

reference_videos string[] 선택

reference_audios string[] 선택

elements object[] 선택

duration integer 선택기본값: 5

aspect_ratio string 선택기본값: 16:9

resolution string 선택기본값: 720p

keep_original_sound boolean 선택

입력 미디어 제한

프롬프트 멘션

조합 규칙

이 모델이 받지 않는 필드

요청 예시

텍스트로 영상 생성

첫 프레임과 마지막 프레임

참조 이미지와 음성

원래 소리를 유지하는 참조 영상

이름 있는 요소

응답

작업 생성(201)

완료된 작업

출력 필드

실패한 작업

전체 예시

과금

자주 발생하는 오류

HTTP 오류 요약

인증

헤더

요청

응답

오류

`Authorization` string 필수

`model` string 필수

`prompt` string 필수

`images` string[] 선택

`reference_images` string[] 선택

`reference_videos` string[] 선택

`reference_audios` string[] 선택

`elements` object[] 선택

`duration` integer 선택기본값: `5`

`aspect_ratio` string 선택기본값: `16:9`

`resolution` string 선택기본값: `720p`

`keep_original_sound` boolean 선택