Kling O3 Image Edit API

kwaivgi/kling-image-o3/edit

1K / 2K / 4K · 1–9 images

Kling O3 Image Edit refines and blends imagery using up to 10 reference images alongside natural language instructions, supporting high-dimensional feature synthesis, mask-free surgical local edits, and native aspect ratio inheritance. It carries out complex wardrobe modifications, background transfers, and asset insertions while strictly preserving subject identity, facial contours, and realistic lighting textures.

Get API Key

Input

Prompt

1036/2000

Use image 1 as the exact reference for the woman and her skateboard, and image 2 as the environment and composition to preserve. Place the woman naturally on the flat central foreground apron of the skatepark in image 2, slightly left of center, full body visible. Keep her recognizable face, short curls, olive helmet, burgundy T-shirt over white sleeves, beige trousers, black shoes and the turquoise skateboard with cream wheels. She stands casually with both feet firmly on the ground, holding her skateboard vertically on the same side and with the same hand as in image 1; do not invent an action trick. Match the camera height, adult scale and late-afternoon light entering from the left in image 2; add realistic contact shadows beneath both shoes and the board. Preserve the bridge columns, right-hand bowl, left bank, distant trees and the overall park layout. Documentary sports photograph, natural skin and fabric. Exactly one person and one skateboard. No additional people, animals, text, brands, advertising or watermark.

Image Urls

2/10

Add images

Elements

Reference subjects in order with @Element1, @Element2. Provide a main view and additional views. Sign in to upload files.

Size

Resolution

Output Format

OutputReady

Continue with

Kling O3 Image Text to Image Kling 3.0 Turbo Kling 2.6

Examples

Edit this attic photograph with precisely localized changes. Remove every cardboard moving box on the left side of the window and restore the uninterrupted oak floor beneath them. In that cleared area place one comfortable moss-green fabric armchair angled slightly toward the center of the room, and one slender dark-bronze floor lamp with a small ivory shade immediately behind the chair. Fit both naturally under the sloping ceiling with believable proportions and floor contact shadows. Keep the exact original camera position and framing, roof slope, all exposed beams, square window and wooden frame, floorboard directions, foreground woven rug, right-hand built-in shelf and existing books. Preserve the original daylight direction and realistic photographic appearance; the new lamp is switched off. Do not renovate other surfaces or add decorations. No people, animals, boxes, typography, brands, advertising or watermark.

Transform this mountain village photograph into a meticulous handmade layered-paper artwork while preserving the original scene layout and camera framing. Keep the same cluster of tiled-roof houses in the upper left, the S-shaped path from the bottom center to the village, the sweeping terraces on the right, and the distant hills along the top. Construct every terrace level from a distinct stacked sheet with crisp cut edges, visible paper thickness and soft cast shadows between layers. Render the houses as tiny folded-paper buildings and trees as simple carefully cut silhouettes. Use warm ivory, muted forest green, ochre and dusty blue cardstock with subtle fiber texture. Directional studio light from upper left reveals the relief without flattening the recognizable topography. No new buildings or roads, no people, animals, writing, labels, border, frame, logos or watermark.

REST API

Quick Start

This flow submits one valid Kling O3 Image Edit request, captures its task_id, and reads image URLs after the asynchronous task ends.

Connect to the Vidgo API

Create an API key, keep it on the server, and send it as Authorization: Bearer VIDGO_API_KEY.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one image task

Send the current model ID, prompt, and ordered image URLs to the unified submit endpoint. The example keeps only first-call fields.

Submit request

