ToAPIsToAPIs
Kling Image 4.0

Kling Image 4.0 Long Image Generation

Generate a long webpage design or ecommerce product-detail image at 1K or 2K

POST
/v1/images/generations

Note for users in mainland China: Please use https://toapis.cn as the API endpoint (Base URL). Replace https://toapis.com with https://toapis.cn in the examples in this document.

kling-image-4.0-long generates one long image asynchronously. Choose the webpage skill for a webpage design or ecommerce for a product-detail image.

Authorizations

Authorizationstringheaderrequired

All endpoints require Bearer Token authentication

Get your API Key from the API Key Management Page

Add to request header:

Authorization: Bearer YOUR_API_KEY

Body

Send an application/json request with the following fields at the top level.

modelstringbodyrequireddefault: kling-image-4.0-long

Set this to kling-image-4.0-long.

promptstringbodyrequired

A non-blank description of the layout and content to generate.

skillstringbodyrequired

webpage generates a webpage design. ecommerce generates an ecommerce product-detail image.

resolutionstringbodydefault: 1K

Use 1K or 2K. The value is case-insensitive.

nintegerbodydefault: 1

Number of images to generate. This is fixed at 1. Omit this field or set it to the integer 1.

lengthstringbody

For ecommerce only. Use short (about 2-5 content sections), medium (about 6-10, the default), or long (about 11-18). All sections form one image.

image_urlsstring[]body

For ecommerce, send 1 to 3 product reference images in order, using this field or reference_images. In the prompt, @image_1, @image_2, and @image_3 refer to the images in array order.

reference_imagesstring[]body

Alternative to image_urls for ecommerce. Send exactly one of these fields.

style_reference_image_urlstringbody

For webpage only. Optional URL for one image that guides the visual style.

subject_reference_image_urlstringbody

For webpage only. Optional URL for one image that supplies the subject.

callback_urlstringbody

Optional callback URL for the finished task. With a configured Token task webhook, the URL must use the same scheme, host, and port as the default URL. Omit this field to use the Token's enabled default.

Reference images must use reachable HTTP(S) URLs. To get a URL for a local file, use the Upload Image API.

Parameter limitations

For webpage, omit length, image_urls, and reference_images entirely, including empty arrays and null. Omit both role-specific URLs to generate from text alone. For ecommerce, omit style_reference_image_url and subject_reference_image_url.

Leave out size, aspect_ratio, ratio, series_amount, result_type, contents, options, and settings.

Query the task

Use the returned id and the same API key to query the image task. Keep polling while the status is queued or in_progress. On completed, read the image URL from result.data[0].url. On failed, check error.

curl "https://toapis.com/v1/images/generations/TASK_ID" \
  -H "Authorization: Bearer $TOAPIS_API_KEY"

Billing

The base charge is per request and depends on the pricing region, skill, and resolution. For ecommerce, it also depends on length. Use the same API key to query GET /v1/pricing?model=kling-image-4.0-long. Append &region=cn for the mainland China catalog or &region=global for the international catalog. The default is global, regardless of the API domain.

If the matching price entry includes input_image_unit_price, each reference image above free_input_image_count adds a charge. The actual charge appears in the task's billing when confirmed. See actual cost and task usage.

Response

idstring

Unique task identifier for status queries

objectstring

Object type, always generation.task

modelstring

Model name used

statusstring

queued when the request is accepted.

progressinteger

Task progress percentage (0-100)

created_atinteger

Task creation timestamp (Unix timestamp)

metadataobject

Task metadata

result.data[].urlstring

URL of the single image in a completed task.

Set the TOAPIS_API_KEY environment variable before running these examples. Replace the example.com reference placeholders with accessible image URLs.

requestExample

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "kling-image-4.0-long",
  "prompt": "Design a long landing page for a pottery studio. Use the visual style of the style reference and feature the handmade mug from the subject reference. Include a workshop schedule and a booking section.",
  "skill": "webpage",
  "n": 1,
  "resolution": "1K",
  "style_reference_image_url": "https://example.com/pottery-style.png",
  "subject_reference_image_url": "https://example.com/handmade-mug.png"
}'
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header "Authorization: Bearer $TOAPIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "kling-image-4.0-long",
  "prompt": "Create a long product-detail image for the desk lamp in @image_1. Use @image_2 for the close-up of the controls. Include sections for brightness settings, dimensions, and what is in the box.",
  "skill": "ecommerce",
  "n": 1,
  "resolution": "2K",
  "length": "medium",
  "image_urls": [
    "https://example.com/desk-lamp.png",
    "https://example.com/lamp-controls.png"
  ]
}'

responseExample

{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "kling-image-4.0-long",
  "status": "queued",
  "progress": 0,
  "created_at": 1794960000,
  "metadata": {}
}
{
  "id": "tsk_img_example",
  "object": "generation.task",
  "model": "kling-image-4.0-long",
  "status": "completed",
  "progress": 100,
  "created_at": 1794960000,
  "metadata": {},
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://example.com/generated/kling-image-4.0-long.png"
      }
    ]
  }
}