> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Kling Image 4.0

POST https://api.beatapi.io/v1/images/tasks
Content-Type: application/json

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 itOpens 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
RequiredYour BeatAPI API key, sent as `Bearer <BEATAPI_API_KEY>`. Create keys in the [Dashboard](https://beatapi.io/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`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`.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](/webhooks) for `task.succeeded` and `task.failed`; keep polling as the fallback, because a task stopped by the processing timeout sends no event.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| Mode                   | Required inputs                                       | Notes                                                                                                                                         |
| ---------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Text to image          | `model`, `prompt`                                     | Leave out `images` and `elements`.                                                                                                            |
| Edit or combine images | `model`, `prompt`, and `images` or `elements` or both | Up 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 parametersmodel
string
RequiredThe 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
RequiredWhat 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[]
OptionalReference 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](/quick-guide#upload-an-input-file) 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**```json
"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png",
  "https://cdn.beatapi.io/samples/neon-singer.png"
]
```elements
object[]
OptionalNamed 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**```json
"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: autoShape 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: 2KSize 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: 1How 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 limitsThe 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.| Media  | Limits checked before the task is created                                                   |
| ------ | ------------------------------------------------------------------------------------------- |
| Images | width 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 mentionsEach input has its own mention:| Mention                  | Names                        | Available when                     |
| ------------------------ | ---------------------------- | ---------------------------------- |
| `@image_1`, `@image_2` … | `images`, in list order      | At least that many images are sent |
| `@` + element name       | The element with that `name` | The 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 acceptThe 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```bash title="cURL"
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"
}'
``````python title="Python"
import os
import requests

response = requests.post(
    "https://api.beatapi.io/v1/images/tasks",
    headers={"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"},
    json={
      "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"
    },
    timeout=60,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{response.status_code} {body['error']['code']}: {body['error']['message']}")
task = body["data"]
print(task["id"], task["status"])
``````javascript title="JavaScript"
const response = await fetch('https://api.beatapi.io/v1/images/tasks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BEATAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "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"
  }),
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status} ${body.error.code}: ${body.error.message}`);
console.log(body.data.id, body.data.status);
```### Text to imageOne 2K image from a prompt.```bash
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 taskFour 4K images from the same prompt; each image is billed at the 4K price.```bash
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 imageRecompose a product photo as a campaign image.```bash
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 imagesName each reference in the prompt by its mention.```bash
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 elementShow one subject from several angles as an element and place it by name.```bash
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.```json
{
  "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
  }
}
```| Field                                  | Type              | Description                                                                                                                              |
| -------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `data.id`                              | `string`          | Task ID: `task_` followed by 32 letters and digits. Use it to poll and to match webhook events.                                          |
| `data.object`                          | `string`          | Always `task`.                                                                                                                           |
| `data.task_kind`                       | `string`          | `image` or `video`.                                                                                                                      |
| `data.capability_id`                   | `string`          | The model ID you sent.                                                                                                                   |
| `data.capability_version`              | `integer`         | Contract version of the model, currently `1`.                                                                                            |
| `data.media_type`                      | `string`          | `image` or `video`.                                                                                                                      |
| `data.model`                           | `string`          | The model ID you sent (same as `capability_id`).                                                                                         |
| `data.status`                          | `string`          | `queued`, `processing`, `succeeded` or `failed`. Only the last two are final.                                                            |
| `data.stage`                           | `string`          | Repeats `status`; kept for older clients.                                                                                                |
| `data.created_at`                      | `integer`         | When the task was created, Unix seconds.                                                                                                 |
| `data.updated_at`                      | `integer`         | Last change, Unix seconds.                                                                                                               |
| `data.completed_at`                    | `integer \| null` | When the task finished, Unix seconds; `null` while it runs.                                                                              |
| `data.poll_after_seconds`              | `integer`         | While running: how long to wait before the next poll (5 for images, 8 for videos).                                                       |
| `data.typical_seconds`                 | `object`          | While running, when enough recent tasks exist: `p50` and `p90` completion times in seconds over the last `window`, from `samples` tasks. |
| `data.output`                          | `object \| null`  | The result; `null` until `status` is `succeeded`. See the output fields below.                                                           |
| `data.usage.credits_reserved`          | `number`          | USD held from your balance when the task was created.                                                                                    |
| `data.usage.credits_charged`           | `number`          | USD this task costs; `0` on a failed task.                                                                                               |
| `data.usage.credits_settled`           | `number`          | USD finally taken; set when the task succeeds, otherwise `0`.                                                                            |
| `data.usage.credits_refunded`          | `number`          | USD returned to your balance; equals the reservation on a failed task once the refund is recorded.                                       |
| `data.usage.billable_duration_seconds` | `integer`         | Video only: the seconds the price is based on. Absent when the model reports no duration.                                                |
| `data.request_id`                      | `string`          | Request ID. Include it when you contact support.                                                                                         |
| `data.error_code`                      | `string \| null`  | Failure code; `null` unless the task failed.                                                                                             |
| `data.error_message`                   | `string \| null`  | What 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`.```json
{
  "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| Field                      | Type       | Description                                                                            |
| -------------------------- | ---------- | -------------------------------------------------------------------------------------- |
| `output.media`             | `object[]` | The generated files: one item per image delivered, at most `n`.                        |
| `output.media[].type`      | `string`   | Always `image`.                                                                        |
| `output.media[].url`       | `string`   | HTTPS link to the stored image. Download and keep it; no retention period is promised. |
| `output.media[].mime_type` | `string`   | The stored file type: `image/png` for 2K and 4K, `image/jpeg` for 8K.                  |
| `output.r2_url`            | `string`   | The first media URL again, for older clients. Read `media` instead.                    |### Failed taskA 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.```json
{
  "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."
  }
}
```| Field                | Type      | Description                                                                                                                                                                                                            |
| -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.error_code`    | `string`  | One 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](/errors). |
| `data.error_message` | `string`  | A sentence that names the problem and the fix.                                                                                                                                                                         |
| `data.retryable`     | `boolean` | Present only on a failed task: `true` when the same request can succeed if you send it again.                                                                                                                          |
| `data.usage`         | `object`  | Once 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 exampleCreate 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`.```python
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](https://beatapi.io/pricing). An account with a negotiated discount pays less; `data.usage` on the task always shows the amount actually charged.| Option                                                                         | List 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 symptom                                                          | Cause                                                                                                          | Fix                                                                                     |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| 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 range`                                  | `n` 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 together`       | More 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 send`         | A 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 accepts`           | A 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/webp` | A 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-v4`      | A field from another image model (`output_format`, `seed`, `quality`, `size`, `background`, `enhance_prompt`). | Remove the field.                                                                       |
| Task `failed` with `content_policy_violation`                             | The 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_timeout`                                   | The images did not finish within the processing window.                                                        | Retry; the failed task was refunded.                                                    |
| 403 `forbidden` on an account that never topped up                        | Free credit covers only some models.                                                                           | Top up once, or use a model available on free credit.                                   |## HTTP errors at a glanceErrors 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](/errors).```json
{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}
```| HTTP status | `error.code`                                                                                  | What to do                                                                                                            |
| ----------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 400         | `bad_request`, `content_policy_violation`                                                     | Fix the request; the message names the field. Do not retry unchanged.                                                 |
| 401         | `missing_api_key`, `invalid_api_key` (older clients may see `unauthorized`)                   | Send a valid key as `Authorization: Bearer <key>`.                                                                    |
| 402         | `insufficient_credits`                                                                        | Top up, or raise the key’s quota, then send it again.                                                                 |
| 403         | `forbidden`                                                                                   | The key or account may not use this model (for example, free credit only covers some models). Do not retry unchanged. |
| 404         | `not_found`                                                                                   | On `GET /v1/tasks/{task_id}`: the task does not exist for this key’s account. Check the ID.                           |
| 409         | `idempotency_conflict`                                                                        | Use a new `Idempotency-Key`, or wait for the first request with this key to finish.                                   |
| 429         | `rate_limit_exceeded`                                                                         | Wait `Retry-After` seconds (also `error.retry_after_seconds`), then retry.                                            |
| 500         | `internal_error`                                                                              | Retry with backoff; contact support with `request_id` if it continues.                                                |
| 503         | `processing_unavailable`, `processing_timeout`, `processing_failed`, `result_transfer_failed` | Nothing was charged. Retry with exponential backoff.                                                                  |

Reference: https://docs.beatapi.io/api-reference/image-api/kling-image-v4

## Authentication

- `Authorization` header (bearer token, required) — Send your API key as `Authorization: Bearer <BEATAPI_API_KEY>`.

## Servers

- `https://api.beatapi.io` (Direct, default)
- `https://api.beatapi.io` (API)

## Request

### Headers

- `Idempotency-Key` (string, optional) — 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.

### Body (application/json)

This endpoint expects a KlingImageV4Request.

- `model` (enum, 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`
  - Allowed values: `kling-image-v4`
- `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`
- `aspect_ratio` (enum, optional, default: 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]`
  - Allowed values: `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`
- `elements` (list of KlingImageV4RequestElementsItems, 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** ```json "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" ] } ] ```
- `images` (list of 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](/quick-guide#upload-an-input-file) 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** ```json "images": [ "https://cdn.beatapi.io/samples/smart-bottle.png", "https://cdn.beatapi.io/samples/neon-singer.png" ] ```
- `n` (integer, optional, default: 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`
- `resolution` (enum, optional, default: 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: `2K`, `4K`, `8K`

## Response

### 201

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

- `map from string to any`

## Errors

### 400 Bad Request Error

`bad_request`, `content_policy_violation` Fix the request; the message names the field. Do not retry unchanged.

- `map from string to any`

### 401 Unauthorized Error

`missing_api_key`, `invalid_api_key` (older clients may see `unauthorized`) Send a valid key as `Authorization: Bearer <key>`.

- `map from string to any`

### 402 Payment Required Error

`insufficient_credits` Top up, or raise the key’s quota, then send it again.

- `map from string to any`

### 403 Forbidden Error

`forbidden` The key or account may not use this model (for example, free credit only covers some models). Do not retry unchanged.

- `map from string to any`

### 409 Conflict Error

`idempotency_conflict` Use a new `Idempotency-Key`, or wait for the first request with this key to finish.

- `map from string to any`

### 429 Too Many Requests Error

`rate_limit_exceeded` Wait `Retry-After` seconds (also `error.retry_after_seconds`), then retry.

- `map from string to any`

### 500 Internal Server Error

`internal_error` Retry with backoff; contact support with `request_id` if it continues.

- `map from string to any`

### 503 Service Unavailable Error

`processing_unavailable`, `processing_timeout`, `processing_failed`, `result_transfer_failed` Nothing was charged. Retry with exponential backoff.

- `map from string to any`

## Types

### KlingImageV4RequestElementsItems

- `element_input_urls` (list of string, required) — `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. **Items**: 2–4 Each item is a public `https://` URL. For a local file, [upload it first](/quick-guide#upload-an-input-file) with `POST /v1/files` and pass the returned `data.url`.
- `name` (string, required) — `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`. **Length**: 1–20 characters
- `description` (string, optional) — `elements[].description` (string, optional): what the element is, at most 100 characters. **Length**: ≤ 100 characters
- `tag` (enum, optional) — `elements[].tag` (string, optional): what the element is. **Allowed values**: `character`, `animal`, `prop`, `costume`, `scene`, `effect`, `others`
  - Allowed values: `character`, `animal`, `prop`, `costume`, `scene`, `effect`, `others`

## Examples

### Text to image

**Request**

```json
{
  "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"
}
```

**Response**

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

**SDK Code**

```python Text to image
import requests

url = "https://api.beatapi.io/v1/images/tasks"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Text to image
const url = 'https://api.beatapi.io/v1/images/tasks';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"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"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Text to image
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beatapi.io/v1/images/tasks"

	payload := strings.NewReader("{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement\",\n  \"aspect_ratio\": \"16:9\",\n  \"resolution\": \"2K\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Text to image
require 'uri'
require 'net/http'

url = URI("https://api.beatapi.io/v1/images/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement\",\n  \"aspect_ratio\": \"16:9\",\n  \"resolution\": \"2K\"\n}"

response = http.request(request)
puts response.read_body
```

```java Text to image
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.beatapi.io/v1/images/tasks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement\",\n  \"aspect_ratio\": \"16:9\",\n  \"resolution\": \"2K\"\n}")
  .asString();
```

```php Text to image
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beatapi.io/v1/images/tasks', [
  'body' => '{
  "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"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Text to image
using RestSharp;

var client = new RestClient("https://api.beatapi.io/v1/images/tasks");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement\",\n  \"aspect_ratio\": \"16:9\",\n  \"resolution\": \"2K\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Text to image
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "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"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beatapi.io/v1/images/tasks")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Four variations in one task

**Request**

```json
{
  "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",
  "n": 4,
  "resolution": "4K"
}
```

**Response**

```json
{
  "data": {
    "capability_id": "kling-image-v4",
    "capability_version": 1,
    "completed_at": null,
    "created_at": 1791993600,
    "error_code": null,
    "error_message": null,
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "media_type": "image",
    "model": "kling-image-v4",
    "object": "task",
    "output": null,
    "poll_after_seconds": 5,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "stage": "queued",
    "status": "queued",
    "task_kind": "image",
    "updated_at": 1791993600
  }
}
```

**SDK Code**

```python Four variations in one task
import requests

url = "https://api.beatapi.io/v1/images/tasks"

payload = {
    "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",
    "n": 4,
    "resolution": "4K"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Four variations in one task
const url = 'https://api.beatapi.io/v1/images/tasks';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"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","n":4,"resolution":"4K"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Four variations in one task
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beatapi.io/v1/images/tasks"

	payload := strings.NewReader("{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A minimalist poster of a lighthouse on a cliff at dawn, soft pastel colours, generous empty sky\",\n  \"aspect_ratio\": \"3:4\",\n  \"n\": 4,\n  \"resolution\": \"4K\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Four variations in one task
require 'uri'
require 'net/http'

url = URI("https://api.beatapi.io/v1/images/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A minimalist poster of a lighthouse on a cliff at dawn, soft pastel colours, generous empty sky\",\n  \"aspect_ratio\": \"3:4\",\n  \"n\": 4,\n  \"resolution\": \"4K\"\n}"

response = http.request(request)
puts response.read_body
```

```java Four variations in one task
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.beatapi.io/v1/images/tasks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A minimalist poster of a lighthouse on a cliff at dawn, soft pastel colours, generous empty sky\",\n  \"aspect_ratio\": \"3:4\",\n  \"n\": 4,\n  \"resolution\": \"4K\"\n}")
  .asString();
```

```php Four variations in one task
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beatapi.io/v1/images/tasks', [
  'body' => '{
  "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",
  "n": 4,
  "resolution": "4K"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Four variations in one task
using RestSharp;

var client = new RestClient("https://api.beatapi.io/v1/images/tasks");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A minimalist poster of a lighthouse on a cliff at dawn, soft pastel colours, generous empty sky\",\n  \"aspect_ratio\": \"3:4\",\n  \"n\": 4,\n  \"resolution\": \"4K\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Four variations in one task
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "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",
  "n": 4,
  "resolution": "4K"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beatapi.io/v1/images/tasks")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Edit one image

**Request**

```json
{
  "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"
}
```

**Response**

```json
{
  "data": {
    "capability_id": "kling-image-v4",
    "capability_version": 1,
    "completed_at": null,
    "created_at": 1791993600,
    "error_code": null,
    "error_message": null,
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "media_type": "image",
    "model": "kling-image-v4",
    "object": "task",
    "output": null,
    "poll_after_seconds": 5,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "stage": "queued",
    "status": "queued",
    "task_kind": "image",
    "updated_at": 1791993600
  }
}
```

**SDK Code**

```python Edit one image
import requests

url = "https://api.beatapi.io/v1/images/tasks"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Edit one image
const url = 'https://api.beatapi.io/v1/images/tasks';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"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"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Edit one image
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beatapi.io/v1/images/tasks"

	payload := strings.NewReader("{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"Keep the bottle in @image_1 exactly as it is. Place it on a sunlit kitchen counter with a soft reflection under it.\",\n  \"images\": [\n    \"https://cdn.beatapi.io/samples/smart-bottle.png\"\n  ],\n  \"resolution\": \"2K\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Edit one image
require 'uri'
require 'net/http'

url = URI("https://api.beatapi.io/v1/images/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"Keep the bottle in @image_1 exactly as it is. Place it on a sunlit kitchen counter with a soft reflection under it.\",\n  \"images\": [\n    \"https://cdn.beatapi.io/samples/smart-bottle.png\"\n  ],\n  \"resolution\": \"2K\"\n}"

response = http.request(request)
puts response.read_body
```

```java Edit one image
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.beatapi.io/v1/images/tasks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"Keep the bottle in @image_1 exactly as it is. Place it on a sunlit kitchen counter with a soft reflection under it.\",\n  \"images\": [\n    \"https://cdn.beatapi.io/samples/smart-bottle.png\"\n  ],\n  \"resolution\": \"2K\"\n}")
  .asString();
```

```php Edit one image
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beatapi.io/v1/images/tasks', [
  'body' => '{
  "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"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Edit one image
using RestSharp;

var client = new RestClient("https://api.beatapi.io/v1/images/tasks");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"Keep the bottle in @image_1 exactly as it is. Place it on a sunlit kitchen counter with a soft reflection under it.\",\n  \"images\": [\n    \"https://cdn.beatapi.io/samples/smart-bottle.png\"\n  ],\n  \"resolution\": \"2K\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Edit one image
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "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"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beatapi.io/v1/images/tasks")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Combine several images

**Request**

```json
{
  "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.",
  "aspect_ratio": "16:9",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "resolution": "2K"
}
```

**Response**

```json
{
  "data": {
    "capability_id": "kling-image-v4",
    "capability_version": 1,
    "completed_at": null,
    "created_at": 1791993600,
    "error_code": null,
    "error_message": null,
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "media_type": "image",
    "model": "kling-image-v4",
    "object": "task",
    "output": null,
    "poll_after_seconds": 5,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "stage": "queued",
    "status": "queued",
    "task_kind": "image",
    "updated_at": 1791993600
  }
}
```

**SDK Code**

```python Combine several images
import requests

url = "https://api.beatapi.io/v1/images/tasks"

payload = {
    "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.",
    "aspect_ratio": "16:9",
    "images": ["https://cdn.beatapi.io/samples/smart-bottle.png", "https://cdn.beatapi.io/samples/neon-singer.png"],
    "resolution": "2K"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Combine several images
const url = 'https://api.beatapi.io/v1/images/tasks';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"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.","aspect_ratio":"16:9","images":["https://cdn.beatapi.io/samples/smart-bottle.png","https://cdn.beatapi.io/samples/neon-singer.png"],"resolution":"2K"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Combine several images
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beatapi.io/v1/images/tasks"

	payload := strings.NewReader("{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"Place the bottle from @image_1 on a neon-lit stage like the one in @image_2. Keep the bottle label readable.\",\n  \"aspect_ratio\": \"16:9\",\n  \"images\": [\n    \"https://cdn.beatapi.io/samples/smart-bottle.png\",\n    \"https://cdn.beatapi.io/samples/neon-singer.png\"\n  ],\n  \"resolution\": \"2K\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Combine several images
require 'uri'
require 'net/http'

url = URI("https://api.beatapi.io/v1/images/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"Place the bottle from @image_1 on a neon-lit stage like the one in @image_2. Keep the bottle label readable.\",\n  \"aspect_ratio\": \"16:9\",\n  \"images\": [\n    \"https://cdn.beatapi.io/samples/smart-bottle.png\",\n    \"https://cdn.beatapi.io/samples/neon-singer.png\"\n  ],\n  \"resolution\": \"2K\"\n}"

response = http.request(request)
puts response.read_body
```

```java Combine several images
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.beatapi.io/v1/images/tasks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"Place the bottle from @image_1 on a neon-lit stage like the one in @image_2. Keep the bottle label readable.\",\n  \"aspect_ratio\": \"16:9\",\n  \"images\": [\n    \"https://cdn.beatapi.io/samples/smart-bottle.png\",\n    \"https://cdn.beatapi.io/samples/neon-singer.png\"\n  ],\n  \"resolution\": \"2K\"\n}")
  .asString();
```

```php Combine several images
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beatapi.io/v1/images/tasks', [
  'body' => '{
  "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.",
  "aspect_ratio": "16:9",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "resolution": "2K"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Combine several images
using RestSharp;

var client = new RestClient("https://api.beatapi.io/v1/images/tasks");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"Place the bottle from @image_1 on a neon-lit stage like the one in @image_2. Keep the bottle label readable.\",\n  \"aspect_ratio\": \"16:9\",\n  \"images\": [\n    \"https://cdn.beatapi.io/samples/smart-bottle.png\",\n    \"https://cdn.beatapi.io/samples/neon-singer.png\"\n  ],\n  \"resolution\": \"2K\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Combine several images
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "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.",
  "aspect_ratio": "16:9",
  "images": ["https://cdn.beatapi.io/samples/smart-bottle.png", "https://cdn.beatapi.io/samples/neon-singer.png"],
  "resolution": "2K"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beatapi.io/v1/images/tasks")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### A named element

**Request**

```json
{
  "model": "kling-image-v4",
  "prompt": "A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light",
  "aspect_ratio": "1:1",
  "elements": [
    {
      "element_input_urls": [
        "https://your-cdn.example.com/bottle-front.png",
        "https://your-cdn.example.com/bottle-side.png"
      ],
      "name": "Bottle",
      "tag": "prop"
    }
  ],
  "resolution": "2K"
}
```

**Response**

```json
{
  "data": {
    "capability_id": "kling-image-v4",
    "capability_version": 1,
    "completed_at": null,
    "created_at": 1791993600,
    "error_code": null,
    "error_message": null,
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "media_type": "image",
    "model": "kling-image-v4",
    "object": "task",
    "output": null,
    "poll_after_seconds": 5,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "stage": "queued",
    "status": "queued",
    "task_kind": "image",
    "updated_at": 1791993600
  }
}
```

**SDK Code**

```python A named element
import requests

url = "https://api.beatapi.io/v1/images/tasks"

payload = {
    "model": "kling-image-v4",
    "prompt": "A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light",
    "aspect_ratio": "1:1",
    "elements": [
        {
            "element_input_urls": ["https://your-cdn.example.com/bottle-front.png", "https://your-cdn.example.com/bottle-side.png"],
            "name": "Bottle",
            "tag": "prop"
        }
    ],
    "resolution": "2K"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript A named element
const url = 'https://api.beatapi.io/v1/images/tasks';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"model":"kling-image-v4","prompt":"A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light","aspect_ratio":"1:1","elements":[{"element_input_urls":["https://your-cdn.example.com/bottle-front.png","https://your-cdn.example.com/bottle-side.png"],"name":"Bottle","tag":"prop"}],"resolution":"2K"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go A named element
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beatapi.io/v1/images/tasks"

	payload := strings.NewReader("{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light\",\n  \"aspect_ratio\": \"1:1\",\n  \"elements\": [\n    {\n      \"element_input_urls\": [\n        \"https://your-cdn.example.com/bottle-front.png\",\n        \"https://your-cdn.example.com/bottle-side.png\"\n      ],\n      \"name\": \"Bottle\",\n      \"tag\": \"prop\"\n    }\n  ],\n  \"resolution\": \"2K\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby A named element
require 'uri'
require 'net/http'

url = URI("https://api.beatapi.io/v1/images/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light\",\n  \"aspect_ratio\": \"1:1\",\n  \"elements\": [\n    {\n      \"element_input_urls\": [\n        \"https://your-cdn.example.com/bottle-front.png\",\n        \"https://your-cdn.example.com/bottle-side.png\"\n      ],\n      \"name\": \"Bottle\",\n      \"tag\": \"prop\"\n    }\n  ],\n  \"resolution\": \"2K\"\n}"

response = http.request(request)
puts response.read_body
```

```java A named element
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.beatapi.io/v1/images/tasks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light\",\n  \"aspect_ratio\": \"1:1\",\n  \"elements\": [\n    {\n      \"element_input_urls\": [\n        \"https://your-cdn.example.com/bottle-front.png\",\n        \"https://your-cdn.example.com/bottle-side.png\"\n      ],\n      \"name\": \"Bottle\",\n      \"tag\": \"prop\"\n    }\n  ],\n  \"resolution\": \"2K\"\n}")
  .asString();
```

```php A named element
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beatapi.io/v1/images/tasks', [
  'body' => '{
  "model": "kling-image-v4",
  "prompt": "A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light",
  "aspect_ratio": "1:1",
  "elements": [
    {
      "element_input_urls": [
        "https://your-cdn.example.com/bottle-front.png",
        "https://your-cdn.example.com/bottle-side.png"
      ],
      "name": "Bottle",
      "tag": "prop"
    }
  ],
  "resolution": "2K"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp A named element
using RestSharp;

var client = new RestClient("https://api.beatapi.io/v1/images/tasks");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model\": \"kling-image-v4\",\n  \"prompt\": \"A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light\",\n  \"aspect_ratio\": \"1:1\",\n  \"elements\": [\n    {\n      \"element_input_urls\": [\n        \"https://your-cdn.example.com/bottle-front.png\",\n        \"https://your-cdn.example.com/bottle-side.png\"\n      ],\n      \"name\": \"Bottle\",\n      \"tag\": \"prop\"\n    }\n  ],\n  \"resolution\": \"2K\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift A named element
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "model": "kling-image-v4",
  "prompt": "A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light",
  "aspect_ratio": "1:1",
  "elements": [
    [
      "element_input_urls": ["https://your-cdn.example.com/bottle-front.png", "https://your-cdn.example.com/bottle-side.png"],
      "name": "Bottle",
      "tag": "prop"
    ]
  ],
  "resolution": "2K"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beatapi.io/v1/images/tasks")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```