Skip to main content
POST
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

Authentication

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

Request parameters

string
required
Must be kling-v4-long-image.
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)
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.
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.
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.
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.
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 and pass the returned url.
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.
integer
Each request generates one tall image. Omit this field or use the integer 1; other values return HTTP 400.
boolean
Omit this field or use false; true returns HTTP 400.
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

Webpage with style and subject references

Webpage from a prompt only

Query the task

Poll the task query API, preferably every 10 seconds. Keep the task_id and avoid duplicate generation requests during a long wait.
The following illustrates a successful result. Both images and url are arrays; this model returns one tall image per request.
Download the image before the Unix timestamp in seconds given by data.result.images[0].expires_at; the link expires afterward.
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. Charges are reserved at submission, settled on success, and fully refunded on failure. See the pricing page 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.