Kling Image 4.0
Kling’s image model. Generate or edit 1 to 9 images per task from text, up to 10 reference images and named elements, at 2K, 4K or 8K.
- Asynchronous: the create call returns a task ID in a moment; the images arrive when the task succeeds.
- One task renders 1 to 9 images with
n; each image is billed at itsresolutiontier. - Text to image, or edit and combine up to 10 reference images and named
elementstogether, given as public HTTPS links. - Name inputs in the prompt:
@image_1,@image_2… forimagesin order, and@plus the name for an element. - Priced per image by
resolution(2K, 4K or 8K), plus a fixed charge for each reference image and each element. A failed task costs nothing.
Opens this model in the API Explorer. Enter your BeatAPI API key to create a task: the call is real and is billed to your own balance.
Endpoint and authentication
POST https://api.beatapi.io/v1/images/tasks
Authorization
string
Required
Your BeatAPI API key, sent as Bearer <BEATAPI_API_KEY>. Create keys in the Dashboard. Keep keys on your server; never ship them in a browser or mobile app.
Send the body as JSON with Content-Type: application/json. Idempotency-Key is optional: send a unique value (at most 255 characters) per logical request and reuse it only to retry that exact body. Within 24 hours a retry with the same key and body returns the first response again with Idempotent-Replayed: true; the same key with a different body returns 409 idempotency_conflict. Responses other than 2xx are not stored, so a retry after a 400 or 402 runs again.
How a request works
Create the task
POST the parameters below to the endpoint. A 201 means the task was accepted and its price reserved from your balance; the work runs in the background. Save data.id.
Wait for it to finish
Call GET /v1/tasks/{task_id} and wait data.poll_after_seconds between calls (5 s for images, 8 s for videos) until status is succeeded or failed. Or register a webhook for task.succeeded and task.failed; keep polling as the fallback, because a task stopped by the processing timeout sends no event.
Save the result
On succeeded, download every data.output.media[].url and store the files you need; BeatAPI does not promise how long result URLs stay available. On failed, read data.error_code and data.error_message: the reserved amount was returned to your balance, and data.retryable says whether sending the same request again can succeed.
Input modes
Request parameters
model
string
Required
The model to run.
Value: kling-image-v4
If the value is wrong
- Missing:
"model" is required - Unknown model ID:
"model" kling-image-v9 is not catalogued - A video model sent to this endpoint:
"model" kling-v4 is served by POST /v1/videos/tasks, not this endpoint
prompt
string
Required
What to draw, or what to change in the reference images: subject, style, lighting, composition and any text that must appear, with each input named by its @ mention.
Length: 1–20000 characters
- Length is counted in characters (a CJK character counts as one).
- Mentions:
imagesare@image_1,@image_2… in list order, and an element is@followed by itsname. - Every
@image_Nmust name an image of the same request.@image_3with two images is refused when the task is created.
If the value is wrong
- Missing:
"prompt" is required - Empty or longer than the limit:
"prompt" has an unsupported length - A mention of an image the request does not send:
the prompt names @image_3, which this request does not send
images
string[]
Optional
Reference images to edit or combine. Name them in the prompt as @image_1, @image_2 … in list order.
Items: 1–10
Each item is a public https:// URL. For a local file, upload it first with POST /v1/files and pass the returned data.url.
- Each entry must be a public
https://link to a JPEG or PNG file. When you create the task, BeatAPI reads each link and refuses one that is not such an image, or that breaks the limits below, naming it by position (images[0]is the first link). imagesandelementsare at most 10 together.- Each link adds a fixed charge to the task (see Pricing).
If the value is wrong
- More than the maximum:
"images" accepts at most 10 items - An empty array:
"images" requires at least 1 item - Not an https:// link:
"images[0]" must be a public HTTPS URL - A link that is not a JPEG or PNG file (here a WebP):
"images[0]" is not a PNG or JPEG image: the URL returned image/webp - A link that answers with an error:
"images[0]" could not be downloaded: the URL returned HTTP 404 - More than 10 images and elements together:
Kling Image 4.0 takes at most 10 images and elements together
Example
elements
object[]
Optional
Named subjects, such as a character, an animal, a prop, a costume or a scene, each shown in 2 to 4 pictures and named in the prompt as @ followed by its name.
Items: ≤ 10
- An array of objects. Each object accepts these keys and no others:
elements[].name(string, required): 1 to 20 letters, digits, underscores or Chinese characters, unique within the request ignoring case. It cannot beimage_N,video_N,voice_N,keyframe_N,object_N,audio_N,first_frameorlast_frame.elements[].element_input_urls(array of strings, required): 2 to 4 public HTTPS links to pictures of the element; the first is its main view.elements[].tag(string, optional): what the element is.elements[].description(string, optional): what the element is, at most 100 characters.- Elements are pictures only: video and voice elements are not accepted on this model.
imagesandelementsare at most 10 together. Each element adds a fixed charge to the task, however many pictures it holds.
If the value is wrong
- More than ten elements:
"elements" accepts at most 10 items - An element that is not an object:
"elements[0]" must be an object - An element without
name:"name" is required in "elements[0]" - An element without
element_input_urls:"element_input_urls" is required in "elements[0]" - A
namethat is empty or longer than 20:"elements[0].name" has an unsupported length - A
namewith other characters, or a reserved name:elements[0].name "image_1" is not a name Kling V4 accepts - The same
nametwice, ignoring case:elements[1].name "Hero" is used twice - Fewer than two pictures:
"elements[0].element_input_urls" requires at least 2 item - More than four pictures:
"elements[0].element_input_urls" accepts at most 4 items - A
tagnot in the list:"elements[0].tag" must be one of: [character animal prop costume scene effect others] - A
descriptionlonger than 100 characters:"elements[0].description" has an unsupported length - A key that an element does not accept, such as a video:
field "element_input_video_urls" is not supported in "elements[0]"
Example
aspect_ratio
string
OptionalDefault: auto
Shape of the images as width:height.
Allowed values: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
Default: auto
- If you leave it out,
autois used: the model chooses the frame from the prompt and any images. Send a ratio when the shape matters.
If the value is wrong
- A value not in the list:
"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
OptionalDefault: 2K
Size class of the images: 2K, 4K or 8K. Each tier has its own price per image.
Allowed values: 2K, 4K, 8K
Default: 2K
- If you leave it out,
2Kis used and billed. - 2K and 4K images come back as PNG, 8K images as JPEG.
- Use the capital K:
2kis refused. There is no 1K tier, and pixel sizes such as2048x2048are not accepted.
If the value is wrong
- A value not in the list (for example
1Kor2k):"resolution" must be one of: [2K 4K 8K]
n
integer
OptionalDefault: 1
How many images to render in this task. Every image uses the same prompt, inputs, ratio and tier.
Default: 1
Range: 1–9
- If you leave it out,
1is used. - Each image is billed at the
resolutionprice, sonmultiplies the image part of the price. The charge for reference images and elements is counted once per task, not once per image. - The images are billed by the number delivered.
If the value is wrong
- Outside the range, not a whole number, or sent as a string:
"n" is outside its supported range
The gateway also checks these combinations before creating the task:
- n renders 1-9 images from one request; each image is billed at its resolution tier, and each image in images and each element is billed once more per request
- the prompt names images as @image_1, @image_2 … in order and elements as @ followed by their name; every @image_N must name an image of the same request
- an element is 2-4 images of one subject in element_input_urls, the first its main view; images and elements are at most 10 together
- element names are 1-20 letters, digits, underscores or Chinese characters, unique ignoring case, and not image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame or last_frame
- images are JPEG or PNG, up to 20 MB, between 2:5 and 5:2, and at most 8192 px on each side
- 2K and 4K come back as PNG, 8K as JPEG; aspect_ratio auto lets the model choose the frame from the prompt and any images
Input media limits
The gateway reads every input before the task is created and refuses one outside these limits with a 400 bad_request that names the input. Nothing is charged.
- The gateway reads every link in
imagesbefore the task is created and refuses one outside these limits with a message that names it, for exampleimages[0] has an aspect ratio of 3.10 (width/height); this model takes 0.4 to 2.5.Nothing is charged. - Element pictures (
element_input_urls) are only checked for being public HTTPS links before the task is created. Use JPEG or PNG files within the same limits. - Have a local file? Upload it with
POST /v1/filesand pass the returneddata.url.
Prompt mentions
Each input has its own mention:
- An
@image_Nwith no image behind it is refused when the task is created, for examplethe prompt names @image_2, which this request does not send.
Fields this model does not accept
The image endpoint knows a few fields that other image models use. Sending one of them here is refused instead of being ignored, so you never pay for a setting that had no effect:
output_format,quality,seed,background,size,enhance_prompt→field "output_format" is not supported by model kling-image-v4(with the field you sent).- Any other unknown field →
unknown field: <name>.
If a request has several bad fields, the message names only one of them; fix it and send again.
Request examples
Text to image
One 2K image from a prompt.
Four variations in one task
Four 4K images from the same prompt; each image is billed at the 4K price.
Edit one image
Recompose a product photo as a campaign image.
Combine several images
Name each reference in the prompt by its mention.
A named element
Show one subject from several angles as an element and place it by name.
Responses
Create a task (201)
The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.
Finished task
GET /v1/tasks/{task_id} returns HTTP 200 with status: "succeeded" and the result in data.output.
Output fields
Failed task
A failed task is still HTTP 200 on GET /v1/tasks/{task_id}: the failure is in the body. The reservation is returned in full, so nothing is charged.
Complete example
Create a task, wait for it with the server’s polling hint, and print the result URLs. Set BEATAPI_API_KEY in your environment and install requests.
Billing
- Each image is priced by
resolution(table below) and multiplied byn. Each link inimagesand each element inelementsadds a fixed charge once per task. - The price is reserved when the task is created, from your balance and from the key’s quota if it has one. A request refused before a task exists costs nothing.
- A succeeded task is billed by the number of images delivered. A failed task returns the reservation in full:
credits_refundedthen equalscredits_reserved, andcredits_chargedandcredits_settledare 0.
Current list prices, the same as on Pricing. An account with a negotiated discount pays less; data.usage on the task always shows the amount actually charged.
Common errors
HTTP errors at a glance
Errors before a task exists arrive as a non-2xx response, and nothing is charged. Branch on error.code or error.retryable; message names the problem. The full list and retry policy are on Errors.
Authentication
Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.
Headers
Send the body as JSON with Content-Type: application/json. Idempotency-Key is optional: send a unique value (at most 255 characters) per logical request and reuse it only to retry that exact body. Within 24 hours a retry with the same key and body returns the first response again with Idempotent-Replayed: true; the same key with a different body returns 409 idempotency_conflict. Responses other than 2xx are not stored, so a retry after a 400 or 402 runs again.
Request
The model to run.
Value: kling-image-v4
If the value is wrong
- Missing:
"model" is required - Unknown model ID:
"model" kling-image-v9 is not catalogued - A video model sent to this endpoint:
"model" kling-v4 is served by POST /v1/videos/tasks, not this endpoint
What to draw, or what to change in the reference images: subject, style, lighting, composition and any text that must appear, with each input named by its @ mention.
Length: 1–20000 characters
- Length is counted in characters (a CJK character counts as one).
- Mentions:
imagesare@image_1,@image_2… in list order, and an element is@followed by itsname. - Every
@image_Nmust name an image of the same request.@image_3with two images is refused when the task is created.
If the value is wrong
- Missing:
"prompt" is required - Empty or longer than the limit:
"prompt" has an unsupported length - A mention of an image the request does not send:
the prompt names @image_3, which this request does not send
Shape of the images as width:height.
Allowed values: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
Default: auto
- If you leave it out,
autois used: the model chooses the frame from the prompt and any images. Send a ratio when the shape matters.
If the value is wrong
- A value not in the list:
"aspect_ratio" must be one of: [auto 1:1 16:9 9:16 4:3 3:4 3:2 2:3 21:9]
Named subjects, such as a character, an animal, a prop, a costume or a scene, each shown in 2 to 4 pictures and named in the prompt as @ followed by its name.
Items: ≤ 10
- An array of objects. Each object accepts these keys and no others:
elements[].name(string, required): 1 to 20 letters, digits, underscores or Chinese characters, unique within the request ignoring case. It cannot beimage_N,video_N,voice_N,keyframe_N,object_N,audio_N,first_frameorlast_frame.elements[].element_input_urls(array of strings, required): 2 to 4 public HTTPS links to pictures of the element; the first is its main view.elements[].tag(string, optional): what the element is.elements[].description(string, optional): what the element is, at most 100 characters.- Elements are pictures only: video and voice elements are not accepted on this model.
imagesandelementsare at most 10 together. Each element adds a fixed charge to the task, however many pictures it holds.
If the value is wrong
- More than ten elements:
"elements" accepts at most 10 items - An element that is not an object:
"elements[0]" must be an object - An element without
name:"name" is required in "elements[0]" - An element without
element_input_urls:"element_input_urls" is required in "elements[0]" - A
namethat is empty or longer than 20:"elements[0].name" has an unsupported length - A
namewith other characters, or a reserved name:elements[0].name "image_1" is not a name Kling V4 accepts - The same
nametwice, ignoring case:elements[1].name "Hero" is used twice - Fewer than two pictures:
"elements[0].element_input_urls" requires at least 2 item - More than four pictures:
"elements[0].element_input_urls" accepts at most 4 items - A
tagnot in the list:"elements[0].tag" must be one of: [character animal prop costume scene effect others] - A
descriptionlonger than 100 characters:"elements[0].description" has an unsupported length - A key that an element does not accept, such as a video:
field "element_input_video_urls" is not supported in "elements[0]"
Example
"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"
]
}
]
Reference images to edit or combine. Name them in the prompt as @image_1, @image_2 … in list order.
Items: 1–10
Each item is a public https:// URL. For a local file, upload it first with POST /v1/files and pass the returned data.url.
- Each entry must be a public
https://link to a JPEG or PNG file. When you create the task, BeatAPI reads each link and refuses one that is not such an image, or that breaks the limits below, naming it by position (images[0]is the first link). imagesandelementsare at most 10 together.- Each link adds a fixed charge to the task (see Pricing).
If the value is wrong
- More than the maximum:
"images" accepts at most 10 items - An empty array:
"images" requires at least 1 item - Not an https:// link:
"images[0]" must be a public HTTPS URL - A link that is not a JPEG or PNG file (here a WebP):
"images[0]" is not a PNG or JPEG image: the URL returned image/webp - A link that answers with an error:
"images[0]" could not be downloaded: the URL returned HTTP 404 - More than 10 images and elements together:
Kling Image 4.0 takes at most 10 images and elements together
Example
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png",
"https://cdn.beatapi.io/samples/neon-singer.png"
]
How many images to render in this task. Every image uses the same prompt, inputs, ratio and tier.
Default: 1
Range: 1–9
- If you leave it out,
1is used. - Each image is billed at the
resolutionprice, sonmultiplies the image part of the price. The charge for reference images and elements is counted once per task, not once per image. - The images are billed by the number delivered.
If the value is wrong
- Outside the range, not a whole number, or sent as a string:
"n" is outside its supported range
Size class of the images: 2K, 4K or 8K. Each tier has its own price per image.
Allowed values: 2K, 4K, 8K
Default: 2K
- If you leave it out,
2Kis used and billed. - 2K and 4K images come back as PNG, 8K images as JPEG.
- Use the capital K:
2kis refused. There is no 1K tier, and pixel sizes such as2048x2048are not accepted.
If the value is wrong
- A value not in the list (for example
1Kor2k):"resolution" must be one of: [2K 4K 8K]
Response
The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

