Kwaivgi Kling Image V4.0 Long Image API Documentation

Kwaivgi Kling Image V4.0 Long Image API Documentation

Playground

Try it on WaveSpeedAI!

Kling Image 4.0 Long Image creates long-form vertical images from product photos or text prompts, making it suitable for ecommerce product detail pages, landing pages, promotional layouts, and web design workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Kling Image 4.0 Long Image generates a single tall image for an ecommerce product detail page or a webpage design concept. Use product photos and a brief to plan an ecommerce layout, or describe a website concept with optional reference images.


Why Choose This?

  • Two page types — Choose an ecommerce product page or a webpage design.
  • Product references — Provide 1–3 product photos for ecommerce pages.
  • Ecommerce length options — Choose short, medium, or long page layouts.
  • Resolution options — Select a 1K or 2K page-width tier.

Parameters

ParameterRequiredDescription
promptYesDescribe the page content, visual style, and section priorities. Refer to inputs as <<<image_1>>>, <<<image_2>>>, and so on.
page_typeYesecommerce or webpage. Default: ecommerce.
imagesOptional1–3 product image URLs are required for ecommerce. For webpage, up to 3 reference images are optional.
lengthNoEcommerce only: short (about 2–5 sections), medium (about 6–10), or long (about 11–18). Default: medium. Ignored for webpage.
resolutionNoPage-width tier: 1k or 2k. Default: 1k.
output_formatNoOutput format: png, jpeg, or webp. Default: png.

How to Use

  1. Select a page type — Choose ecommerce for a product detail page or webpage for a website concept.
  2. Add images — Provide 1–3 product photos for ecommerce, or optional webpage references.
  3. Write the page brief — Describe the content, section order, requested text, and visual style.
  4. Choose output settings — Set the resolution and format. For ecommerce, also choose the page length.
  5. Submit and review — Inspect the generated page image and its text.

Pricing

Pricing is based on page_type, resolution, and, for ecommerce pages, length.

Page typeLength1K price2K price
EcommerceShort$0.235$0.282
EcommerceMedium$0.470$0.549
EcommerceLong$0.784$0.862
WebpageNot applicable$0.549$0.596

Each input image adds $0.003 per request.

Total price = the selected page rate + input image count × $0.003.

Example Costs

ConfigurationPrice
Short ecommerce page at 1K + 1 product image$0.238
Medium ecommerce page at 1K + 1 product image$0.473
Long ecommerce page at 2K + 3 product images$0.871
Webpage at 2K, no reference images$0.596

Best Use Cases

  • Product page concepts — Draft layouts for product features, specifications, and imagery.
  • Landing-page concepts — Explore section order, styling, and visual hierarchy.
  • Campaign presentations — Create a long-form visual for design review.

Pro Tips

  • List sections in the intended order and identify the most important content.
  • Provide concise copy for headings and labels.
  • Use product photos that clearly show the features mentioned in the prompt.

Notes

  • prompt and page_type are required; ecommerce pages also need 1–3 product images.
  • Each reference image must be no larger than 30 MB.
  • Each request returns one image of a page design, rather than HTML or an interactive website.
  • Section counts are approximate, and the generated page height depends on the layout.
  • Review generated copy, product details, and layout before use.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "page_type": "ecommerce",
  "length": "medium",
  "resolution": "1k",
  "output_format": "png"
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/kwaivgi/kling-image-v4.0/long-image" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Retry temporary errors only while polling, never the submit request. Errors, retries and timeouts

Parameters

Task Submission Parameters

Request Parameters

ParameterTypeRequiredDefaultRangeDescription
promptstringYes-Describe the page: the product and its selling points for an ecommerce page, or the site and its content for a webpage design. Refer to the input images as <<<image_1>>>, <<<image_2>>>, etc. in array order.
page_typestringYesecommerceecommerce, webpageecommerce: a product detail page built from your product photos. webpage: a website visual design.
imagesarray<string>No-0 ~ 3 itemsProduct photos (1-3, required for an ecommerce page), or optional references (up to 3) for a webpage design.
lengthstringNomediumshort, medium, longLength of an ecommerce page: short (about 2-5 sections), medium (about 6-10) or long (about 11-18). Not used for a webpage.
resolutionstringNo1k1k, 2kOutput resolution (page width tier).
output_formatstringNopngpng, jpeg, webpOutput image format.

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

ParameterTypeDescription
codeintegerHTTP status code (e.g., 200 for success)
messagestringStatus message (e.g., “success”)
data.idstringUnique identifier for the prediction, Task Id
data.modelstringModel ID used for the prediction
data.outputsarrayOutput values, usually URL strings; some models return text strings or structured result objects (empty when status is not completed)
data.urlsobjectObject containing related API endpoints
data.statusstringTask status. completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses.
data.created_atstringISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”)
data.errorstringError message (empty if no error occurred)
data.timingsobjectObject containing timing details
data.timings.inferenceintegerInference time in milliseconds

Result Request Parameters

ParameterTypeRequiredDefaultDescription
idstringYes-Task ID

Result Response Parameters

ParameterTypeDescription
codeintegerHTTP status code (e.g., 200 for success)
messagestringStatus message (e.g., “success”)
dataobjectThe prediction data object containing all details
data.idstringUnique identifier for the prediction
data.modelstringModel ID used for the prediction
data.outputsarray<string | object>Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.
data.urlsobjectObject containing related API endpoints
data.statusstringStatus: completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses
data.created_atstringISO timestamp of when the request was created
data.errorstringError message (empty if no error occurred)
data.timingsobjectObject containing timing details
data.timings.inferenceintegerInference time in milliseconds
© 2026 WaveSpeedAI. All rights reserved.