Qwen Image 2.1 Edit LoRA API Documentation

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 to 3 custom LoRA weights in the same request.

  • Up to 2K resolution
    Generate edited results at 1K, 1.5K, or 2K.

  • Flexible aspect ratios
    Adjust the output composition for different creative workflows.

  • Multiple output formats
    Export edited images as jpeg, png, or webp.

  • Native transparency Generate images with a real alpha channel. Ask for transparency in the prompt and export as png or webp.


Parameters

ParameterRequiredDescription
promptYesText instruction describing the desired edit. Refer to supplied images as <Picture 1> through <Picture 10> when needed.
imagesYesReference image URLs. Supports between 1 and 10 images.
lorasNoUp to 3 LoRA objects. Each item uses {path, scale}.
resolutionNoOutput resolution: 1k, 1.5k, or 2k. Default: 1k.
aspect_ratioNoOptional output aspect ratio.
output_formatNoOutput image format: jpeg, png, or webp. Use png or webp to preserve transparency; jpeg fills transparent areas with white.
seedNoOptional random seed for generation. Use -1 for a random seed.

How to Use

  1. Upload reference images — Provide between 1 and 10 images in images.
  2. Write the editing prompt — Describe what should change and refer to specific inputs as <Picture 1>, <Picture 2>, and so on.
  3. Add LoRAs optional — Provide up to 3 LoRA files with individual scale values.
  4. Choose resolution — Select 1k, 1.5k, or 2k.
  5. Choose aspect ratio optional — Set the desired output composition.
  6. Choose output format optional — Select jpeg, png, or webp.
  7. Set seed optional — Use a fixed seed for reproducible results, or -1 for random generation.
  8. 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.

  1. 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.
  2. Set output_format to png or webp. 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.

Resolution1 imageEach additional image2 images5 images10 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 1K for lower-cost iteration before moving to higher resolutions.
  • Choose png when you want to avoid lossy compression or need a transparent background.
  • Set a fixed seed when comparing LoRA, prompt, or reference changes.

Notes

  • prompt and images are required.
  • images supports between 1 and 10 reference images.
  • References can be addressed as <Picture 1> through <Picture 10>.
  • loras supports up to 3 items.
  • Each LoRA item uses the {path, scale} format.
  • resolution defaults to 1k.
  • Supported resolutions are 1k, 1.5k, and 2k.
  • Supported output formats are jpeg, png, and webp.
  • png and webp preserve transparency; jpeg fills transparent areas with white.
  • seed=-1 selects a random seed.
  • Additional reference images increase the price based on resolution.

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
done

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

Parameters

Task Submission Parameters

Request Parameters

ParameterTypeRequiredDefaultRangeDescription
promptstringYes-The edit instruction. Refer to references as <Picture 1> through <Picture 10>.
imagesarray<string>Yes-1 ~ 10 itemsReference images to edit from (1 to 10 URLs). The first image also sets the output aspect ratio unless aspect_ratio is given.
aspect_ratiostringNo-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:9The aspect ratio of the generated image. If not specified, it is determined automatically from the input image.
resolutionstringNo1k1k, 1.5k, 2kTotal output resolution tier: 1K (~1 megapixel), 1.5K (~2.25 megapixels), or 2K (~4 megapixels).
output_formatstringNojpegjpeg, png, webpThe format of the output image.
lorasarray<object>No0 ~ 3 itemsList of LoRAs to apply (max 3).
loras[].pathstringYes---
loras[].scalenumberNo10 ~ 4-
seedintegerNo--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

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.