Skip to navigation

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 its resolution tier.
  • Text to image, or edit and combine up to 10 reference images and named elements together, given as public HTTPS links.
  • Name inputs in the prompt: @image_1, @image_2 … for images in 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.
POST/v1/images/tasksTry it

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

1

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.

2

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.

3

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

ModeRequired inputsNotes
Text to imagemodel, promptLeave out images and elements.
Edit or combine imagesmodel, prompt, and images or elements or bothUp to 10 reference images and elements together. Name each one in prompt: @image_1 for the first image, @ plus the name for an element.

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: images are @image_1, @image_2 … in list order, and an element is @ followed by its name.
  • Every @image_N must name an image of the same request. @image_3 with 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).
  • images and elements are 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"
]

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 be image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame or last_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.
  • images and elements are 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 name that is empty or longer than 20: "elements[0].name" has an unsupported length
  • A name with other characters, or a reserved name: elements[0].name "image_1" is not a name Kling V4 accepts
  • The same name twice, 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 tag not in the list: "elements[0].tag" must be one of: [character animal prop costume scene effect others]
  • A description longer 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"
]
}
]

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, auto is 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, 2K is used and billed.
  • 2K and 4K images come back as PNG, 8K images as JPEG.
  • Use the capital K: 2k is refused. There is no 1K tier, and pixel sizes such as 2048x2048 are not accepted.

If the value is wrong

  • A value not in the list (for example 1K or 2k): "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, 1 is used.
  • Each image is billed at the resolution price, so n multiplies 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.

MediaLimits checked before the task is created
Imageswidth and height at most 8192 px; aspect ratio (width ÷ height) 0.4–2.5; at most 20 MB each
  • The gateway reads every link in images before the task is created and refuses one outside these limits with a message that names it, for example images[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/files and pass the returned data.url.

Prompt mentions

Each input has its own mention:

MentionNamesAvailable when
@image_1, @image_2 …images, in list orderAt least that many images are sent
@ + element nameThe element with that nameThe element is in elements
  • An @image_N with no image behind it is refused when the task is created, for example the 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

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement",
"aspect_ratio": "16:9",
"resolution": "2K"
}'

Text to image

One 2K image from a prompt.

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement",
"aspect_ratio": "16:9",
"resolution": "2K"
}'

Four variations in one task

Four 4K images from the same prompt; each image is billed at the 4K price.

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "A minimalist poster of a lighthouse on a cliff at dawn, soft pastel colours, generous empty sky",
"aspect_ratio": "3:4",
"resolution": "4K",
"n": 4
}'

Edit one image

Recompose a product photo as a campaign image.

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "Keep the bottle in @image_1 exactly as it is. Place it on a sunlit kitchen counter with a soft reflection under it.",
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png"
],
"resolution": "2K"
}'

Combine several images

Name each reference in the prompt by its mention.

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "Place the bottle from @image_1 on a neon-lit stage like the one in @image_2. Keep the bottle label readable.",
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png",
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"aspect_ratio": "16:9",
"resolution": "2K"
}'

A named element

Show one subject from several angles as an element and place it by name.

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light",
"elements": [
{
"name": "Bottle",
"tag": "prop",
"element_input_urls": [
"https://your-cdn.example.com/bottle-front.png",
"https://your-cdn.example.com/bottle-side.png"
]
}
],
"aspect_ratio": "1:1",
"resolution": "2K"
}'

Responses

Create a task (201)

