Kwaivgi Kling Image V4.0 Edit API Documentation

Kwaivgi Kling Image V4.0 Edit API Documentation

Playground

Try it on WaveSpeedAI!

Kling Image 4.0 Edit transforms and combines reference images through natural-language instructions, supporting multi-image composition, subject and style consistency, product imagery, creative edits, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Kling Image 4.0 Edit generates images guided by a text prompt and 1–10 reference images. Use it to explore changes to subjects, backgrounds, clothing, products, or visual styles at 2K, 4K, or 8K.


Why Choose This?

  • Reference-guided editing — Use uploaded images to guide the requested changes.
  • Multiple references — Combine guidance from up to 10 input images.
  • Framing options — Choose an aspect ratio or leave it unset for automatic selection.
  • Batch generation — Request 1–9 independent output images.

Parameters

ParameterRequiredDescription
promptYesDescribe the requested changes. Refer to inputs as <<<image_1>>>, <<<image_2>>>, and so on, in array order.
imagesYes1–10 reference image URLs.
aspect_ratioNo1:1, 3:2, 2:3, 3:4, 4:3, 9:16, 16:9, or 21:9. If omitted, the model selects the ratio automatically using the input images.
resolutionNoOutput resolution tier: 2k, 4k, or 8k. Default: 2k.
num_imagesNoNumber of independent output images, from 1 to 9. Default: 1.
output_formatNoOutput format: png, jpeg, or webp. Default: png.

How to Use

  1. Add reference images — Upload 1–10 images in the order you will reference them.
  2. Describe the edit — State what should change and which details should be retained.
  3. Choose output settings — Set the resolution, image count, and format; optionally choose an aspect ratio.
  4. Submit and review — Check the generated images against your references.

Pricing

Pricing is based on the selected resolution and num_images.

ResolutionPrice per output image
2K$0.063
4K$0.094
8K$0.157

Each input image adds $0.003 per request.

Total price = num_images × the resolution rate + input image count × $0.003.

Example Costs

ConfigurationPrice
1 output at 2K + 1 input image$0.066
2 outputs at 4K + 3 input images$0.197
1 output at 8K + 10 input images$0.187

Best Use Cases

  • Product imagery — Explore new backgrounds, arrangements, and styling.
  • Portrait variations — Request changes to clothing or surroundings.
  • Visual combinations — Use several references to describe a new composition.

Pro Tips

  • Use clear references with the relevant subject or detail visible.
  • Assign a specific role to each reference in the prompt.
  • Describe both the requested changes and the details you want to retain.

Notes

  • Both prompt and images are required.
  • Each reference image must be no larger than 30 MB.
  • Reference images guide generation; exact identity, text, and detail preservation can vary. Review the output 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",
  "images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ],
  "aspect_ratio": "1:1",
  "resolution": "2k",
  "num_images": 1,
  "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/edit" \
  -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-Text prompt describing the image to create from the input images. Refer to the input images as <<<image_1>>>, <<<image_2>>>, etc. in array order.
imagesarray<string>Yes-1 ~ 10 itemsInput images (1-10): subjects, products, styles or scenes to combine or transform.
aspect_ratiostringNo-1:1, 3:2, 2:3, 3:4, 4:3, 9:16, 16:9, 21:9The aspect ratio of the generated image. If not specified, it is determined automatically from the input image.
resolutionstringNo2k2k, 4k, 8kOutput resolution. 2k, 4k or native 8k.
num_imagesintegerNo11 ~ 9Number of independent images to generate.
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.