> ## 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 Long Image Generation

> Generate tall product detail images or webpage designs in 1K / 2K. Supports short, medium, and long ecommerce layouts and product, style, and subject references. Returns one PNG per request.

```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-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "nsfw_check": true
}'
```

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

payload = {
  "model": "kling-v4-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "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-long-image",
  "skill": "ecommerce",
  "prompt": "Create a product detail page for the coffee maker in @Image1, with a hero section, key features, and everyday use scenes",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "length": "medium",
  "resolution": "1K",
  "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_long_image"
    }
  ]
}
```

```json 400 theme={null}
{
  "error": {
    "code": "invalid_request_error",
    "message": "reference image is not accessible for kling-v4-long-image: image_urls[0] returned HTTP 404; make sure the URL is public and still valid",
    "param": "",
    "type": "invalid_request_error"
  }
}
```

Submit an asynchronous request to `POST /v1/images/generations` with `model: "kling-v4-long-image"`. Read `data[0].task_id`, then query `GET /v1/tasks/{task_id}`. Each request returns one tall PNG; webpage mode produces a webpage design image.

## Choose a mode

| Mode | `skill` | References | Length |
| - | - | - | - |
| Product detail page | `ecommerce` | `image_urls`: 1–3 product images required | `short` / `medium` / `long` |
| Webpage design | `webpage` | `image_with_roles`: optional style and subject images, at most one of each | Omit `length` |

## Authentication

**Authorization** `string` *required*

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

## Request parameters

**model** `string` *required*

Must be `kling-v4-long-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 and must not be blank. Limits are 166,000 characters for English-only text and 71,000 for Chinese-only text and similar languages; mixed-language limits are proportional. Describe the layout, sections, copy, style, and subject.

**skill** `string` *required*

Required: `ecommerce` for product detail pages or `webpage` for webpage designs, case-insensitive. The modes use different reference-image fields as shown above.

**length** `string` (default: medium)

Only for `skill: "ecommerce"`: `short`, `medium` (default), or `long`, roughly corresponding to 2–5, 6–10, or 11–18 content sections. Actual content and height depend on generation. Omit this field in webpage mode; sending it returns HTTP 400.

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

Supports `1K` (default) and `2K`, case-insensitive. Both resolutions support every ecommerce length, including `long + 2K`. Output widths are 1024 px and 2048 px respectively; height depends on content. `4K` is not supported.

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