The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "image",
"capability_id": "kling-image-v4",
"capability_version": 1,
"media_type": "image",
"model": "kling-image-v4",
"status": "queued",
"stage": "queued",
"created_at": 1791993600,
"updated_at": 1791993600,
"completed_at": null,
"poll_after_seconds": 5,
"output": null,
"usage": {
"credits_reserved": 0.0593,
"credits_settled": 0,
"credits_refunded": 0,
"credits_charged": 0.0593
},
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": null,
"error_message": null
}
}
FieldTypeDescription
data.idstringTask ID: task_ followed by 32 letters and digits. Use it to poll and to match webhook events.
data.objectstringAlways task.
data.task_kindstringimage or video.
data.capability_idstringThe model ID you sent.
data.capability_versionintegerContract version of the model, currently 1.
data.media_typestringimage or video.
data.modelstringThe model ID you sent (same as capability_id).
data.statusstringqueued, processing, succeeded or failed. Only the last two are final.
data.stagestringRepeats status; kept for older clients.
data.created_atintegerWhen the task was created, Unix seconds.
data.updated_atintegerLast change, Unix seconds.
data.completed_atinteger | nullWhen the task finished, Unix seconds; null while it runs.
data.poll_after_secondsintegerWhile running: how long to wait before the next poll (5 for images, 8 for videos).
data.typical_secondsobjectWhile running, when enough recent tasks exist: p50 and p90 completion times in seconds over the last window, from samples tasks.
data.outputobject | nullThe result; null until status is succeeded. See the output fields below.
data.usage.credits_reservednumberUSD held from your balance when the task was created.
data.usage.credits_chargednumberUSD this task costs; 0 on a failed task.
data.usage.credits_settlednumberUSD finally taken; set when the task succeeds, otherwise 0.
data.usage.credits_refundednumberUSD returned to your balance; equals the reservation on a failed task once the refund is recorded.
data.usage.billable_duration_secondsintegerVideo only: the seconds the price is based on. Absent when the model reports no duration.
data.request_idstringRequest ID. Include it when you contact support.
data.error_codestring | nullFailure code; null unless the task failed.
data.error_messagestring | nullWhat went wrong and what to change; null unless the task failed.

Finished task

GET /v1/tasks/{task_id} returns HTTP 200 with status: "succeeded" and the result in data.output.

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

Output fields

FieldTypeDescription
output.mediaobject[]The generated files: one item per image delivered, at most n.
output.media[].typestringAlways image.
output.media[].urlstringHTTPS link to the stored image. Download and keep it; no retention period is promised.
output.media[].mime_typestringThe stored file type: image/png for 2K and 4K, image/jpeg for 8K.
output.r2_urlstringThe first media URL again, for older clients. Read media instead.

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.

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "image",
"capability_id": "kling-image-v4",
"capability_version": 1,
"media_type": "image",
"model": "kling-image-v4",
"status": "failed",
"stage": "failed",
"created_at": 1791993600,
"updated_at": 1791993690,
"completed_at": 1791993690,
"output": null,
"usage": {
"credits_reserved": 0.0593,
"credits_settled": 0,
"credits_refunded": 0.0593,
"credits_charged": 0
},
"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."
}
}
FieldTypeDescription
data.error_codestringOne of bad_request and content_policy_violation (change the request) or processing_unavailable, processing_timeout, processing_failed and result_transfer_failed (try again later). See Errors.
data.error_messagestringA sentence that names the problem and the fix.
data.retryablebooleanPresent only on a failed task: true when the same request can succeed if you send it again.
data.usageobjectOnce the refund is recorded (normally at the moment the task fails): credits_charged and credits_settled are 0, and credits_refunded equals credits_reserved.

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.

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/images/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-image-v4",
"prompt": "A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement",
"aspect_ratio": "16:9",
"resolution": "2K"
})
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"])

Billing

  • Each image is priced by resolution (table below) and multiplied by n. Each link in images and each element in elements adds 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_refunded then equals credits_reserved, and credits_charged and credits_settled are 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.

OptionList price (USD)
1 image · 2K$0.0593
1 image · 4K$0.0893
1 image · 8K$0.1486
Each reference image in images and each element in elements, once per task$0.0026

Common errors

