Kling Image 4.0
Kling의 이미지 모델입니다. 텍스트, 최대 10장의 참조 이미지와 이름 있는 요소로 작업당 1~9장의 이미지를 2K, 4K 또는 8K로 생성하거나 편집합니다.
- 비동기 방식입니다. 생성 요청은 곧바로 작업 ID를 반환하며, 작업이 성공하면 이미지가 도착합니다.
- 작업 하나가
n으로 1~9장의 이미지를 만들며, 각 이미지는 해당resolution등급 요금으로 과금됩니다. - 텍스트로 이미지를 만들거나, 공개 HTTPS 링크로 전달한 참조 이미지와 이름 있는
elements를 합계 최대 10개까지 편집·합성합니다. - 프롬프트에서 입력을 지칭하세요.
images는 순서대로@image_1,@image_2…, 요소는@뒤에 이름을 붙입니다. resolution(2K, 4K 또는 8K)에 따라 이미지당 가격이 정해지며, 참조 이미지와 요소마다 고정 요금이 더해집니다. 실패한 작업은 과금되지 않습니다.
API Explorer에서 이 모델을 엽니다. BeatAPI API 키를 입력해 작업을 만드세요. 실제 호출이며 본인 잔액에서 과금됩니다.
엔드포인트와 인증
POST https://api.beatapi.io/v1/images/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에 대한 웹훅을 등록하세요. 처리 시간 초과로 중단된 작업은 이벤트를 보내지 않으므로 폴링은 대비책으로 유지하세요.
입력 모드
요청 파라미터
model
string
필수
실행할 모델입니다.
값: kling-image-v4
값이 잘못된 경우
- 누락:
"model" is required - 알 수 없는 모델 ID:
"model" kling-image-v9 is not catalogued - 이 엔드포인트로 영상 모델을 보낸 경우:
"model" kling-v4 is served by POST /v1/videos/tasks, not this endpoint
prompt
string
필수
그릴 내용 또는 참조 이미지에서 바꿀 내용입니다. 피사체, 스타일, 조명, 구도, 이미지에 들어가야 할 문구를 쓰고, 각 입력을 @ 멘션으로 지칭합니다.
길이: 1–20000자
- 길이는 문자 수로 계산합니다(한중일 문자 하나는 1자).
- 멘션:
images는 목록 순서대로@image_1,@image_2…이며, 요소는@뒤에name을 붙입니다. - 모든
@image_N은 같은 요청의 이미지를 가리켜야 합니다. 이미지가 두 장인데@image_3을 쓰면 작업 생성 시 거부됩니다.
값이 잘못된 경우
- 누락:
"prompt" is required - 비어 있거나 한도보다 긴 경우:
"prompt" has an unsupported length - 요청에 없는 이미지를 멘션함:
the prompt names @image_3, which this request does not send
images
string[]
선택
편집하거나 합성할 참조 이미지입니다. 프롬프트에서는 목록 순서대로 @image_1, @image_2 …로 지칭합니다.
항목 수: 1–10
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.
- 각 항목은 JPEG 또는 PNG 파일을 가리키는 공개
https://링크여야 합니다. 작업을 생성할 때 BeatAPI는 각 링크를 읽고, 그런 이미지가 아니거나 아래 제한을 벗어나는 링크를 위치와 함께 거부합니다(images[0]이 첫 번째 링크). images와elements는 합계 최대 10개입니다.- 링크마다 작업에 고정 요금이 추가됩니다(가격 참고).
값이 잘못된 경우
- 최대 개수를 넘은 경우:
"images" accepts at most 10 items - 빈 배열:
"images" requires at least 1 item - https:// 링크가 아닌 경우:
"images[0]" must be a public HTTPS URL - JPEG 또는 PNG 파일이 아닌 링크(이 예에서는 WebP):
"images[0]" is not a PNG or JPEG image: the URL returned image/webp - 오류로 응답하는 링크:
"images[0]" could not be downloaded: the URL returned HTTP 404 - 이미지와 요소가 합계 10개 초과:
Kling Image 4.0 takes at most 10 images and elements together
예시
elements
object[]
선택
캐릭터, 동물, 소품, 의상, 장면 같은 이름 있는 피사체입니다. 각각 2~4장의 이미지로 보여 주며, 프롬프트에서는 @ 뒤에 name을 붙여 지칭합니다.
항목 수: 10개 이하
- 객체 배열입니다. 각 객체는 다음 키만 받습니다.
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[].tag(문자열, 선택): 요소의 종류입니다.elements[].description(string, 선택): 요소에 대한 설명, 최대 100자.- 요소는 이미지로만 구성됩니다. 이 모델은 영상 요소와 음성 요소를 받지 않습니다.
images와elements는 합계 최대 10개입니다. 요소마다 포함한 이미지 수와 관계없이 작업에 고정 요금이 더해집니다.
값이 잘못된 경우
- 요소가 10개 초과:
"elements" accepts at most 10 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]"- 비어 있거나 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].element_input_urls" requires at least 2 item - 이미지가 네 장 초과:
"elements[0].element_input_urls" accepts at most 4 items - 목록에 없는
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 "element_input_video_urls" is not supported in "elements[0]"
예시
aspect_ratio
string
선택기본값: auto
이미지의 형태(너비:높이)입니다.
허용 값: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
기본값: auto
- 생략하면
auto가 사용되며, 모델이 프롬프트와 입력 이미지를 보고 프레임을 정합니다. 형태가 중요하면 비율을 지정하세요.
값이 잘못된 경우
- 목록에 없는 값:
"aspect_ratio" must be one of: [auto 1:1 16:9 9:16 4:3 3:4 3:2 2:3 21:9]
resolution
string
선택기본값: 2K
이미지의 크기 등급: 2K, 4K 또는 8K. 등급마다 이미지당 가격이 다릅니다.
허용 값: 2K, 4K, 8K
기본값: 2K
- 생략하면
2K가 사용되어 과금됩니다. - 2K와 4K 이미지는 PNG로, 8K 이미지는 JPEG으로 반환됩니다.
- K는 대문자로 쓰세요.
2k는 거부됩니다. 1K 등급은 없으며2048x2048같은 픽셀 크기도 받지 않습니다.
값이 잘못된 경우
- 목록에 없는 값(예:
1K또는2k):"resolution" must be one of: [2K 4K 8K]
n
integer
선택기본값: 1
이 작업에서 생성할 이미지 수입니다. 모든 이미지에 같은 프롬프트, 입력, 비율, 등급이 사용됩니다.
기본값: 1
범위: 1–9
- 생략하면
1이 사용됩니다. - 각 이미지는
resolution가격으로 과금되므로n은 이미지 부분의 가격을 배로 늘립니다. 참조 이미지와 요소 요금은 이미지마다가 아니라 작업당 한 번만 계산됩니다. - 이미지는 전달된 수만큼 과금됩니다.
값이 잘못된 경우
- 범위 밖, 정수가 아님, 또는 문자열로 보낸 경우:
"n" is outside its supported range
게이트웨이는 작업을 만들기 전에 다음 조합도 검사합니다.
- n은 요청 하나로 1~9장의 이미지를 만듭니다. 각 이미지는 해당 해상도 등급으로 과금되며, images의 각 이미지와 각 요소는 요청마다 한 번씩 추가로 과금됩니다
- 프롬프트에서 images는 순서대로 @image_1, @image_2 …, 요소는 @ 뒤에 이름을 붙여 지칭합니다. 모든 @image_N은 같은 요청의 이미지를 가리켜야 합니다
- 요소는 element_input_urls에 넣은 한 피사체의 이미지 2~4장이며 첫 번째가 메인 뷰입니다. images와 elements는 합계 최대 10개입니다
- 요소 이름은 영문자, 숫자, 밑줄 또는 한자 1-20자이며, 대소문자 구분 없이 고유해야 하고 image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame, last_frame은 쓸 수 없습니다
- images는 JPEG 또는 PNG, 최대 20 MB, 비율 2:5~5:2, 각 변 최대 8192 px입니다
- 2K와 4K는 PNG로, 8K는 JPEG으로 반환됩니다. aspect_ratio auto는 프롬프트와 입력 이미지를 보고 모델이 프레임을 정합니다
입력 미디어 제한
게이트웨이는 작업을 만들기 전에 모든 입력을 읽고, 아래 제한을 벗어난 입력은 해당 입력을 명시한 400 bad_request로 거부합니다. 과금되지 않습니다.
- 게이트웨이는 작업 생성 전에
images의 모든 링크를 읽고, 이 제한을 벗어난 링크를 이름을 밝혀 거부합니다. 예:images[0] has an aspect ratio of 3.10 (width/height); this model takes 0.4 to 2.5.과금되지 않습니다. - 요소 이미지(
element_input_urls)는 작업 생성 전에 공개 HTTPS 링크인지만 확인합니다. 같은 제한 안의 JPEG 또는 PNG 파일을 사용하세요. - 로컬 파일이 있다면
POST /v1/files로 업로드하고 반환된data.url을 전달하세요.
프롬프트 멘션
입력마다 멘션이 있습니다.
- 대응하는 이미지가 없는
@image_N은 작업 생성 시 거부됩니다. 예:the prompt names @image_2, which this request does not send.
이 모델이 받지 않는 필드
이미지 엔드포인트는 다른 이미지 모델이 사용하는 필드도 몇 가지 알고 있습니다. 이 모델에서 그런 필드를 보내면 무시하지 않고 거부하므로, 효과 없는 설정에 비용을 내는 일이 없습니다.
output_format,quality,seed,background,size,enhance_prompt→field "output_format" is not supported by model kling-image-v4(보낸 필드 포함).- 그 밖의 알 수 없는 필드 →
unknown field: <name>.
요청에 잘못된 필드가 여러 개 있어도 메시지에는 하나만 표시됩니다. 고친 뒤 다시 보내세요.
요청 예시
텍스트로 이미지 생성
프롬프트로 2K 이미지 한 장을 생성합니다.
작업 하나로 변형 4장
같은 프롬프트로 4K 이미지 4장을 생성하며, 각 이미지는 4K 가격으로 과금됩니다.
이미지 한 장 편집
제품 사진을 캠페인 이미지로 재구성합니다.
여러 이미지 합성
프롬프트에서 각 참조를 멘션으로 지칭합니다.
이름 있는 요소
한 피사체를 여러 각도에서 찍은 이미지를 요소로 만들고 이름으로 배치합니다.
응답
작업 생성(201)
작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.
완료된 작업
GET /v1/tasks/{task_id}는 HTTP 200과 함께 status: "succeeded", 그리고 data.output에 결과를 반환합니다.
출력 필드
실패한 작업
실패한 작업도 GET /v1/tasks/{task_id}에서는 HTTP 200입니다. 실패 정보는 본문에 있습니다. 보류 금액이 전액 환불되므로 과금되지 않습니다.
전체 예시
작업을 만들고, 서버의 폴링 안내에 따라 기다린 뒤 결과 URL을 출력합니다. 환경 변수에 BEATAPI_API_KEY를 설정하고 requests를 설치하세요.
과금
- 각 이미지는
resolution(아래 표)에 따라 가격이 정해지고n을 곱합니다.images의 각 링크와elements의 각 요소는 작업당 한 번씩 고정 요금이 더해집니다. - 가격은 작업 생성 시 잔액에서, 키에 한도가 있다면 키 한도에서도 보류됩니다. 작업이 생기기 전에 거부된 요청은 비용이 들지 않습니다.
- 성공한 작업은 전달된 이미지 수만큼 과금됩니다. 실패한 작업은 예약액을 전액 반환합니다. 이때
credits_refunded는credits_reserved와 같고,credits_charged와credits_settled는 0입니다.
현재 정가이며 가격 페이지와 같습니다. 별도 할인 계약이 있는 계정은 더 적게 지불하며, 실제 청구 금액은 항상 작업의 data.usage에서 확인할 수 있습니다.
자주 발생하는 오류
HTTP 오류 요약
작업이 생성되기 전의 오류는 2xx가 아닌 응답으로 오며 과금되지 않습니다. error.code 또는 error.retryable로 분기하세요. message에 문제가 표시됩니다. 전체 목록과 재시도 정책은 오류에 있습니다.
인증
API 키를 Authorization: Bearer <BEATAPI_API_KEY>로 보내세요.
헤더
본문은 Content-Type: application/json과 함께 JSON으로 보냅니다. Idempotency-Key는 선택 사항입니다. 논리적 요청마다 고유한 값(최대 255자)을 보내고, 완전히 같은 본문을 재시도할 때만 다시 사용하세요. 24시간 안에 같은 키와 본문으로 재시도하면 첫 응답을 Idempotent-Replayed: true와 함께 다시 반환하고, 같은 키에 다른 본문을 보내면 409 idempotency_conflict를 반환합니다. 2xx 이외의 응답은 저장되지 않으므로 400이나 402 이후의 재시도는 다시 실행됩니다.
요청
실행할 모델입니다.
값: kling-image-v4
값이 잘못된 경우
- 누락:
"model" is required - 알 수 없는 모델 ID:
"model" kling-image-v9 is not catalogued - 이 엔드포인트로 영상 모델을 보낸 경우:
"model" kling-v4 is served by POST /v1/videos/tasks, not this endpoint
그릴 내용 또는 참조 이미지에서 바꿀 내용입니다. 피사체, 스타일, 조명, 구도, 이미지에 들어가야 할 문구를 쓰고, 각 입력을 @ 멘션으로 지칭합니다.
길이: 1–20000자
- 길이는 문자 수로 계산합니다(한중일 문자 하나는 1자).
- 멘션:
images는 목록 순서대로@image_1,@image_2…이며, 요소는@뒤에name을 붙입니다. - 모든
@image_N은 같은 요청의 이미지를 가리켜야 합니다. 이미지가 두 장인데@image_3을 쓰면 작업 생성 시 거부됩니다.
값이 잘못된 경우
- 누락:
"prompt" is required - 비어 있거나 한도보다 긴 경우:
"prompt" has an unsupported length - 요청에 없는 이미지를 멘션함:
the prompt names @image_3, which this request does not send
이미지의 형태(너비:높이)입니다.
허용 값: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
기본값: auto
- 생략하면
auto가 사용되며, 모델이 프롬프트와 입력 이미지를 보고 프레임을 정합니다. 형태가 중요하면 비율을 지정하세요.
값이 잘못된 경우
- 목록에 없는 값:
"aspect_ratio" must be one of: [auto 1:1 16:9 9:16 4:3 3:4 3:2 2:3 21:9]
캐릭터, 동물, 소품, 의상, 장면 같은 이름 있는 피사체입니다. 각각 2~4장의 이미지로 보여 주며, 프롬프트에서는 @ 뒤에 name을 붙여 지칭합니다.
항목 수: 10개 이하
- 객체 배열입니다. 각 객체는 다음 키만 받습니다.
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[].tag(문자열, 선택): 요소의 종류입니다.elements[].description(string, 선택): 요소에 대한 설명, 최대 100자.- 요소는 이미지로만 구성됩니다. 이 모델은 영상 요소와 음성 요소를 받지 않습니다.
images와elements는 합계 최대 10개입니다. 요소마다 포함한 이미지 수와 관계없이 작업에 고정 요금이 더해집니다.
값이 잘못된 경우
- 요소가 10개 초과:
"elements" accepts at most 10 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]"- 비어 있거나 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].element_input_urls" requires at least 2 item - 이미지가 네 장 초과:
"elements[0].element_input_urls" accepts at most 4 items - 목록에 없는
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 "element_input_video_urls" is not supported in "elements[0]"
예시
"elements": [
{
"name": "Bottle",
"tag": "prop",
"description": "A matte smart water bottle",
"element_input_urls": [
"https://your-cdn.example.com/bottle-front.png",
"https://your-cdn.example.com/bottle-side.png"
]
}
]
편집하거나 합성할 참조 이미지입니다. 프롬프트에서는 목록 순서대로 @image_1, @image_2 …로 지칭합니다.
항목 수: 1–10
각 항목은 공개 https:// URL입니다. 로컬 파일은 POST /v1/files로 먼저 업로드한 뒤 반환된 data.url을 전달하세요.
- 각 항목은 JPEG 또는 PNG 파일을 가리키는 공개
https://링크여야 합니다. 작업을 생성할 때 BeatAPI는 각 링크를 읽고, 그런 이미지가 아니거나 아래 제한을 벗어나는 링크를 위치와 함께 거부합니다(images[0]이 첫 번째 링크). images와elements는 합계 최대 10개입니다.- 링크마다 작업에 고정 요금이 추가됩니다(가격 참고).
값이 잘못된 경우
- 최대 개수를 넘은 경우:
"images" accepts at most 10 items - 빈 배열:
"images" requires at least 1 item - https:// 링크가 아닌 경우:
"images[0]" must be a public HTTPS URL - JPEG 또는 PNG 파일이 아닌 링크(이 예에서는 WebP):
"images[0]" is not a PNG or JPEG image: the URL returned image/webp - 오류로 응답하는 링크:
"images[0]" could not be downloaded: the URL returned HTTP 404 - 이미지와 요소가 합계 10개 초과:
Kling Image 4.0 takes at most 10 images and elements together
예시
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png",
"https://cdn.beatapi.io/samples/neon-singer.png"
]
이 작업에서 생성할 이미지 수입니다. 모든 이미지에 같은 프롬프트, 입력, 비율, 등급이 사용됩니다.
기본값: 1
범위: 1–9
- 생략하면
1이 사용됩니다. - 각 이미지는
resolution가격으로 과금되므로n은 이미지 부분의 가격을 배로 늘립니다. 참조 이미지와 요소 요금은 이미지마다가 아니라 작업당 한 번만 계산됩니다. - 이미지는 전달된 수만큼 과금됩니다.
값이 잘못된 경우
- 범위 밖, 정수가 아님, 또는 문자열로 보낸 경우:
"n" is outside its supported range
이미지의 크기 등급: 2K, 4K 또는 8K. 등급마다 이미지당 가격이 다릅니다.
허용 값: 2K, 4K, 8K
기본값: 2K
- 생략하면
2K가 사용되어 과금됩니다. - 2K와 4K 이미지는 PNG로, 8K 이미지는 JPEG으로 반환됩니다.
- K는 대문자로 쓰세요.
2k는 거부됩니다. 1K 등급은 없으며2048x2048같은 픽셀 크기도 받지 않습니다.
값이 잘못된 경우
- 목록에 없는 값(예:
1K또는2k):"resolution" must be one of: [2K 4K 8K]
응답
작업 객체입니다. 작업이 성공할 때까지 output는 null입니다. ‘실행 중’으로 표시된 필드는 작업이 끝나면 사라집니다.