Only for ecommerce: 1–3 product images are required. Omit this field in webpage mode and use `image_with_roles`. Supply publicly accessible direct image URLs. For local files, use the [image upload API](https://docs.apimart.ai/en/api-reference/uploads/images.md) and pass the returned `url`.

**image\_with\_roles** `object[]`

Only for webpage mode; optional. Provide at most one `style` image and one `subject` image. Either or both may be omitted. Omit this field in ecommerce mode.

**Array item**

**url** `string` *required*

A publicly accessible direct reference-image URL.

**role** `string` *required*

`style` guides visual and layout style; `subject` identifies the subject to preserve. Each role may appear only once.

**n** `integer`

Each request generates one tall image. Omit this field or use the integer `1`; other values return HTTP 400.

**watermark** `boolean`

Omit this field or use `false`; `true` returns HTTP 400.

> [!WARNING]
>
> Do not send `size`, `aspect_ratio`, `width`, `height`, `mask_url`, `sequential_image_generation`, or `sequential_image_generation_options`. These fields return HTTP 400 even when set to `null` or an empty string.

## Reference requirements and prompt markers

Supports JPG / JPEG / PNG. Each image must be at most 30 MB, at least 300 px in both dimensions, and have a ratio from 2:5 to 5:2. A URL returning HTTP 403 / 404 / 410, invalid dimensions or ratio, or an oversized file returns HTTP 400 synchronously, 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 charges are refunded.

Use `@Image1`, `@Image2`, and so on in the prompt. Ecommerce numbers images in `image_urls` order; webpage numbers them in style-then-subject order. If only one role is supplied, its image is `@Image1`.

## Request examples

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

### Long ecommerce layout in 2K

```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-long-image",
  "skill": "ecommerce",
  "prompt": "Create a long product detail page using the front view in @Image1, side view in @Image2, and close-up in @Image3. Include key features, materials, use scenes, and care instructions.",
  "image_urls": [
    "https://example.com/product-front.jpg",
    "https://example.com/product-side.jpg",
    "https://example.com/product-detail.png"
  ],
  "length": "long",
  "resolution": "2K"
}'
```

### Webpage with style and subject references

```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-long-image",
  "skill": "webpage",
  "prompt": "Design a product landing page using the visual style of @Image1 and preserving the product in @Image2. Include a hero section, features, and a call to action.",
  "image_with_roles": [
    {
      "url": "https://example.com/style.png",
      "role": "style"
    },
    {
      "url": "https://example.com/product.jpg",
      "role": "subject"
    }
  ],
  "resolution": "2K"
}'
```

### Webpage from a prompt only

```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-long-image",
  "skill": "webpage",
  "prompt": "Design a welcoming coffee shop webpage with warm colors, a hero section, a menu, and store information",
  "resolution": "1K"
}'
```

## Query the task

Poll the [task query API](https://docs.apimart.ai/en/api-reference/tasks/status.md), preferably every 10 seconds. Keep the `task_id` and avoid duplicate generation requests during a long wait.

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

| Status (`data.status`) | Handling |
| - | - |
| `pending` / `processing` | Continue polling. `data.cost` is the prepaid amount and `data.billing_status` is `held`. |
| `completed` | Read `data.result.images[0].url[0]`. `data.billing_status` is `settled` and `data.cost` is the final charge. |
| `failed` | Read `data.error.message`. `data.billing_status` is `refunded` and `data.cost` is `0`; prepaid charges are fully refunded. |

The following illustrates a successful result. Both `images` and `url` are arrays; this model returns one tall image per request.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_example_kling_v4_long_image",
    "status": "completed",
    "progress": 100,
    "billing_status": "settled",
    "result": {
      "images": [
        {
          "url": [
            "https://example.com/generated-long-image.png"
          ],
          "expires_at": 1795331293
        }
      ]
    }
  }
}
```

Download the image before the Unix timestamp in seconds given by `data.result.images[0].expires_at`; the link expires afterward.

> [!NOTE]
>
> Generation usually takes several minutes; one `long + 2K` sample took 432 seconds. `estimated_time` currently always returns 60 seconds and must not be used as a countdown or timeout threshold. Timing varies with content and service load; the sample is not an upper bound.
>
> Image height and file size vary with content. One `long + 2K` sample was `2048×46615` and 63.9 MB; these are examples, not output limits. Results can exceed 50 MB, so account for large-image download and display costs.

## Billing

Each request is billed for one tall image at the selected output tier, plus reference images: **output tier price + reference count × reference image price**. Product, style, and subject images all count; the first reference is also charged.

There are 8 output tiers below. Price keys are `kling-v4-long-image@<tier>` and `kling-v4-long-image@input` for references. These are billing tiers; the generation request still uses only `1K` or `2K` for `resolution`.

| Mode | Length | `1K` | `2K` |
| - | - | - | - |
| Product detail page | `short` | `1K-SHORT` | `2K-SHORT` |
| Product detail page | `medium` | `1K-MEDIUM` | `2K-MEDIUM` |
| Product detail page | `long` | `1K-LONG` | `2K-LONG` |
| Webpage design | Omit `length` | `1K-WEBPAGE` | `2K-WEBPAGE` |

Charges are reserved at submission, settled on success, and fully refunded on failure. See the [pricing page](https://apimart.ai/pricing) for rates and account discounts.

## Common errors

These validation errors return HTTP 400 synchronously, 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-long-image `` | Provide a non-empty prompt. |
| `` `skill` is required for kling-v4-long-image `` | Provide `skill`. |
| `` `skill` must be ecommerce or webpage for kling-v4-long-image `` | Use `ecommerce` or `webpage`. |
| `` skill=ecommerce on kling-v4-long-image requires 1 to 3 product images in `image_urls` `` | Ecommerce requires 1–3 product images. |
| `` skill=ecommerce on kling-v4-long-image supports at most 3 product images in `image_urls` `` | Provide no more than 3 product images. |
| `` `image_with_roles` is only for skill=webpage on kling-v4-long-image `` | For ecommerce, use `image_urls` and omit `image_with_roles`. |
| `` `length` must be short, medium or long for kling-v4-long-image `` | Use `short`, `medium`, or `long` for ecommerce. |
| `` `length` only applies to skill=ecommerce for kling-v4-long-image `` | Omit `length` in webpage mode. |
| `` skill=webpage on kling-v4-long-image does not take `image_urls` `` | For webpage, omit `image_urls` and use `image_with_roles`. |
| `` `image_with_roles[0].role` must be style or subject for kling-v4-long-image `` | Use only `style` or `subject`. |
| `kling-v4-long-image supports at most 1 image with role style` | Provide at most one image per role; duplicate subject images are also invalid. |
| `` `resolution` must be 1K or 2K for kling-v4-long-image `` | Use `1K` or `2K`. |
| `` `size` is not supported by kling-v4-long-image `` | Remove unsupported size, ratio, or series fields; do not send `null` or empty strings. |
| `` `n` is not supported by kling-v4-long-image: each request returns one long image `` | Omit `n` or use the integer `1`. |
| `reference image is not accessible for kling-v4-long-image` | Check public access and URL validity, including HTTP 403 / 404 / 410. |
| `unsupported reference image dimensions for kling-v4-long-image` | Both dimensions must be at least 300 px, with a ratio from 2:5 to 5:2. |
| `reference image too large for kling-v4-long-image` | Each reference image must be at most 30 MB. |


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