Error or symptomCauseFix
400 "resolution" must be one of: [2K 4K 8K]1K, lower-case 2k, or a pixel size such as 2048x2048.Send 2K, 4K or 8K, or leave the field out.
400 "n" is outside its supported rangen above 9, below 1, a fraction or a string.Send a whole number from 1 to 9; for more images, create another task.
400 Kling Image 4.0 takes at most 10 images and elements togetherMore than 10 entries across images and elements.Send at most 10 in total; group several pictures of one subject into one element.
400 the prompt names @image_3, which this request does not sendA mention numbered past the last link in images.Number mentions from @image_1 in list order, or add the missing image.
400 elements[0].name "image_1" is not a name Kling V4 acceptsA reserved name or a name with spaces, hyphens or other symbols.Use 1 to 20 letters, digits, underscores or Chinese characters, such as Bottle.
400 "images[0]" is not a PNG or JPEG image: the URL returned image/webpA WebP, GIF or HEIC file, or a link that returns a web page.Convert the file to JPEG or PNG, or upload it with POST /v1/files and use data.url.
400 field "output_format" is not supported by model kling-image-v4A field from another image model (output_format, seed, quality, size, background, enhance_prompt).Remove the field.
Task failed with content_policy_violationThe prompt, a reference image or the generated image was refused by moderation.Change the prompt or the image. Retrying unchanged fails again; nothing is charged.
Task failed with processing_timeoutThe images did not finish within the processing window.Retry; the failed task was refunded.
403 forbidden on an account that never topped upFree credit covers only some models.Top up once, or use a model available on free credit.

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.

{
"error": {
"code": "bad_request",
"message": "\"prompt\" is required",
"retryable": false,
"request_id": "req_5f0c2a9e4b7d4e31"
}
}
HTTP statuserror.codeWhat to do
400bad_request, content_policy_violationFix the request; the message names the field. Do not retry unchanged.
401missing_api_key, invalid_api_key (older clients may see unauthorized)Send a valid key as Authorization: Bearer <key>.
402insufficient_creditsTop up, or raise the key’s quota, then send it again.
403forbiddenThe key or account may not use this model (for example, free credit only covers some models). Do not retry unchanged.
404not_foundOn GET /v1/tasks/{task_id}: the task does not exist for this key’s account. Check the ID.
409idempotency_conflictUse a new Idempotency-Key, or wait for the first request with this key to finish.
429rate_limit_exceededWait Retry-After seconds (also error.retry_after_seconds), then retry.
500internal_errorRetry with backoff; contact support with request_id if it continues.
503processing_unavailable, processing_timeout, processing_failed, result_transfer_failedNothing was charged. Retry with exponential backoff.

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Headers

Idempotency-KeystringOptional<=255 characters

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

This endpoint expects an object.
modelenumRequired

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
Allowed values:
promptstringRequired1-20000 characters

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: images are @image_1, @image_2 … in list order, and an element is @ followed by its name.
  • Every @image_N must name an image of the same request. @image_3 with 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
aspect_ratioenumOptionalDefaults to 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, auto is 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]
elementslist of objectsOptional

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 be image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame or last_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.
  • images and elements are 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 name that is empty or longer than 20: "elements[0].name" has an unsupported length
  • A name with other characters, or a reserved name: elements[0].name "image_1" is not a name Kling V4 accepts
  • The same name twice, 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 tag not in the list: "elements[0].tag" must be one of: [character animal prop costume scene effect others]
  • A description longer 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"
    ]
  }
]
imageslist of stringsOptional

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).
  • images and elements are 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"
]
nintegerOptional1-9Defaults to 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, 1 is used.
  • Each image is billed at the resolution price, so n multiplies 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
resolutionenumOptionalDefaults to 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, 2K is used and billed.
  • 2K and 4K images come back as PNG, 8K images as JPEG.
  • Use the capital K: 2k is refused. There is no 1K tier, and pixel sizes such as 2048x2048 are not accepted.

If the value is wrong

  • A value not in the list (for example 1K or 2k): "resolution" must be one of: [2K 4K 8K]
Allowed values:

Response

The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

Errors

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