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

# Kling Image 4.0 API: Images, Image Sets & Long Images

> Generate ordinary images, coherent image sets, webpage designs, and ecommerce detail pages with Kling Image 4.0 on APIXO, including reference and subject inputs.

## Overview

Kling Image 4.0 uses one model ID for ordinary image generation, coherent image sets, webpage designs, and ecommerce detail pages. Ordinary images and image sets share the same per-image prices.

| Capability | Value |
| - | - |
| Model ID | `kling-image-4-0` |
| Modes | `image`, `series`, `webpage`, `ecommerce` |
| Ordinary images | Text-only or reference-guided; 1–9 outputs |
| Coherent image sets | Text-only or reference-guided; 2–10 related outputs |
| Image resolutions | `2k`, `4k`, `8k` |
| Long-image resolutions | `1k`, `2k`; one complete image per task |
| Subject inputs | 2–4 reference images per named subject |

`image` can generate several independent images. Use `series` when the outputs should form a coherent set. `webpage` creates a scrolling webpage design as an image; `ecommerce` creates a product detail page as an image. Long-image outputs are not HTML or editable websites.

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint | Purpose |
| - | - | - |
| `POST` | `/generateTask/kling-image-4-0` | Create a generation task |
| `GET` | `/statusTask/kling-image-4-0?taskId={taskId}` | Poll task status and retrieve image URLs |

Send `Authorization: Bearer YOUR_API_KEY`. POST requests also require `Content-Type: application/json`.

## Copy-paste async quickstart

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/kling-image-4-0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "image",
      "prompt": "A blue ceramic cup on a white table, studio photography",
      "resolution": "2k",
      "aspect_ratio": "1:1",
      "num_images": 1
    }
  }'
```

An accepted request returns a task ID:

```json theme={null}
{"code":200,"message":"success","data":{"taskId":"task_123"}}
```

Task acceptance does not mean generation has completed. Save the task ID and query the status endpoint.

## Mode examples

Replace example image URLs with your publicly accessible image URLs.

### Coherent three-image set with one subject

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "series",
    "prompt": "Create three consistent photographs of @Cup: a studio shot, a cafe scene, and a close-up.",
    "resolution": "2k",
    "num_images": 3,
    "elements": [{
      "name": "Cup",
      "tag": "prop",
      "description": "The same blue ceramic cup in every image.",
      "image_urls": [
        "https://example.com/cup-front.png",
        "https://example.com/cup-side.png",
        "https://example.com/cup-top.png"
      ]
    }]
  }
}
```

This request has one billable subject, even though it contains three reference images and the task requests three outputs.

### Webpage long image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "webpage",
    "prompt": "Design a scrolling website for a ceramic cup brand. Use @style for the layout and @subject for the product. Include a hero, features, gallery, and footer.",
    "resolution": "1k",
    "style_image_url": "https://example.com/layout.png",
    "subject_image_url": "https://example.com/cup.png"
  }
}
```

Both references are optional. This example has two billable input materials.

### Ecommerce detail-page long image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "ecommerce",
    "prompt": "Create a product detail page for @image_1 with a hero photo, materials, features, and use cases.",
    "resolution": "1k",
    "length": "short",
    "image_urls": ["https://example.com/cup.png"]
  }
}
```

Ecommerce requires 1–3 product images. `length` controls content inside one image: roughly 2–5 sections for `short`, 6–10 for `medium`, and 11–18 for `long`. These are content guidelines, not fixed output heights or section counts.

## Parameters

**request\_type** `string` (default: async)

Result delivery mode. Supported values: `async`, `callback`. Use async for polling or callback for final webhook delivery. Poll until data.state is success or failed; HTTP 200 alone does not indicate successful generation.

**callback\_url** `string`

Required when request\_type is callback. Use a publicly accessible HTTPS webhook URL. See [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md).

**input** `object` *required*

Kling Image 4.0 generation parameters. Send the fields for your selected mode.

**properties**

**mode** `string` *required*

Generation mode. Supported values: `image`, `series`, `webpage`, `ecommerce`.

**prompt** `string` *required*

Non-empty prompt, at most 20,000 characters. Reference ordinary images and ecommerce product images as @image\_1, @image\_2, and so on; reference named subjects as @name. Webpage references use @style and @subject. Only mention references you provide. For literal email addresses or handles in long-image prompts, use a full-width ＠ or insert a space after @.

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

Output resolution. Supported values: `1k`, `2k`, `4k`, `8k`. Image and series support only 2k, 4k, or 8k; webpage and ecommerce support only 1k or 2k. Uppercase K is accepted. Defaults to 2k in every mode.

**num\_images** `integer`

Requested output count. Image supports 1–9, default 1; series supports 2–10, default 4. Webpage and ecommerce return exactly one image: omit this field or set it to 1. Input material fees do not multiply with this count.

**aspect\_ratio** `string` (default: auto)

Image and series only. Supported values: `auto`, `9:16`, `2:3`, `3:4`, `1:1`, `4:3`, `3:2`, `16:9`, `21:9`. Long-image layout is controlled by the mode and prompt.

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

Public HTTP(S) image URLs. Optional for image and series, with up to 10 ordinary references; required for ecommerce, with 1–3 product images. Use style\_image\_url and subject\_image\_url for webpage references instead. Ordinary references and named subjects combined cannot exceed 10 items. Each file must be JPG, JPEG, or PNG and at most 20 MB. Recommended dimensions are at least 300 pixels on each side with width/height ratio 0.4–2.5. Each ordinary reference or product image adds one input material fee, including the first.

**elements** `object[]`