curl --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "kwaivgi/kling-image-o3/edit",
  "input": {
    "prompt": "Use image 1 as the exact reference for the woman and her skateboard, and image 2 as the environment and composition to preserve. Place the woman naturally on the flat central foreground apron of the skatepark in image 2, slightly left of center, full body visible. Keep her recognizable face, short curls, olive helmet, burgundy T-shirt over white sleeves, beige trousers, black shoes and the turquoise skateboard with cream wheels. She stands casually with both feet firmly on the ground, holding her skateboard vertically on the same side and with the same hand as in image 1; do not invent an action trick. Match the camera height, adult scale and late-afternoon light entering from the left in image 2; add realistic contact shadows beneath both shoes and the board. Preserve the bridge columns, right-hand bowl, left bank, distant trees and the overall park layout. Documentary sports photograph, natural skin and fabric. Exactly one person and one skateboard. No additional people, animals, text, brands, advertising or watermark.",
    "resolution": "2K",
    "size": "16:9",
    "output_format": "png",
    "n": 1,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-image-o3/edit/v1/01/input-01.png",
      "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-image-o3/edit/v1/01/input-02.png"
    ]
  }
}'

Wait for the image result

Read data.task_id and poll only while status is not_started or running. Stop on both finished and failed.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll every 2–5 seconds and back off on 429/5xx. Or provide top-level callback_url to receive a terminal-state callback.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "SZY89V5J52M4304L",
    "status": "running",
    "created_time": "2026-09-24T11:39:07"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "SZY89V5J52M4304L",
    "status": "finished",
    "files": [
      {
        "file_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-image-o3/edit/v1/01/output.png",
        "file_type": "image"
      }
    ],
    "created_time": "2026-09-24T11:39:07",
    "error_message": null,
    "progress": 100
  }
}

Complete runnable polling example

Expand for the same payload end to end, including business-code, missing-task-ID, failed-state, unexpected-state, and network-error handling.

Complete runnable polling example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "kwaivgi/kling-image-o3/edit",
  "input": {
    "prompt": "Use image 1 as the exact reference for the woman and her skateboard, and image 2 as the environment and composition to preserve. Place the woman naturally on the flat central foreground apron of the skatepark in image 2, slightly left of center, full body visible. Keep her recognizable face, short curls, olive helmet, burgundy T-shirt over white sleeves, beige trousers, black shoes and the turquoise skateboard with cream wheels. She stands casually with both feet firmly on the ground, holding her skateboard vertically on the same side and with the same hand as in image 1; do not invent an action trick. Match the camera height, adult scale and late-afternoon light entering from the left in image 2; add realistic contact shadows beneath both shoes and the board. Preserve the bridge columns, right-hand bowl, left bank, distant trees and the overall park layout. Documentary sports photograph, natural skin and fabric. Exactly one person and one skateboard. No additional people, animals, text, brands, advertising or watermark.",
    "resolution": "2K",
    "size": "16:9",
    "output_format": "png",
    "n": 1,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-image-o3/edit/v1/01/input-01.png",
      "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-image-o3/edit/v1/01/input-02.png"
    ]
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

while true; do
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep 2
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters

This table lists only public fields inside input. See Quick Start for top-level model and optional callback_url usage.

Field	Type	Required	Default	Description
input.prompt	string	Yes	–	String, 1–2,000 characters after trimming.
input.image_urls	string[]	Yes	–	1–10 public HTTP(S) image URLs, passed in order.
input.resolution	string	No	1K	Output resolution determines the per-image rate.
input.size	string	No	16:9	Aspect ratio; auto is supported only by Edit. auto, 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9
input.output_format	string	No	png	Output image format.
input.n	integer	No	1	Integer output count, 1–9. Total credits = the resolution rate × n.
input.elements	object[]	No	–	Array of subject-reference objects. Reference them as @Element1, @Element2, etc. No published count limit; extension fields are preserved.
input.elements[].frontal_image_url	string	No	–	Public HTTP(S) URL for the main subject view.
input.elements[].reference_image_urls	string[]	No	–	Array of public HTTP(S) image URLs for additional views of the same subject.

Response Fields

The submit response identifies the task. The status response supplies image files or failure details at a terminal state.

