Kling 3.0 | BeatAPI API Documentation

텍스트나 프레임 한두 장으로 std 또는 pro 등급의 3~15초 영상을 생성하며, 멀티샷 스토리보드와 재사용 가능한 요소를 지원합니다. 초 단위로 과금됩니다.

비동기: 생성 호출은 작업 ID를 반환하며, 작업이 성공하면 영상이 준비됩니다.
세 가지 입력 방식: 텍스트만, 첫 프레임, 또는 첫 프레임과 마지막 프레임. 이 모델은 참조 이미지, 영상, 오디오를 받지 않습니다.
resolution은 등급입니다. std는 720p, pro(기본값)는 1080p로 렌더링합니다.
멀티샷: 첫 프레임 이미지 하나로 샷을 최대 5개까지, 샷마다 프롬프트와 길이를 따로 지정합니다. 샷 길이의 합은 duration과 같아야 합니다.
요소: elements로 한 번 정의하는 이름 있는 피사체를 최대 3개까지 둘 수 있습니다.
선택한 등급에서 영상 초 단위로 과금됩니다. 실패한 작업은 비용이 들지 않습니다.

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

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

엔드포인트와 인증

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`	`images`를 보내지 않습니다.
첫 프레임	`model`, `prompt`, `images`(링크 1개)	이미지에서 영상이 시작됩니다.
첫 프레임과 마지막 프레임	`model`, `prompt`, `images`(링크 2개)	`images[0]`은 첫 프레임, `images[1]`은 마지막 프레임입니다.
멀티샷	`model`, `prompt`, `images`(링크 정확히 1개), `multi_shots: true`, `multi_prompt`	샷 길이의 합이 `duration`(생략하면 5)과 같아야 합니다.
요소	`model`, `prompt`, `elements`	위의 어떤 모드와도 함께 쓸 수 있습니다. 요소는 최대 3개입니다.

요청 파라미터

`model` string 필수

실행할 모델입니다.

값: kling-v3

값이 잘못된 경우

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

`prompt` string 필수

영상에서 일어나는 일: 피사체, 동작, 카메라 움직임, 스타일.

길이: 1–5000자

길이는 문자 수로 계산합니다(한중일 문자 하나는 1자).
멀티샷을 포함한 모든 모드에서 필수이며, 멀티샷에서는 각 샷에도 multi_prompt에 별도의 프롬프트가 있습니다.

값이 잘못된 경우

누락: "prompt" is required
비어 있거나 한도보다 긴 경우: "prompt" has an unsupported length

`images` string[] 선택

첫 프레임, 또는 첫 프레임과 마지막 프레임.

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

링크 하나: 이 이미지에서 영상이 시작됩니다. 링크 두 개: images[0]은 첫 프레임, images[1]은 마지막 프레임입니다.
멀티샷(multi_shots: true)은 이미지를 정확히 한 장 받습니다.
이 모델에는 참조 이미지 필드가 없습니다. 피사체 이미지는 elements에 넣으세요.

값이 잘못된 경우

링크가 두 개 초과: "images" accepts at most 2 items
빈 배열: "images" requires at least 1 item
https:// 링크가 아닌 경우: "images[0]" must be a public HTTPS URL
이미지가 없거나 두 장인 multi_shots: true: Kling V3 multi-shot mode requires exactly one image

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

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

기본값: 5
범위: 3–15

생략하면 5가 사용되어 과금됩니다.
multi_shots: true에서는 multi_prompt에 있는 샷들의 duration 합이 이 값과 정확히 같아야 합니다. duration을 생략하면 합이 5이어야 합니다.

값이 잘못된 경우

범위 밖, 정수가 아님, 또는 문자열로 보낸 경우: "duration" is outside its supported range
멀티샷 길이의 합이 duration과 다른 경우: Kling V3 shot durations must sum to duration

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

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

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

기본값은 16:9입니다.

값이 잘못된 경우

목록에 없는 값: "aspect_ratio" must be one of: [16:9 9:16 1:1]

`resolution` string 선택기본값: `pro`

품질 등급입니다. std는 720p, pro는 1080p로 렌더링합니다. pro가 초당 가격이 더 높습니다. 이름은 픽셀 크기가 아니라 std와 pro입니다.

허용 값: std, pro
기본값: pro

생략하면 pro가 사용되어 과금됩니다.
4K, 720p, 1080p는 받지 않습니다. std 또는 pro를 보내세요.

값이 잘못된 경우

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

`sound` boolean 선택

영상에 생성된 사운드트랙을 넣을지 정합니다.

생략하면 사운드는 multi_shots를 따릅니다. 멀티샷 요청이면 켜지고 아니면 꺼집니다. 직접 정하려면 true 또는 false를 보내세요.

값이 잘못된 경우

true나 false가 아닌 경우: "sound" must be a boolean

`multi_shots` boolean 선택기본값: `false`

스토리보드 모드를 켭니다. 영상은 multi_prompt에 나열된 샷들로 만들어집니다. 기본값은 false입니다.

기본값: false

images에 이미지 정확히 한 장과, 샷 길이의 합이 duration과 같은 multi_prompt가 필요합니다. multi_shots: true 없이 보낸 multi_prompt는 거부됩니다.
검사 순서: 이미지 한 장, multi_prompt 존재 여부, 길이.

값이 잘못된 경우

true나 false가 아닌 경우: "multi_shots" must be a boolean
이미지가 없거나 둘 이상: Kling V3 multi-shot mode requires exactly one image
multi_prompt 없음: Kling V3 multi-shot mode requires multi_prompt
샷 길이의 합이 duration과 다른 경우: Kling V3 shot durations must sum to duration

`multi_prompt` object[] 선택

멀티샷 영상의 샷을 순서대로 나열합니다. 객체 1~5개이며, 각각 프롬프트와 길이를 가집니다.

항목 수: 1–5

각 샷은 필수 필드 두 개를 가진 객체이며, 다른 필드는 받지 않습니다.
multi_prompt[].prompt(string, 필수): 이 샷에서 일어나는 일, 1~500자.
multi_prompt[].duration(integer, 필수): 이 샷의 길이(초 단위 정수), 1~12.
샷 길이의 합은 요청의 duration(duration을 생략하면 5)과 같아야 하며, 합계는 최대 15입니다.
multi_shots: true일 때만 유효합니다.

값이 잘못된 경우

multi_shots: true 없이 보낸 경우: "multi_prompt" requires multi_shots=true
샷이 5개 초과: "multi_prompt" accepts at most 5 items
빈 배열: "multi_prompt" requires at least 1 item
prompt가 없는 샷: "prompt" is required in "multi_prompt[0]"
duration이 없는 샷: "duration" is required in "multi_prompt[0]"
비어 있거나 500자를 넘는 샷 프롬프트: "multi_prompt[0].prompt" has an unsupported length
1~12 범위 밖이거나 정수가 아닌 샷 길이: "multi_prompt[0].duration" is outside its supported range
prompt, duration 이외의 키: field "name" is not supported in "multi_prompt[0]"
샷 길이의 합이 duration과 다른 경우: Kling V3 shot durations must sum to duration

`elements` object[] 선택

이미지로 한 번 정의하는 이름 있는 피사체(인물, 제품, 소품)를 최대 3개까지 둘 수 있습니다.

항목 수: 3개 이하

객체를 최대 3개까지 담은 배열입니다. 각 객체는 다음 키만 받습니다.
elements[].name(string, 필수): 요소 이름, 1자 이상.
elements[].description(string, 선택): 요소에 대한 설명. 생략하면 name이 설명으로 쓰입니다.
elements[].element_input_urls(문자열 배열, 필수): 요소를 보여 주는 공개 HTTPS 링크 1~4개.
elements[].element_input_audio_urls(문자열 배열, 선택): 요소의 공개 HTTPS 오디오 링크 정확히 하나.
elements[].start_time과 elements[].end_time(integer, 선택): 밀리초 단위 시간이며 각각 0~~30000 사이의 정수입니다. 둘 다 보내거나 둘 다 생략하세요. end_time은 start_time보다 커야 하고, end_time - start_time은 3000~~8000(3~8초)이어야 합니다.
링크 제한은 요소마다 따로 적용됩니다. 각 항목에 링크 4개와 오디오 링크 1개를 둘 수 있습니다.

값이 잘못된 경우

요소가 3개 초과: "elements" accepts at most 3 items
객체가 아닌 요소: "elements[0]" must be an object
name이 없는 요소: "name" is required in "elements[0]"
element_input_urls가 없는 요소: "element_input_urls" is required in "elements[0]"
빈 name: "elements[0].name" has an unsupported length
링크가 4개 초과: "elements[0].element_input_urls" accepts at most 4 items
빈 element_input_urls 배열: "elements[0].element_input_urls" requires at least 1 item
https://:가 아닌 링크: "elements[0].element_input_urls[1]" must be a public HTTPS URL
오디오 링크가 둘 이상: "elements[0].element_input_audio_urls" accepts at most 1 items
0~30000 범위 밖이거나 정수가 아닌 start_time 또는 end_time: "elements[0].start_time" is outside its supported range
요소가 받지 않는 키: field "color" is not supported in "elements[0]"
start_time과 end_time 중 하나만 있음, end_time이 start_time보다 늦지 않음, 또는 구간이 3초보다 짧거나 8초보다 긴 경우: Kling V3 element segment must provide a 3-8 second start_time/end_time range

입력 미디어 제한

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

게이트웨이는 모든 이미지, 요소 링크, 오디오 링크가 공개 HTTPS 링크인지만 검사합니다. 작업 생성 전에 크기, 형식, 픽셀 크기를 측정하지 않으므로, 모델이 사용할 수 없는 입력은 제출 후 작업을 실패시킵니다. 메시지에 바꿀 부분이 표시되며 보류 금액은 전액 반환됩니다.
로컬 파일이 있다면 POST /v1/files로 업로드하고 반환된 data.url을 전달하세요.

멀티샷 규칙

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

규칙	메시지
`multi_prompt`를 보냈지만 `multi_shots`가 `true`가 아님	`"multi_prompt" requires multi_shots=true`
`images`에 이미지가 정확히 한 장 없는 `multi_shots: true`	`Kling V3 multi-shot mode requires exactly one image`
`multi_prompt` 없는 `multi_shots: true`	`Kling V3 multi-shot mode requires multi_prompt`
샷 길이의 합이 `duration`(생략하면 5)과 다름	`Kling V3 shot durations must sum to duration`

텍스트만으로 하는 멀티샷은 지원하지 않습니다. 멀티샷 영상은 항상 이미지 한 장에서 시작합니다.
멀티샷 요청은 샷 길이의 합인 duration초로 과금됩니다.

이 모델이 받지 않는 필드

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

reference_images, reference_videos, reference_audios, generate_audio, seed, quality, watermark, task_type, output_format → field "reference_images" is not supported by model kling-v3(보낸 필드 포함).
그 밖의 알 수 없는 필드 → 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-v3",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": true
}'

텍스트로 영상 생성

사운드가 있는 pro 등급(1080p) 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-v3",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": true
}'

첫 프레임

이미지에서 영상이 시작됩니다.

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-v3",
  "prompt": "The bottle slowly rotates on its pedestal while reflections move across the glass",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "duration": 5,
  "resolution": "pro",
  "sound": true
}'

첫 프레임과 마지막 프레임

더 저렴한 std 등급(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-v3",
  "prompt": "The camera moves from the bottle on the table to the singer on a neon stage in one continuous shot",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "resolution": "std"
}'

멀티샷

첫 프레임 이미지 하나로 만드는 3초 샷 두 개입니다. 샷 길이(3 + 3)가 duration(6)과 같습니다.

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-v3",
  "prompt": "A two-shot cinematic product reveal",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": true,
  "multi_shots": true,
  "multi_prompt": [
    {
      "prompt": "Macro detail shot of the bottle with moving reflections",
      "duration": 3
    },
    {
      "prompt": "Wide hero reveal of the bottle on a dark pedestal",
      "duration": 3
    }
  ]
}'

재사용 가능한 요소

이미지 두 장으로 이름 있는 요소 하나를 정의합니다. 요소 이름은 product이며 설명은 선택 사항입니다.

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-v3",
  "prompt": "A slow cinematic camera orbit around the product",
  "duration": 5,
  "resolution": "pro",
  "elements": [
    {
      "name": "product",
      "description": "The featured water bottle",
      "element_input_urls": [
        "https://cdn.beatapi.io/samples/smart-bottle.png",
        "https://cdn.beatapi.io/samples/neon-singer.png"
      ]
    }
  ]
}'

응답

작업 생성(201)

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

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-v3",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v3",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.65,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.65,
      "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-v3",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v3",
    "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.65,
      "credits_settled": 0.65,
      "credits_refunded": 0,
      "credits_charged": 0.65,
      "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-v3",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v3",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.65,
      "credits_settled": 0,
      "credits_refunded": 0.65,
      "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-v3",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": True
})
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"])

과금

sound는 가격에 영향을 주지 않습니다. 가격은 duration과 resolution으로만 정해지므로 사운드 유무와 관계없이 같은 가격 행이 적용됩니다.
가격은 선택한 등급의 영상 초당 요금입니다. 아래 목록은 8초 클립 기준이므로 8로 나누면 초당 요금이 됩니다(std 초당 약 $0.11, `pro` 약$ 0.13).
초 수는 duration이며, 생략하면 5입니다. 멀티샷 요청은 샷 길이의 합이며 duration과 같습니다. 작업의 usage.billable_duration_seconds에 표시됩니다.
가격은 작업 생성 시 보류되고 영상이 준비되면 정산됩니다. 실패한 작업은 제출 후 콘텐츠 검수에서 거부된 경우를 포함해 전액 환불됩니다.

자주 발생하는 오류

오류 또는 증상	원인	해결 방법
400 `"resolution" must be one of: [std pro]`	`720p`, `1080p`, `4K` 같은 픽셀 크기를 보냈습니다. 이 모델은 등급을 받습니다.	`std`(720p로 렌더링) 또는 `pro`(1080p로 렌더링)를 보내세요.
400 `Kling V3 multi-shot mode requires exactly one image`	이미지가 없거나 두 장인 `multi_shots: true`.	`images`에 이미지를 한 장 보내세요. 텍스트만으로 하는 멀티샷은 없습니다.
400 `Kling V3 shot durations must sum to duration`	`multi_prompt` 길이의 합이 `duration`과 다르거나, `duration`을 생략했는데 5가 아닙니다.	샷 길이의 합이 `duration`과 정확히 같도록 맞추세요(예: `duration: 6`에 3 + 3).
400 `"multi_prompt" requires multi_shots=true`	`multi_shots: true` 없이 `multi_prompt`를 보냈습니다.	`multi_shots: true`를 추가하거나 `multi_prompt`를 삭제하세요.
400 `Kling V3 multi-shot mode requires multi_prompt`	`multi_prompt` 없는 `multi_shots: true`.	샷 1~5개가 든 `multi_prompt`를 추가하세요.
400 `Kling V3 element segment must provide a 3-8 second start_time/end_time range`	요소에 `start_time`과 `end_time` 중 하나만 있거나, `end_time`이 `start_time`보다 늦지 않거나, 구간이 3초보다 짧거나 8초보다 깁니다. 둘 다 밀리초 단위입니다.	둘 다 밀리초 단위로 보내고, `end_time - start_time`은 3000~8000 사이로 맞추세요.
400 `"elements[0].element_input_urls" accepts at most 4 items`	한 요소에 링크가 4개를 넘습니다.	요소마다 링크를 최대 4개까지 두고, 피사체를 별도의 요소로 나누세요(최대 3개).
400 `field "reference_images" is not supported by model kling-v3`	이 모델에는 참조 필드가 없습니다(`generate_audio`, `seed`, `quality` 포함).	해당 필드를 삭제하세요. 피사체 이미지는 `elements`에 넣으세요.
400 `"duration" is outside its supported range`	3~15 사이의 정수가 아니거나 문자열로 보냈습니다.	`5` 같은 정수를 보내세요.
작업이 `content_policy_violation`과 함께 `failed`	프롬프트, 입력 이미지 또는 결과가 콘텐츠 검수에서 거부되었습니다.	프롬프트나 이미지를 바꾸세요. 그대로 재시도하면 다시 실패하며, 비용은 청구되지 않습니다.
402 `insufficient_credits`	잔액이 이 길이와 등급의 보류 금액보다 적습니다.	충전하거나, `duration`을 줄이거나, `std`를 사용하세요.

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-v3

값이 잘못된 경우

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

허용된 값:

promptstring필수1-5000 characters

영상에서 일어나는 일: 피사체, 동작, 카메라 움직임, 스타일.

길이: 1–5000자

길이는 문자 수로 계산합니다(한중일 문자 하나는 1자).
멀티샷을 포함한 모든 모드에서 필수이며, 멀티샷에서는 각 샷에도 multi_prompt에 별도의 프롬프트가 있습니다.

값이 잘못된 경우

누락: "prompt" is required
비어 있거나 한도보다 긴 경우: "prompt" has an unsupported length

aspect_ratioenum선택 사항기본값 16:9

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

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

기본값: 16:9

기본값은 16:9입니다.

값이 잘못된 경우

목록에 없는 값: "aspect_ratio" must be one of: [16:9 9:16 1:1]

허용된 값:

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

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

기본값: 5

범위: 3–15

생략하면 5가 사용되어 과금됩니다.
multi_shots: true에서는 multi_prompt에 있는 샷들의 duration 합이 이 값과 정확히 같아야 합니다. duration을 생략하면 합이 5이어야 합니다.

값이 잘못된 경우

범위 밖, 정수가 아님, 또는 문자열로 보낸 경우: "duration" is outside its supported range
멀티샷 길이의 합이 duration과 다른 경우: Kling V3 shot durations must sum to duration

elementslist of objects선택 사항

이미지로 한 번 정의하는 이름 있는 피사체(인물, 제품, 소품)를 최대 3개까지 둘 수 있습니다.

항목 수: 3개 이하

객체를 최대 3개까지 담은 배열입니다. 각 객체는 다음 키만 받습니다.
elements[].name(string, 필수): 요소 이름, 1자 이상.
elements[].description(string, 선택): 요소에 대한 설명. 생략하면 name이 설명으로 쓰입니다.
elements[].element_input_urls(문자열 배열, 필수): 요소를 보여 주는 공개 HTTPS 링크 1~4개.
elements[].element_input_audio_urls(문자열 배열, 선택): 요소의 공개 HTTPS 오디오 링크 정확히 하나.
elements[].start_time과 elements[].end_time(integer, 선택): 밀리초 단위 시간이며 각각 0~~30000 사이의 정수입니다. 둘 다 보내거나 둘 다 생략하세요. end_time은 start_time보다 커야 하고, end_time - start_time은 3000~~8000(3~8초)이어야 합니다.
링크 제한은 요소마다 따로 적용됩니다. 각 항목에 링크 4개와 오디오 링크 1개를 둘 수 있습니다.

값이 잘못된 경우

요소가 3개 초과: "elements" accepts at most 3 items
객체가 아닌 요소: "elements[0]" must be an object
name이 없는 요소: "name" is required in "elements[0]"
element_input_urls가 없는 요소: "element_input_urls" is required in "elements[0]"
빈 name: "elements[0].name" has an unsupported length
링크가 4개 초과: "elements[0].element_input_urls" accepts at most 4 items
빈 element_input_urls 배열: "elements[0].element_input_urls" requires at least 1 item
https://:가 아닌 링크: "elements[0].element_input_urls[1]" must be a public HTTPS URL
오디오 링크가 둘 이상: "elements[0].element_input_audio_urls" accepts at most 1 items
0~30000 범위 밖이거나 정수가 아닌 start_time 또는 end_time: "elements[0].start_time" is outside its supported range
요소가 받지 않는 키: field "color" is not supported in "elements[0]"
start_time과 end_time 중 하나만 있음, end_time이 start_time보다 늦지 않음, 또는 구간이 3초보다 짧거나 8초보다 긴 경우: Kling V3 element segment must provide a 3-8 second start_time/end_time range

imageslist of strings선택 사항

첫 프레임, 또는 첫 프레임과 마지막 프레임.

항목 수: 1–2

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

링크 하나: 이 이미지에서 영상이 시작됩니다. 링크 두 개: images[0]은 첫 프레임, images[1]은 마지막 프레임입니다.
멀티샷(multi_shots: true)은 이미지를 정확히 한 장 받습니다.
이 모델에는 참조 이미지 필드가 없습니다. 피사체 이미지는 elements에 넣으세요.

값이 잘못된 경우

링크가 두 개 초과: "images" accepts at most 2 items
빈 배열: "images" requires at least 1 item
https:// 링크가 아닌 경우: "images[0]" must be a public HTTPS URL
이미지가 없거나 두 장인 multi_shots: true: Kling V3 multi-shot mode requires exactly one image

multi_promptlist of objects선택 사항

멀티샷 영상의 샷을 순서대로 나열합니다. 객체 1~5개이며, 각각 프롬프트와 길이를 가집니다.

항목 수: 1–5

각 샷은 필수 필드 두 개를 가진 객체이며, 다른 필드는 받지 않습니다.
multi_prompt[].prompt(string, 필수): 이 샷에서 일어나는 일, 1~500자.
multi_prompt[].duration(integer, 필수): 이 샷의 길이(초 단위 정수), 1~12.
샷 길이의 합은 요청의 duration(duration을 생략하면 5)과 같아야 하며, 합계는 최대 15입니다.
multi_shots: true일 때만 유효합니다.

값이 잘못된 경우

multi_shots: true 없이 보낸 경우: "multi_prompt" requires multi_shots=true
샷이 5개 초과: "multi_prompt" accepts at most 5 items
빈 배열: "multi_prompt" requires at least 1 item
prompt가 없는 샷: "prompt" is required in "multi_prompt[0]"
duration이 없는 샷: "duration" is required in "multi_prompt[0]"
비어 있거나 500자를 넘는 샷 프롬프트: "multi_prompt[0].prompt" has an unsupported length
1~12 범위 밖이거나 정수가 아닌 샷 길이: "multi_prompt[0].duration" is outside its supported range
prompt, duration 이외의 키: field "name" is not supported in "multi_prompt[0]"
샷 길이의 합이 duration과 다른 경우: Kling V3 shot durations must sum to duration

multi_shotsboolean선택 사항기본값 false

스토리보드 모드를 켭니다. 영상은 multi_prompt에 나열된 샷들로 만들어집니다. 기본값은 false입니다.

기본값: false

images에 이미지 정확히 한 장과, 샷 길이의 합이 duration과 같은 multi_prompt가 필요합니다. multi_shots: true 없이 보낸 multi_prompt는 거부됩니다.
검사 순서: 이미지 한 장, multi_prompt 존재 여부, 길이.

값이 잘못된 경우

true나 false가 아닌 경우: "multi_shots" must be a boolean
이미지가 없거나 둘 이상: Kling V3 multi-shot mode requires exactly one image
multi_prompt 없음: Kling V3 multi-shot mode requires multi_prompt
샷 길이의 합이 duration과 다른 경우: Kling V3 shot durations must sum to duration

resolutionenum선택 사항기본값 pro

품질 등급입니다. std는 720p, pro는 1080p로 렌더링합니다. pro가 초당 가격이 더 높습니다. 이름은 픽셀 크기가 아니라 std와 pro입니다.

허용 값: std, pro

기본값: pro

생략하면 pro가 사용되어 과금됩니다.
4K, 720p, 1080p는 받지 않습니다. std 또는 pro를 보내세요.

값이 잘못된 경우

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

허용된 값:

soundboolean선택 사항

영상에 생성된 사운드트랙을 넣을지 정합니다.

생략하면 사운드는 multi_shots를 따릅니다. 멀티샷 요청이면 켜지고 아니면 꺼집니다. 직접 정하려면 true 또는 false를 보내세요.

값이 잘못된 경우

true나 false가 아닌 경우: "sound" must be a boolean

응답

작업 객체입니다. 작업이 성공할 때까지 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

엔드포인트와 인증

Authorization string 필수

요청 처리 방식

작업 만들기

완료 기다리기

결과 저장하기

입력 모드

요청 파라미터

model string 필수

prompt string 필수

images string[] 선택

duration integer 선택기본값: 5

aspect_ratio string 선택기본값: 16:9

resolution string 선택기본값: pro

sound boolean 선택

multi_shots boolean 선택기본값: false

multi_prompt object[] 선택

elements object[] 선택

입력 미디어 제한

멀티샷 규칙

이 모델이 받지 않는 필드

요청 예시

텍스트로 영상 생성

첫 프레임

첫 프레임과 마지막 프레임

멀티샷

재사용 가능한 요소

응답

작업 생성(201)

완료된 작업

출력 필드

실패한 작업

전체 예시

과금

자주 발생하는 오류

HTTP 오류 요약

인증

헤더

요청

응답

오류

`Authorization` string 필수

`model` string 필수

`prompt` string 필수

`images` string[] 선택

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

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

`resolution` string 선택기본값: `pro`

`sound` boolean 선택

`multi_shots` boolean 선택기본값: `false`

`multi_prompt` object[] 선택

`elements` object[] 선택