# Kling Image 4.0 Long — /images/generations

The long-image mode of Kuaishou Kling Image 4.0 (Beta): a whole e-commerce detail page or web page design in one tall image. 1K / 2K, delivered as the original PNG with its C2PA content credential, billed by page type, length and resolution.

**Endpoint:** `POST https://kovapi.com/v1/images/generations`

## Quick start

An asynchronous job like the other image calls: submit, get a job id, poll for the result. An e-commerce page needs 1-3 product photos; a web page can be text only.

**Step 1: submit an e-commerce page (skill, length, resolution and the product photos)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "An e-commerce detail page for the travel mug in image 1: hero visual, three selling points, usage scene, English copy; use only what the photo shows, no invented specifications", "skill": "ecommerce", "length": "medium", "resolution": "1K", "images": ["https://example.com/mug.jpg"]}'
```

Response (HTTP 202)

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "kling-image-4.0-long"
}
```

**Step 2 · Poll every 2–3 seconds until `status` is `succeeded` or `failed`**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response when it succeeds

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "kling-image-4.0-long",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "1K", "model": "kling-image-4.0-long"}
}
```

**Step 3: download data[0].url, Kling's original long PNG (1024 / 2048 px wide, height follows the content), kept for 7 days.**

**Complete example (Python: submit, wait, save to disk)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# A web page: images are optional
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "kling-image-4.0-long",
    "prompt": "A home page for Northbound Coffee, a specialty roaster: hero image and headline, three signature beans, brand story, footer, English copy, warm minimal style",
    "skill": "webpage",
    "resolution": "1K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

while job["status"] not in ("succeeded", "failed"):
    time.sleep(5)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("kling-image-4.0-long.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])
```

## Authentication
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Request parameters

The JSON body of `POST /v1/images/generations`:

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| model | string | Yes | The model id: `kling-image-4.0-long`. |
| prompt | string | Yes | What to draw. For image-to-image, say what to change. |
| skill | string | No | Page type: `ecommerce` (a product detail page; 1-3 product photos in images) or `webpage` (a web page design). When omitted: ecommerce with images, webpage without. |
| length | string | No | E-commerce page length: `short` (about 2-5 sections), `medium` (default, about 6-10), `long` (about 11-18); leave it out for a web page. |
| resolution | string | No | `1K` (default, 1024 px wide) or `2K` (2048 px wide); there is no 4K. |
| image / images | string / array | No | E-commerce page: 1-3 product photos (required). Web page: up to 2; by default the first is the subject reference and the second the style reference. jpg / png, at least 300 px a side, aspect ratio 2:5-5:2; each costs $0.003 more. |
| image_roles | array | No | Web page only: one per image in images, each `subject` or `style`, at most one of each, e.g. `["style", "subject"]`. |
| n | integer | No | One long image per request: n must be 1. |
| callback_url | string | No | Where to push the result when the job ends; see Webhooks below. |

## Price

Billed per image by page type, length and resolution; each reference image costs $0.003 more. Held at submit, released in full on failure.

| Type | 1K · Credits per image | 1K · USD per image | 2K · Credits per image | 2K · USD per image |
| --- | --- | --- | --- | --- |
| E-commerce page · short | 47 | $0.235 | 56 | $0.28 |
| E-commerce page · medium | 94 | $0.47 | 109 | $0.545 |
| E-commerce page · long | 156 | $0.78 | 172 | $0.86 |
| Web page | 109 | $0.545 | 119 | $0.595 |

## Size and format

- Fixed width: 1024 px at 1K, 2048 px at 2K; the height follows the content (4,257-16,270 px measured on 11-20).

- The original PNG with its C2PA content credential, never cropped or resized; a 2K long image can run to tens of MB.

- One whole long image per request; no HTML or editable design files.

## Writing the prompt

- State the purpose, language, section order, selling points and copy. Write the prompt in the language you want the copy in and say so, e.g. "English copy".

- Give only real product facts and add "use only the product facts provided; do not invent specifications": the model writes what you give it and may add details of its own.

- Refer to the images as @image1, @image2 in the prompt.