Field	Type	Description
code	integer	Business response code; 0 or 200 indicates success.
message	string	Optional human-readable response message.
data.task_id	string	Unique task ID used for status queries after submission.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Task creation timestamp.
data.progress	integer	Progress from 0–100 in status responses.
data.files[]	array	Generated files in returned order when finished.
data.files[].file_url	string	Direct generated-image URL.
data.files[].file_type	string	Image results are identified as image.
data.files[].watermark_url	string \| null	Optional watermarked-file URL when present.
data.error_message	string \| null	Readable failure reason for failed tasks.

Task Lifecycle

Only the first two states may be polled again. finished and failed are terminal.

not_started
Accepted and queued; wait before checking again.
running
Image generation is in progress; continue polling.
finished
Successful terminal state; validate files and read image URLs.
failed
Failure terminal state; read error_message and stop.

Polling and Errors

Authentication401 means the key is missing or invalid. Fix authentication before resubmitting and never expose the key in browser code.
Validation400 indicates an invalid model ID, field, enum, length, or image count.
Polling intervalStart at 2–5 seconds, use exponential backoff for 429/5xx, and enforce an overall timeout.
Terminal statesStop after finished or failed. Treat finished without a valid image as a separate error.
Callback optionProvide a public top-level callback_url to receive a flat task object after finished or failed.
Network errorsDistinguish request timeout, network failure, and task failure. Retry the same query only when safe.

Model Specifications

Specification	Value	Details
Input mode	Prompt + 1–10 images	Both endpoints accept optional subject elements.
Resolution	1K · 2K · 4K	Default: 1K.
Aspect ratio	auto, 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9	Default: 16:9. Only Edit supports auto.
Output format	jpeg · png · webp	Default: png.
Output count	1–9	Integer; default: 1.
Billing	1K/2K: 3.5 credits/image (approximately $0.018); 4K: 7 credits/image ($0.035). Total credits = resolution rate × n, without input-image or subject-reference surcharges. At $0.005 per credit, 3.5 credits equals $0.0175. USD is rounded to three decimals after calculating the total.	1 credit = $0.005. USD is displayed to three decimals; final billing is determined by the backend.

Kling O3 Image Edit API documentation

Kling O3 Image Edit Overview

Kling O3 Image Edit is Kuaishou's (Kling AI) flagship multimodal image editing model engineered for complex visual compositing and multi-source asset modification. Ingesting 1 to 10 reference images simultaneously, it excels at multi-reference visual reasoning, prompt-driven maskless local inpainting, auto-ratio canvas inheritance, and native 4K resolution output. It delivers precise aesthetic control while preserving core subject continuity across commercial e-commerce, storyboards, and digital art.

Why Choose Kling O3 Image Edit?

Intelligent Multi-Reference Fusion up to 10 ImagesIngests 1 to 10 image assets in a single call, decoupling and harmonizing distinct subjects, styling palettes, physical props, and textures into an organic composite.
Mask-Free Natural Language InpaintingEliminates the friction of manual pixel masking; simply state modifications in plain language to execute pinpoint garment swaps, asset adjustments, and ambient relighting.
Dedicated auto Aspect Ratio SupportFeatures an auto ratio mode that preserves original canvas proportions faithfully, or maps cleanly to 8 standard ratios with realistic peripheral background synthesis.
Rigorous Subject & Illumination ConsistencyMaintains facial geometry, physique, material properties, and authentic ambient bounce light across successive scene transfers and object modifications.
Transparent Billing with Zero Input SurchargesAdopts the exact same predictable resolution rates as text-to-image with no surcharges per uploaded reference image, backed by automatic credit refunds on task errors.

Parameters

