> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kling V4 Image Generation

> Generate images from text or up to 10 reference images, or create a related series of 2–4 images. Standard mode outputs 1–9 images per request in 2K / 4K / 8K PNG.

```bash cURL theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "nsfw_check": true
}'
```

```python Python theme={null}
import requests

payload = {
  "model": "kling-v4-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "nsfw_check": True
}
response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const payload = {
  "model": "kling-v4-image",
  "prompt": "An orange cat sitting on a windowsill in warm afternoon sunlight, realistic photography",
  "size": "1:1",
  "resolution": "2K",
  "n": 1,
  "nsfw_check": true
};
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example_kling_v4_image"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "message": "`prompt` is required for kling-v4-image",
    "type": "invalid_request_error"
  }
}
```

Submit an asynchronous request with `model: "kling-v4-image"` to `POST /v1/images/generations`. Read `data[0].task_id`, then query `GET /v1/tasks/{task_id}` for the result.

## Authentication

**Authorization** `string` *required*

Use `Authorization: Bearer <token>`, where `<token>` is your APIMart API key.

## Request parameters

**model** `string` *required*

Must be `kling-v4-image`.

**nsfw\_check** `boolean` (default: false)

Whether to run content moderation before submitting the image task.

* `true`: use `omni-moderation-latest` to review prompts and input images
* `false` or omitted: do not send a moderation request, adding no moderation cost or latency (default)

**prompt** `string` *required*

Required for text-to-image, image-to-image, and series generation. Describe both desired and unwanted content here. Limits are 50,000 characters for English-only text and 21,000 for Chinese-only text and similar languages; mixed-language limits are proportional.

**image\_urls** `string[]`

Up to 10 reference images, supplied as publicly accessible direct image URLs. For local files, use the [image upload API](https://docs.apimart.ai/en/api-reference/uploads/images.md) first and pass the returned `url`.

Supports JPG / JPEG / PNG / GIF. Each image must be at most 30 MB, at least 300 px in both width and height, and have an aspect ratio from 2:5 to 5:2.

Reference images are checked at submission. A URL returning HTTP 403 / 404 / 410, either dimension below 300 px, a ratio outside 2:5–5:2, or an image larger than 30 MB returns HTTP 400 immediately, without creating a task or charging for generation. Other fetch failures, such as an origin timeout, are accepted initially; the task then fails and prepaid generation charges are fully refunded.

Use `@Image1`, `@Image2`, and so on in the prompt to refer to images in array order. Images are still used as references without these markers.

**n** `integer` (default: 1)

Number of outputs in standard mode: an integer from 1 to 9, default 1. In series mode, omit `n` or set it to `1`; `sequential_image_generation_options.max_images` determines the output count. Passing `n > 1` in series mode returns HTTP 400.

**resolution** `string` (default: 2K)

Supports `2K` (default), `4K`, and `8K`, case-insensitive, with PNG output. At `1:1`, 2K is `2048×2048`, 4K is `4096×4096`, and 8K is `8192×8192`; for other ratios, use the actual dimensions of the returned images.

8K supports text-to-image, image-to-image, and series generation: 1–9 outputs in standard mode, 2–4 in series mode, and up to 10 reference images. Reference image formats, dimensions, and the 30 MB per-image limit remain unchanged.

**size** `string` (default: auto)

Output aspect ratio. Supports `auto` (default) and these 8 explicit ratios:

`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`.

`auto` chooses a ratio from the prompt or reference images. Pixel dimensions such as `2048x2048` are not supported.

**aspect\_ratio** `string`

Alias for `size`, with the same accepted values. If both are provided, `aspect_ratio` takes precedence.

**sequential\_image\_generation** `string` (default: disabled)

Use `disabled` or omit this field for standard generation. Set it to `auto` to generate related images as a series; `sequential_image_generation_options.max_images` is then required. Here, `auto` does not choose the image count automatically.

**sequential\_image\_generation\_options** `object`

Specifies the image count in series mode.

**Properties**

**max\_images** `integer`

Required in series mode: an integer from 2 to 4 specifying the requested output count. Omitting it, passing the string `"auto"`, or using an out-of-range value returns HTTP 400.

> [!WARNING]
>
> `width`, `height`, `mask_url`, pixel-based `size`, and `watermark: true` are not supported and return HTTP 400.

## Request examples

Send these requests to `POST /v1/images/generations`. Replace example image URLs with accessible direct links.

### Image-to-image

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "Use the dog in @Image1 as a reference for a 3D animated character poster, preserving its fur color and features",
  "image_urls": [
    "https://example.com/dog.png"
  ],
  "size": "3:4",
  "resolution": "2K"
}'
```

### Generate three 4K images

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "A quiet mountain lake at sunrise, detailed landscape photography",
  "size": "16:9",
  "resolution": "4K",
  "n": 3
}'
```

