Qwen Image 2.1 Edit LoRA API Documentation
Playground
Try it on WaveSpeedAI!Qwen Image 2.1 Image Edit LoRA supports image editing with up to 10 reference images and up to 3 custom LoRAs, with 1K, 1.5K, or 2K output for reference-guided edits, custom styles, character consistency, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.
Features
Qwen Image 2.1 Image Edit LoRA edits existing images with natural-language instructions, up to 10 reference images, and up to 3 custom LoRA weights. Address reference images directly in the prompt using <Picture 1> through <Picture 10>, then combine them with LoRAs for additional subject, style, or concept control.
Choose between 1K, 1.5K, and 2K output resolution depending on your quality and cost requirements.
Why Choose This?
-
Prompt-based image editing
Modify existing images using natural-language instructions. -
Up to 10 reference images
Combine multiple visual references in a single editing workflow. -
Reference-aware prompting
Address supplied images directly as<Picture 1>through<Picture 10>. -
LoRA customization
Apply up to3custom LoRA weights in the same request. -
Up to 2K resolution
Generate edited results at1K,1.5K, or2K. -
Flexible aspect ratios
Adjust the output composition for different creative workflows. -
Multiple output formats
Export edited images asjpeg,png, orwebp. -
Native transparency Generate images with a real alpha channel. Ask for transparency in the prompt and export as
pngorwebp.
Parameters
| Parameter | Required | Description |
|---|---|---|
| prompt | Yes | Text instruction describing the desired edit. Refer to supplied images as <Picture 1> through <Picture 10> when needed. |
| images | Yes | Reference image URLs. Supports between 1 and 10 images. |
| loras | No | Up to 3 LoRA objects. Each item uses {path, scale}. |
| resolution | No | Output resolution: 1k, 1.5k, or 2k. Default: 1k. |
| aspect_ratio | No | Optional output aspect ratio. |
| output_format | No | Output image format: jpeg, png, or webp. Use png or webp to preserve transparency; jpeg fills transparent areas with white. |
| seed | No | Optional random seed for generation. Use -1 for a random seed. |
How to Use
- Upload reference images — Provide between
1and10images inimages. - Write the editing prompt — Describe what should change and refer to specific inputs as
<Picture 1>,<Picture 2>, and so on. - Add LoRAs optional — Provide up to
3LoRA files with individualscalevalues. - Choose resolution — Select
1k,1.5k, or2k. - Choose aspect ratio optional — Set the desired output composition.
- Choose output format optional — Select
jpeg,png, orwebp. - Set seed optional — Use a fixed seed for reproducible results, or
-1for random generation. - Submit — Generate and retrieve the edited image.
Transparent Backgrounds
This model generates transparency natively, so a cut-out subject comes back with a real alpha channel rather than a painted-in background.
- Ask for it in the prompt. Describe the image as transparent, for example:
This is an RGBA image with transparency. A cute cartoon dragon sticker. The image has alpha channel and the background is transparent. - Set
output_formattopngorwebp. Both carry the alpha channel.
Reference images keep their own transparency as well, so you can edit an existing cut-out and get a cut-out back.
jpeg cannot store transparency, so transparent areas are filled with white. Prompts that do not ask for transparency return a fully opaque image in every format.
Pricing
Pricing is based on the selected resolution and the number of supplied reference images (images).
The first image uses the base edit price for the selected resolution. Each additional image adds a resolution-dependent charge. A request with default settings (resolution 1k, one image) costs $0.035 per run.
| Resolution | 1 image | Each additional image | 2 images | 5 images | 10 images |
|---|---|---|---|---|---|
resolution=1k (1K) | $0.035 | $0.01 | $0.045 | $0.075 | $0.125 |
resolution=1.5k (1.5K) | $0.065 | $0.015 | $0.08 | $0.125 | $0.20 |
resolution=2k (2K) | $0.125 | $0.02 | $0.145 | $0.205 | $0.305 |
The columns are the number of supplied images (images.count=1, 2, 5, 10); “Each additional image” is the extra cost of going from images.count=1 to images.count=2 at the same resolution.
aspect_ratio, output_format, and seed do not add separate charges.
Best Use Cases
- LoRA-guided image editing — Combine text instructions with custom LoRAs for stronger subject or style control.
- Multi-reference editing — Use several images to guide characters, products, objects, environments, or composition.
- Character consistency — Combine reference images and LoRAs to reinforce recurring character appearance.
- Style-guided edits — Apply custom visual directions while preserving elements from existing images.
- Product and marketing edits — Combine multiple product or scene references with customized visual styles.
- Creative prototyping — Test different reference combinations, LoRAs, and edit instructions quickly.
Pro Tips
- Refer to every important input explicitly as
<Picture 1>,<Picture 2>, and so on. - Clearly state which reference controls each subject, object, style, or scene element.
- Describe both what should change and what should remain unchanged.
- Keep LoRA combinations focused to avoid competing visual directions.
- Use fewer reference images when multiple inputs provide redundant or conflicting guidance.
- Use
1Kfor lower-cost iteration before moving to higher resolutions. - Choose
pngwhen you want to avoid lossy compression or need a transparent background. - Set a fixed
seedwhen comparing LoRA, prompt, or reference changes.
Notes
promptandimagesare required.imagessupports between1and10reference images.- References can be addressed as
<Picture 1>through<Picture 10>. lorassupports up to3items.- Each LoRA item uses the
{path, scale}format. resolutiondefaults to1k.- Supported resolutions are
1k,1.5k, and2k. - Supported output formats are
jpeg,png, andwebp. pngandwebppreserve transparency;jpegfills transparent areas with white.seed=-1selects a random seed.- Additional reference images increase the price based on resolution.
Related Models
- Qwen Image 2.1 Text-to-Image — Generate images directly from text prompts.
- Qwen Image 2.1 Text-to-Image LoRA — Generate images from text prompts with LoRA customization.
- Qwen Image 2.1 Edit — Edit images with text instructions and up to 10 reference images.
- Qwen Image 2.1 Edit LoRA — Edit images with multi-reference guidance and LoRA customization.
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": "1k",
"output_format": "jpeg"
}
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/wavespeed-ai/qwen-image-2.1/edit-lora" \
-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
doneRetry temporary errors only while polling, never the submit request. Errors, retries and timeouts
Parameters
Task Submission Parameters
Request Parameters
| Parameter | Type | Required | Default | Range | Description |
|---|---|---|---|---|---|
| prompt | string | Yes | - | The edit instruction. Refer to references as <Picture 1> through <Picture 10>. | |
| images | array<string> | Yes | - | 1 ~ 10 items | Reference images to edit from (1 to 10 URLs). The first image also sets the output aspect ratio unless aspect_ratio is given. |
| aspect_ratio | string | No | - | 1:1, 1:2, 2:1, 1:3, 3:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 9:21, 21:9 | The aspect ratio of the generated image. If not specified, it is determined automatically from the input image. |
| resolution | string | No | 1k | 1k, 1.5k, 2k | Total output resolution tier: 1K (~1 megapixel), 1.5K (~2.25 megapixels), or 2K (~4 megapixels). |
| output_format | string | No | jpeg | jpeg, png, webp | The format of the output image. |
| loras | array<object> | No | 0 ~ 3 items | List of LoRAs to apply (max 3). | |
| loras[].path | string | Yes | - | - | - |
| loras[].scale | number | No | 1 | 0 ~ 4 | - |
| seed | integer | No | - | - | The random seed. -1 means random. |
Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| code | integer | HTTP status code (e.g., 200 for success) |
| message | string | Status message (e.g., “success”) |
| data.id | string | Unique identifier for the prediction, Task Id |
| data.model | string | Model ID used for the prediction |
| data.outputs | array | Output values, usually URL strings; some models return text strings or structured result objects (empty when status is not completed) |
| data.urls | object | Object containing related API endpoints |
| data.status | string | Task status. completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses. |
| data.created_at | string | ISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”) |
| data.error | string | Error message (empty if no error occurred) |
| data.timings | object | Object containing timing details |
| data.timings.inference | integer | Inference time in milliseconds |
Result Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| id | string | Yes | - | Task ID |
Result Response Parameters
| Parameter | Type | Description |
|---|---|---|
| code | integer | HTTP status code (e.g., 200 for success) |
| message | string | Status message (e.g., “success”) |
| data | object | The prediction data object containing all details |
| data.id | string | Unique identifier for the prediction |
| data.model | string | Model ID used for the prediction |
| data.outputs | array<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.urls | object | Object containing related API endpoints |
| data.status | string | Status: completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses |
| data.created_at | string | ISO timestamp of when the request was created |
| data.error | string | Error message (empty if no error occurred) |
| data.timings | object | Object containing timing details |
| data.timings.inference | integer | Inference time in milliseconds |