Parameter	Requirement	Description
prompt	Required	String, 1–2,000 characters after trimming.
image_urls	Required	1–10 public HTTP(S) image URLs, passed in order.
resolution	Optional	Output resolution determines the per-image rate. Default`1K2K4K`
size	Optional	Aspect ratio; auto is supported only by Edit. auto, 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9 Default`16:9auto9:161:14:33:43:22:321:9`
output_format	Optional	Output image format. Default`pngjpegwebp`
n	Optional	Integer output count, 1–9. Total credits = the resolution rate × n. Default`1`
elements	Optional	Array of subject-reference objects. Reference them as @Element1, @Element2, etc. No published count limit; extension fields are preserved.
elements[].frontal_image_url	Optional	Public HTTP(S) URL for the main subject view.
elements[].reference_image_urls	Optional	Array of public HTTP(S) image URLs for additional views of the same subject.

How to Use

Gather reference image URLsAssemble 1 to 10 accessible public HTTP(S) image URLs representing subjects, garments, environments, or styling references.
Formulate clear editing instructionsSpecify requested updates and boundary constraints in text (for example, 'Keep the facial identity from image 1, but dress the subject in the vintage leather jacket from image 2').
Configure resolution and ratio framingSelect 1K, 2K, or 4K resolution, and configure auto to preserve the source image framing or choose standard ratios like 16:9 or 1:1.
Choose format and output volumePick your target delivery format (PNG, JPEG, or WebP) and define output quantity n between 1 and 9.
Dispatch job and download resultsSubmit the API request to obtain a unique task ID, poll until complete, and retrieve direct high-resolution PNG download URLs.

Pricing

1K/2K: 3.5 credits/image (approximately $0.018); 4K: 7 credits/image ($0.035). Total credits = resolution rate × n, without input-image or subject-reference surcharges. At $0.005 per credit, 3.5 credits equals $0.0175. USD is rounded to three decimals after calculating the total.

Usage	Rate	Details
1K / 2K	3.5 credits/image · ≈ $0.018	Multiply by the output count n.
4K	7 credits/image · $0.035	Multiply by the output count n.

Best Use Cases

E-commerce apparel styling and multi-asset fusionCombine model shots, apparel packshots, and studio environments to generate realistic lifestyle photography without reshoots.
Multi-reference character design and pose variationSynthesize facial traits and styling from multiple reference angles to produce consistent character portraits in fresh environments.
Format re-composition and intelligent background extensionUse auto to lock native aspect ratios, or extend horizontal banners into vertical 9:16 social assets with seamless environmental filling.
Surgical detail modification and object clean-upSwap accessories, adjust hairstyles, replace cluttered backgrounds with minimalist studio sets, and refine local highlights seamlessly.

Pro Tips

When supplying multiple images, identify references distinctly in your prompt (e.g., 'Retain the facial identity of image 1, dressed in the trench coat from image 2').
Clarify both updates and constraints: 'Replace the background with a sunlit modern interior; keep the subject's pose, facial expression, and studio lighting reflections completely unchanged.'
Use auto for the size parameter when you want the generated output to match the exact proportions and dimensions of your primary input image.
High-contrast reference images with clean backgrounds help the multimodal feature decoupling pipeline isolate subject contours with maximum precision.

Notes

The image_urls parameter is required and must contain 1 to 10 valid public HTTP(S) image URLs.
The prompt parameter is required and must contain 1 to 2,000 characters after removing leading and trailing whitespace.
Output count n must be an integer between 1 and 9; charges scale strictly with output count and resolution tier without reference surcharges.
Generation operates asynchronously; query status with task_id or configure a callback_url for immediate webhook notifications.

Related Models

Qwen Image 3.0 Text-to-ImageAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Image EditAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Pro Text-to-Image preview

Qwen Image 3.0 Pro Text-to-ImageAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Pro Image EditAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Seedream 5.0 Pro Text-to-ImageThe ByteDance Seedream 5.0 Pro API generates 1K or 2K JPEG/PNG images from prompts and edits one to ten ordered HTTP(S) image inputs.

Seedream 5.0 Pro Image EditThe ByteDance Seedream 5.0 Pro API generates 1K or 2K JPEG/PNG images from prompts and edits one to ten ordered HTTP(S) image inputs.