Image and series only: up to 10 named subjects, with ordinary references and subjects combined limited to 10 items. Each object requires name and image\_urls. Names must be unique ignoring case, contain 1–20 Chinese characters, letters, digits, or underscores, and must not be image\_N or object\_N where N is a number. Each subject requires 2–4 public HTTP(S) image URLs of the same subject from different angles; the first is the primary view. Each image must be JPG, JPEG, or PNG and at most 20 MB; recommended dimensions are at least 300 pixels per side with width/height ratio 0.4–2.5. Optional tag values are character, animal, prop, costume, scene, effect, or others. Optional description is a string of at most 100 characters. A subject counts as one billable input material; its internal images are not charged separately.

**style\_image\_url** `string`

Webpage only: optional public HTTP(S) image URL for layout and style guidance, referenced as @style. JPG, JPEG, or PNG, at most 20 MB; recommended dimensions are at least 300 pixels per side with width/height ratio 0.4–2.5. Adds one input material fee.

**subject\_image\_url** `string`

Webpage only: optional public HTTP(S) image URL for subject guidance, referenced as @subject. JPG, JPEG, or PNG, at most 20 MB; recommended dimensions are at least 300 pixels per side with width/height ratio 0.4–2.5. Adds one input material fee.

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

Ecommerce only. Supported values: `short`, `medium`, `long`. Controls content length and the base price of the single detail-page image.

## Poll for result

```bash theme={null}
curl "https://api.apixo.ai/api/v1/statusTask/kling-image-4-0?taskId=task_123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

While generating, the task returns a nonterminal state such as `processing`. Continue polling until `success` or `failed`; treat other states as still processing.

On success, `data.resultJson` is a JSON string containing one URL for each generated image:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_123",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/example.png\"]}",
    "createTime": 1795014219438,
    "completeTime": 1795014285457,
    "costTime": 66019
  }
}
```

```javascript theme={null}
if (response.data.state === "success") {
  const { resultUrls } = JSON.parse(response.data.resultJson);
  // Display every URL, including all images in a series.
}
```

Creation and completion timestamps use Unix milliseconds; `costTime` is elapsed milliseconds when available. Read each image's actual content type instead of assuming an extension. Long-image tasks return one URL for the complete image.

## Webhook delivery

Set `request_type` to `callback` and supply a top-level `callback_url`. Input parameters and the image result format are the same as with polling. Your receiver should accept the final payload and handle duplicate delivery safely. See [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md) for the shared contract.

## Billing

Standard prices are in USD before applicable account discounts. Check [current prices](https://apixo.ai/pricing/api) for the latest rates.

Ordinary images and coherent image sets share one output price table:

| Resolution | Price per output image |
| - | - |
| 2K | \$0.063 |
| 4K | \$0.094 |
| 8K | \$0.157 |

Each long-image task produces one complete image:

| Long-image type | 1K | 2K |
| - | - | - |
| Webpage | \$0.549 | \$0.596 |
| Ecommerce — short | \$0.235 | \$0.282 |
| Ecommerce — medium | \$0.470 | \$0.549 |
| Ecommerce — long | \$0.784 | \$0.862 |

**Input materials add \$0.003 each per task, including the first.** Count each ordinary reference image, named subject, webpage style/subject reference, or ecommerce product image as one material. A subject's 2–4 internal reference images are included in its single subject fee. Material fees do not multiply with output count.

`Request amount = output price × output count + $0.003 × input materials`.

* Three 2K outputs with one subject containing three reference images: `3 × $0.063 + $0.003 = $0.192`.
* A 1K webpage with style and subject references: `$0.549 + 2 × $0.003 = $0.555`.
* A short 1K ecommerce page with one product image: `$0.235 + $0.003 = $0.238`.

Apply the applicable account discount to the full amount, then round the request total upward to the nearest \$0.001. Failed tasks are fully refunded. When a successful task returns fewer images than requested, missing output charges are refunded using the task's captured prices and discount; input material fees are retained. See [Pricing](https://apixo.ai/docs/pricing.md#credit-conversion-and-rounding) for the platform calculation rules.

## Latency and polling

| Workload | Typical generation time | Recommended first poll | Poll interval |
| - | - | - | - |
| Images, image sets, and long images | Varies with the request | 20 seconds after task creation | At least 5 seconds |

Use callback mode for production workloads and allow longer generations in your application timeout. Do not submit a duplicate task just because the current task is still processing.

## Errors and troubleshooting

Invalid inputs and insufficient balance can reject task creation. An accepted task may later fail: check `data.state`, then read `failCode` and `failMsg` when the state is `failed`. An HTTP 200 response by itself does not mean generation succeeded. See [Error codes](https://apixo.ai/docs/api-reference/errors.md) and [Status Task](https://apixo.ai/docs/api-reference/status-task.md).

Check the selected mode's resolution and output count, ecommerce product-image requirement, and the combined limit of ordinary references plus subjects. Reference URLs must remain publicly accessible while the task runs.

## MCP integration

The paired [model schema](https://apixo.ai/docs/models/schemas/image/kling-image-4-0.json) declares `mcp.result` as image URLs using `url_array_v1`. Render every returned URL. `mcp.attachments` supports `image_urls`, `elements[].image_urls`, `style_image_url`, and `subject_image_url`. Preserve file order. For a named subject, provide the parent object and its name in `input`, then bind its files to an explicit item index. See [schema-driven MCP contracts](https://apixo.ai/docs/guides/mcp-model-contracts.md).

## Related links

* [Image Models](https://apixo.ai/docs/models/image)
* [Generate Task](https://apixo.ai/docs/api-reference/generate-task.md)
* [Webhooks](https://apixo.ai/docs/api-reference/webhooks.md)
* [API Pricing](https://apixo.ai/pricing/api)


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