## Job status and fields

`GET /v1/images/jobs/{id}` reports these statuses; every field is described in [Async jobs](https://docs.kovapi.com/en/guide/async-jobs#fields). Poll every 2–3 seconds, or use a webhook.

| Status | Meaning |
| --- | --- |
| queued | Waiting in line. Carries `queue_position` (jobs ahead of yours) and `eta_seconds` (expected wait). |
| processing | Rendering. |
| succeeded | Done. The result is in `data[0].url`, the billing detail in `usage`. |
| failed | Failed. The reason is in `error`; the credits held for the job are refunded in full. |

One account runs up to 50 jobs at a time; further jobs wait in submission order, and a job that has not started after 15 minutes fails and is refunded in full. Job records are kept for 3 days and image links for 7 days.

## How long it takes

Measured on 11-20: about 1.5-2.5 minutes at 1K and 2.5 at 2K; longer pages take longer, and peaks can be slower.

## Errors and refunds

An error at submit comes back at once as HTTP 4xx / 5xx: no job is created and nothing is charged. A failure after the job was accepted is reported by the job endpoint, and the hold is refunded in full. Every code is listed under [Error codes](https://docs.kovapi.com/en/guide/errors).

### Errors at submit

| HTTP | code | Cause | What to do |
| --- | --- | --- | --- |
| 400 | missing_prompt | `/v1/images/generations` has no `prompt`. | Add a `prompt`. |
| 400 | invalid_request | A reference image cannot be read (dead link, not an image, over 16MB...; `message` says which one and why), `/v1/images/edits` has no reference image, the body is not a JSON object, or `n` is not an integer. | Fix what `message` says and submit again. |
| 400 | unsupported_resolution | The model does not offer the chosen resolution tier (Grok image generation has no 4K, for example). | Pick another tier; each model's doc lists its tiers. |
| 400 | model_not_found | The model id is misspelled, `model` is missing, or the model cannot be used on this endpoint (a chat model on the image endpoint, for example). | Use a model id from `GET /v1/models` or the [API reference](https://docs.kovapi.com/en/api). |
| 401 | invalid_api_key | The key does not exist, was deleted or is disabled, or the account is disabled. | Check the key on the API Keys page of the console. |
| 402 | insufficient_quota | Not enough balance to hold this request. The gateway holds the highest possible cost of the request first, so a burst of concurrent calls can trigger it too. | After a burst, wait a few seconds and retry; otherwise top up. |
| 429 | rate_limit_exceeded | Over the requests-per-minute limit set on this key (counted over the last 60 seconds). No `Retry-After` header. | Wait a few seconds and retry, or raise the key's limit in the console. |
| 503 | model_maintenance | The model is under maintenance and takes no requests; no other model answers in its place meanwhile. | Retry when maintenance ends; see [Status](https://kovapi.com/en/status). |
| 503 | service_unavailable | A temporary failure on our side, such as storing a reference file; `/v1/responses` also answers 503, with `Retry-After`, when it cannot take requests for a moment. | Retry shortly. |

### Failed jobs (`status` `failed`)

| code | When you see it | What to do |
| --- | --- | --- |
| moderation_blocked | Image: the model provider's safety system refused the prompt or a reference image (the code may also be `content_policy_violation`). | Rewrite the prompt or replace the reference; resubmitting it unchanged is usually refused again. |
| upstream_error | Any other failure: the automatic retries did not help, the job waited 15 minutes without starting, the upstream refused without a reason, and so on; `message` says which. | Submitting again usually works. |

## Webhooks instead of polling

Add `callback_url` when you submit and the moment the job ends, success or failure, the gateway pushes exactly what the poll endpoint returns to that URL, signed and retried on failure. You can also set an account-wide address under Settings → Webhook in the console. [Webhook docs →](https://docs.kovapi.com/en/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kling-image-4.0-long", "prompt": "A home page for Northbound Coffee, a specialty roaster: hero image and headline, three signature beans, brand story, footer, English copy, warm minimal style", "skill": "webpage", "callback_url": "https://your-domain.com/webhook"}'
```