GPT Image 2 Text-to-ImageOpenAI image generation and editing with quality tiers, flexible size controls, and single-image outputs up to 4K.

GPT Image 2 Image EditOpenAI image generation and editing with quality tiers, flexible size controls, and single-image outputs up to 4K.

Nano Banana 2 Text-to-ImageGoogle's next-gen image model powered by Gemini 3.1 Flash with native 2K/4K resolution, chain-of-thought reasoning, precise multi-language text rendering, and up to 14 reference images.

Nano Banana 2 Image EditGoogle's next-gen image model powered by Gemini 3.1 Flash with native 2K/4K resolution, chain-of-thought reasoning, precise multi-language text rendering, and up to 14 reference images.

Nano Banana Pro Text-to-ImageGoogle's Nano Banana Pro image model powered by Gemini 3 Pro for 4K generation, strong text rendering, multi-image blending, and production-ready image editing.

Nano Banana Pro Image EditGoogle's Nano Banana Pro image model powered by Gemini 3 Pro for 4K generation, strong text rendering, multi-image blending, and production-ready image editing.

GPT Image 1.5OpenAI's latest image model with 4x speed, precision editing, and superior text rendering.

Z-ImageAlibaba's efficient 6B-parameter image model with sub-second generation and exceptional Chinese-English bilingual text rendering capabilities.

Seedream 4.5ByteDance's unified 4K image generation and editing model with professional-grade text rendering and commercial photography quality.

Seedream 5.0 LiteByteDance Seedream 5.0 Lite family on Vidgo API: seedream-5.0-lite for text-to-image and seedream-5.0-lite-edit for image-to-image editing, with 2K/3K presets, custom sizes, and up to 10 reference images.

Kling O3 Image Edit API frequently asked questions

What is the Kling O3 Image Edit API?

Kling O3 Image Edit is a state-of-the-art multimodal image editing model developed by Kuaishou (Kling AI). It pairs 1 to 10 reference images with natural language instructions to execute multi-asset feature fusion, mask-free surgical local edits, and aspect ratio adaptation. Built on advanced multimodal feature decoupling and diffusion architectures, it carries out wardrobe updates, scene changes, or element adjustments while preserving facial contours, fine textures, and lighting harmony. You can call it programmatically or try it from the playground above.

How many reference images can I upload to Kling O3 Image Edit?

You can provide between 1 and 10 publicly accessible HTTP(S) image URLs. The model parses visual elements from each asset, blending distinct subjects, styling cues, or props into a unified final output in a single job.

How does Kling O3 Image Edit preserve subject identity during edits?

The model utilizes semantic prompt localization rather than manual pixel masks. Stating clearly which attributes to modify and which to retain ensures that facial contours, product dimensions, and ambient light reflections remain stable.

Does Kling O3 Image Edit support original aspect ratio retention?

Yes. By setting the size parameter to auto, the model automatically respects the aspect ratio of the primary input image; it also supports expanding images into 8 standard aspect ratios with realistic peripheral background synthesis.

Are there extra fees for uploading reference images in Kling O3 Image Edit?

No. Kling O3 Image Edit shares the exact same pricing tiers as text-to-image with zero input image surcharges. Costs depend solely on output count and resolution tier, and failed tasks receive an immediate full refund.

What resolutions and output formats does Kling O3 Image Edit support?

It supports 1K, 2K, and native 4K resolutions with output choices of PNG, JPEG, and WebP (PNG by default). Even intricate multi-reference local edits produce sharp, high-fidelity commercial deliverables.

What is the recommended prompt formula for multi-reference fusion with Kling O3 Image Edit?

Structure your instructions using target localization, reference binding, requested action, and preservation constraints (for example: 'Select the model in image 1, dress them in the black jacket from image 2, place them in the street setting of image 3, and keep facial expressions and studio lighting identical').