Kwaivgi Kling Image O3 Edit API Documentation

Kwaivgi Kling Image O3 Edit API Documentation

Playground

Kling O3 Edit is an AI image editing model with 4K resolution and multi-image reference support, enabling high-quality transformations with multiple reference inputs. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Kling Image O3 Edit is Kuaishou’s next-generation image editing model from the O3 architecture. Upload up to 10 reference images and describe how to combine or transform them — the model generates new images that blend characters, styles, and elements from your references while following your text instructions. Supports flexible aspect ratios, up to 4K resolution, and batch generation.

Why Choose This?

• O3-generation quality The latest architecture with improved detail, composition, and prompt understanding.

• Multi-reference support Upload up to 10 reference images to combine characters, objects, or styles in a single output.

• Text-guided editing Describe changes or compositions in natural language — no manual masking required.

• Up to 4K resolution Choose output resolution from 1K to 4K based on your quality requirements.

• Flexible aspect ratios Auto-detect or manually select from multiple options including 1:1, 3:4, 4:3, 9:16, 16:9.

• Batch generation Generate multiple variations in a single request for rapid iteration.

Parameters

How to Use

1. Upload your images — add up to 10 reference images containing the characters, objects, or styles you want.
2. Write your prompt — describe how to combine or transform them (e.g., “Have the people in picture 1 and picture 2 take a selfie together.”).
3. Choose aspect ratio — select auto or a specific format for your use case.
4. Set resolution — choose 1k/2k for speed or 4k for maximum detail.
5. Set num_images — generate multiple variations if needed.
6. Run — submit and download your edited images.

Pricing

Billing Rules

• Base rate: $0.028 per image (1K/2K)
• 4K rate: $0.056 per image (2× base)
• Total cost = num_images × per-image rate

Best Use Cases

• Character Composition — Combine people from different photos into a single scene.
• Style Fusion — Blend visual styles from multiple reference images.
• Creative Mashups — Merge characters, objects, or environments from separate sources.
• Marketing & Ads — Create composite visuals featuring multiple products or people.
• Social Content — Generate imaginative scenes combining friends, celebrities, or fictional characters.

Pro Tips

• Reference images with clear subjects and good lighting produce the best results.
• Use “picture 1”, “picture 2” etc. in your prompt to refer to specific reference images in order.
• Generate multiple images (num_images > 1) to explore different interpretations.
• Use 4K resolution for print-quality or large-format outputs.
• Auto aspect ratio adapts to your reference images — use manual selection for specific platforms.

Notes

• Both prompt and images are required fields.
• Maximum 10 reference images per request.
• 4K resolution costs 2× the base rate.
• Ensure uploaded image URLs are publicly accessible.

Related Models

• Kling Image O3 Text-to-Image — Generate images from text prompts with O3 quality.
• Kling Image V3 Edit — Previous generation image editing model.
• Kling Video O3 Pro Image-to-Video — Animate edited images into video.

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": "auto",
  "resolution": "1k",
  "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-o3/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

Parameters

Task Submission Parameters

Request Parameters

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

Response Parameters

Result Request Parameters

Result Response Parameters