### Generate one 8K image

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "A sweeping aerial view of a misty mountain valley at sunrise",
  "resolution": "8K",
  "size": "16:9",
  "n": 1
}'
```

### Generate a series of four related 8K images

Set `max_images` to 2–4. In series mode, `n` may be omitted or set to `1`, but cannot exceed `1`. A series may take several minutes; keep the `task_id` and poll its status instead of submitting duplicate requests.

```bash theme={null}
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4-image",
  "prompt": "The same tree in spring, summer, autumn, and winter, consistent picture-book style",
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {
    "max_images": 4
  },
  "size": "3:4",
  "resolution": "8K"
}'
```

## 8K output and timing examples

These measurements are samples from the test environment. Dimensions, file sizes, and completion times are illustrative; actual results may vary.

| 8K request | Output dimensions | File size per image | Completion time |
| - | - | - | - |
| 1 standard image (16:9) | `10880×6144` | 117 MB | About 2.5 minutes |
| 4 / 9 standard images (1:1) | `8192×8192` | 100–130 MB | About 3 minutes |
| 4-image series (3:4) | `7040×9344` | 77–104 MB | About 6 minutes |

Poll every 5–10 seconds until `completed` or `failed`. `estimated_time` is fixed at 60 seconds and must not be used as an actual completion estimate or countdown. Keep the `task_id` and avoid resubmitting while waiting.

8K results are original PNG images, and a single file can exceed 100 MB. For lists and previews, use thumbnails you generate or load images on demand. Provide an original-file download option and indicate the large file size.

## Query the task

Use the [task query API](https://docs.apimart.ai/en/api-reference/tasks/status.md) and read `data.status`: `pending` / `processing` means the task is running, `completed` means success, and `failed` provides details in `data.error.message`.

```bash theme={null}
curl --request GET \
  --url 'https://api.apimart.ai/v1/tasks/task_example_kling_v4_image' \
  --header 'Authorization: Bearer <token>'
```

The following illustrates a successful result. Image URLs are in `data.result.images[].url[]`; `url` is an array. Iterate through all outputs and download them promptly.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_kling_v4_image",
    "status": "completed",
    "result": {
      "images": [
        {
          "url": [
            "https://example.com/generated-image.png"
          ]
        }
      ]
    }
  }
}
```

## Billing

Charges depend on the actual image count and selected resolution tier. Reference images are charged separately per image. See the [pricing page](https://apimart.ai/pricing) for current rates.

| Billing item | Price key |
| - | - |
| Each 2K output image | `kling-v4-image@2K` |
| Each 4K output image | `kling-v4-image@4K` |
| Each 8K output image | `kling-v4-image@8K` |
| Each input reference image | `kling-v4-image@input` |

* Standard generation with `n=3` is billed for 3 outputs; series generation is billed for the actual returned count.
* Each reference image is counted once per request, regardless of output count. For example, generating 3 images from 2 references incurs 2 input-image charges and 3 output-image charges.
* Failed generation tasks are not charged; prepaid generation charges are fully refunded.

## Common parameter errors

These parameter errors return HTTP 400 synchronously at submission, without creating a task or charging for generation. Read `error.message` for submission errors and `data.error.message` for failures after task creation.

| Error excerpt | Resolution |
| - | - |
| `` `prompt` is required for kling-v4-image `` | Provide a non-empty prompt. |
| `` `n` must be an integer between 1 and 9 `` | Use an integer from 1 to 9 for `n`. |
| `` `n` cannot be combined with sequential_image_generation=auto `` | Omit `n` or set it to `1` in series mode; use `max_images` to control the output count. |
| `` `sequential_image_generation_options.max_images` is required for kling-v4-image series mode `` | Provide `max_images` when enabling series generation. |
| `` `sequential_image_generation_options.max_images` must be an integer between 2 and 4 `` | Use an integer from 2 to 4, not `"auto"`. |
| `` `resolution` must be 2K, 4K or 8K for kling-v4-image `` | Use `2K`, `4K`, or `8K`; values are case-insensitive. |
| `` `size` must be auto or one of 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9 `` | Use `auto` or a supported ratio, not pixel dimensions. |
| `kling-v4-image supports at most 10 reference images` | Provide no more than 10 reference images. |
| `reference image is not accessible for kling-v4-image` | The reference URL returned 403 / 404 / 410. Check that it is public and still valid, or upload the image again. |
| `unsupported reference image dimensions for kling-v4-image` | Both dimensions must be at least 300 px, with a ratio from 2:5 to 5:2. Ratio violations use the same error prefix. |
| `reference image too large for kling-v4-image` | Each reference image must be at most 30 MB. Compress it before submitting again. |
| `` `n` must be an integer between 1 and 9 for kling-v4-image (got: "3") `` | Use a JSON integer such as `"n": 3`, not the string `"3"`. Other fields must also use their declared string, array, or boolean types. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.