VidgoAI

Qwen Image 2.1 Edit API

alibaba/qwen-image-2.1/edit
1K / 2K · 6 / 10 credits

Qwen Image 2.1 Edit turns 1-10 reference images and instructions into precise edits, with multi-image feature fusion and masked inpainting. It preserves facial features and product materials while replacing backgrounds naturally and retaining every pixel outside the mask.

Get API Key
Input
1192 / 5,000

Drag and drop files, paste from clipboard, or provide a URL. 1–10 ordered images. JPEG, PNG, or WebP, up to 30 MB and 25 megapixels each.

2/10 files added

Drag and drop files, paste from clipboard, or provide a URL. Requires one reference image and opaque background. White areas change; black areas stay unchanged. Match the reference aspect ratio.

OutputReady
6 credits / image · $0.030

Continue with

Qwen Image 2.1 Text to ImageGrok Imagine Image 2.0 EditSeedream 5.0 Flash Edit

Examples

The First Chair Repaired After the Flood

Repair only the damaged oak chair inside the white area of the supplied mask. Replace the broken seat plank with a structurally complete oak plank and mend the snapped upper backrest rail so the same chair is whole, stable and usable again. Match the existing oak color, aged wood grain, joinery, perspective and soft window lighting; keep the chair's original design and position. Retain subtle signs of age rather than making it a new manufactured chair. Preserve every pixel in the black mask area: the elderly carpenter, face, blue apron, workbench, tools, window, walls, mud marks and floor outside the chair region must remain unchanged. The image tells the story of the first small repair after the flood. Do not add people, objects, text, logos, brands or watermark.

The Seaside Kite, Ready for a Memory Book

This is an RGBA image with transparency. Extract only the exact handmade swallowtail kite from image 1 as a transparent cutout, including both complete long ribbon tails and the thin curled kite string. Preserve the original swallowtail outline, pale turquoise rice-paper panels, muted vermilion edging, fine bamboo ribs, ivory repair patch on the left wing, paper fibers, knots, colors, scale and lighting. Preserve fine gaps between string, ribbons and kite; retain the subtly translucent quality of thin rice paper where appropriate. Remove the wooden peg, cottage eave, plaster wall, sea and every other background element. Keep the entire original kite, tails and curled string within the output frame without cropping, stretching, redesigning or adding anything. Real alpha transparency, no colored backdrop, floor, cast shadow outside the kite or drawn checkerboard. This is a keepsake from a seaside flight, not a product advertisement. No text, brand, logo or watermark. The background is transparent.

Qwen Image 2.1 Edit

Qwen Image 2.1 Edit is a unified image editing model developed by Alibaba's Tongyi team. Using joint Qwen3-VL encoding and Prefix KV caching, its 7B architecture supports feature fusion across up to 10 reference images, single-image masked inpainting, and RGBA transparent-layer editing. It delivers industrial-grade editing for e-commerce virtual try-on, product redesign, and subject extraction without manual background removal.

Why Choose Qwen Image 2.1 Edit?

  • Powerful mixing and fusion with 1-10 reference imagesProvide up to 10 reference images in one request to naturally combine model portraits, garment cuts, accessories, and backgrounds. Create cross-image e-commerce virtual try-on results and multi-subject composites with ease.

  • Precise masked inpainting with non-destructive pixel preservationSupply a black-and-white Mask Url with a single reference image. White regions are precisely repainted, while black regions retain 100% of their original pixels, preventing unwanted changes across the image.

  • Consistent subject identity and product texturesUnified Qwen3-VL visual-language representations retain facial contours, feature proportions, clothing patterns, and product textures, maintaining strong consistency through complex edits and style transfers.

  • Native RGBA layer extraction and transparent editingA built-in 64-channel RGBA autoencoder extracts isolated subjects with transparency directly from standard RGB photographs. Create industrial-grade transparent stickers and edit assets without manual background removal.

  • Prefix KV caching accelerates multi-image inference with no reference or mask surchargePrefix Key-Value caching significantly reduces multi-reference denoising computation. Billing depends only on output resolution, with no extra charge for additional reference images or masks.

Parameters

ParameterRequirementDescription
promptRequired

Required non-blank text, up to 5,000 characters after trimming leading and trailing whitespace.

image_urlsRequired

Add 1-10 images in order. JPEG, PNG, or WebP, up to 30 MB and 25 MP each.

mask_urlOptional

Requires exactly one reference image and background set to opaque. White areas are edited; black areas are preserved. Match the reference aspect ratio. size and prompt_extend are ignored when a mask is supplied.

sizeOptional

Choose a supported aspect ratio. Edit defaults to auto; generation defaults to 1:1. Ignored when a mask is supplied.

Defaultauto1:14:33:43:22:316:99:1621:99:21
resolutionOptional

1K: 6 credits ($0.030); 2K: 10 credits ($0.050).

Default1K2K
output_formatOptional

Supports png, jpeg, and webp. Transparent backgrounds require png or webp.

Defaultpngjpegwebp
backgroundOptional

Supports opaque and transparent. A mask requires opaque.

Defaultopaquetransparent
prompt_extendOptional

Automatically expand the prompt. Ignored when a mask is supplied.

Defaulttrue
enable_safety_checkerOptional

Enable content safety checking.

Defaulttrue
seedOptional

Optional integer or decimal integer string. Use a string outside the JavaScript safe integer range; leave empty for a random seed.

How to Use

  1. Upload 1-10 reference imagesUpload through the interface or add 1-10 publicly accessible image URLs to image_urls. Arrange the images in the order they are referenced in your prompt.

  2. Write editing instructions and add an optional maskClearly describe the intended changes in prompt. For precise local edits, upload a black-and-white Mask Url image with the same aspect ratio as the reference: white for repainting and black for preservation.

  3. Set the output aspect ratio and resolutionThe aspect ratio defaults to auto to follow the reference image. You can also choose a specific ratio, such as 1:1 or 16:9, then select 1K or 2K resolution and the required format.

  4. Submit an asynchronous editing task and retrieve the resultSend the API request to receive task_id. Once background processing is complete, use the status endpoint to retrieve the URL of the edited high-resolution image.

Pricing

One image per request, billed by resolution. No extra charge for reference images or masks. 1 credit = $0.005.

UsageRateDetails
1K6 credits / image$0.030 / image
2K10 credits / image$0.050 / image

Best Use Cases

  • E-commerce virtual try-on with multiple clothing referencesProvide a model photo alongside reference images of clothing, shoes, and bags. Fit the selected items naturally to the model to create commercial try-on images with realistic lighting and fabric folds.

  • Background replacement and scene transfer for product photographyPreserve the original product appearance, packaging text, and material details while moving simple white-background still-life photos into beach scenes, modern minimalist interiors, or naturally lit outdoor settings.

  • Precise local retouching and detail changesUse a black-and-white mask to identify hand poses, facial expressions, clothing prints, or background clutter to change. Apply targeted inpainting while preserving the rest of the image without loss.

  • Subject extraction and transparent layer creationInput a standard photograph and select transparent background mode to extract a person, pet, or standalone product as an RGBA layer with a transparent background, ready for poster layouts and compositing.

Pro Tips

  • Assign clear roles to each reference: When uploading multiple images, identify their subjects in the prompt, such as "Use the pose of the person in image 1 with the jacket style and material from image 2." This helps the model allocate visual features accurately.
  • Meet the mask requirements: Local editing with mask_url requires exactly one reference image and background set to opaque. Match the mask dimensions and aspect ratio to the reference. White indicates repainting; black locks and preserves the original pixels.
  • Keep auto as your first choice: The Edit endpoint defaults size to auto, following the first reference image's native aspect ratio to prevent unexpected stretching or edge cropping.
  • Understand the mask dependencies: When mask_url is supplied, the backend automatically ignores size and prompt_extend, focusing on precise inpainting within the mask boundaries and the original image structure.

Notes

  • image_urls is required and accepts 1-10 ordered image URLs. Each image must be JPEG, PNG, or WebP and no larger than 30 MB or 25 million pixels (25 MP).
  • mask_url is valid only with exactly one reference image and background set to opaque. size and prompt_extend are automatically ignored when a mask is used.
  • Billing depends on output resolution: 1K costs 6 credits ($0.030), and 2K costs 10 credits ($0.050). The number of reference images and use of a mask do not add any extra credits.
  • The model is open-sourced under the Qwen Research License for research evaluation. Commercial deployment and sales must follow the official license and commercial authorization terms.

Related Models

Qwen Image 2.1 Text to Image previewQwen Image 2.1 Text to ImageAn efficient text-to-image model with native 2K quality, 64-channel RGBA transparency, and Chinese-English typography.
Grok Imagine Image 2.0 Edit previewGrok Imagine Image 2.0 EditAn xAI image editing model with multi-reference fusion and intelligent aspect ratio adaptation.
Seedream 5.0 Flash Edit previewSeedream 5.0 Flash EditA cost-effective ByteDance image editing endpoint with multi-reference fusion and fast local edits.

Qwen Image 2.1 Edit API Frequently Asked Questions

What is the Qwen Image 2.1 Edit API?

Qwen Image 2.1 Edit is a unified image editing model developed by Alibaba's Tongyi team. It generates high-fidelity edits from 1-10 reference images and natural-language instructions, with multi-image feature fusion, masked inpainting, subject extraction without manual background removal, and native aspect ratio adaptation. Built on a 7B-parameter Single-Stream DiT architecture and a Qwen3-VL encoder, it replaces backgrounds and performs local edits while precisely preserving facial identity, product materials, and original pixels outside the mask. You can call it programmatically through the API or try it online in the playground above.

How many reference images can I upload to Qwen Image 2.1 Edit?

The model accepts 1-10 ordered images in image_urls for complex cross-image subject compositing and multi-element transfer. Efficient Prefix KV caching computes the visual features of all reference images in the first sampling step and reuses them throughout. This maintains high inference efficiency and stable GPU memory usage even with up to 10 high-resolution images.

How do I use a mask for inpainting with Qwen Image 2.1 Edit?

Provide a black-and-white mask image through mask_url. Masked editing requires exactly one reference image and background set to opaque. White regions mark the areas to repaint; black regions are strictly locked to preserve the original pixels without loss. Once a mask is supplied, the system automatically ignores size and prompt_extend so the output retains the original image's geometry and level of detail.

How does Qwen Image 2.1 Edit preserve facial identity and product details?

Qwen3-VL aligns text and images in a unified semantic space, giving the model strong memory for facial identity and product form. During background replacement, relighting, or clothing changes, it retains facial geometry, hair direction, brand logos, and specific textures. For the best consistency, use targeted instructions such as "Keep the subject's face unchanged and only replace the background with...".

Can Qwen Image 2.1 Edit extract transparent subjects from ordinary photos?

Yes. The endpoint uses a powerful 64-channel RGBA autoencoder to extract the main subject from a standard RGB photo into an independent layer with transparency. Set background to transparent, choose png or webp, and use an instruction such as "Extract the main subject and make the background fully transparent." This produces clean, smooth-edged transparent assets without additional background removal tools.

Does uploading multiple reference images to Qwen Image 2.1 Edit cost extra?

No. Qwen Image 2.1 Edit is billed only by resolution: each 1K generation costs 6 credits ($0.030), and each 2K generation costs 10 credits ($0.050). Each credit is worth $0.005. Whether you provide one reference image, 10 reference images, or a local inpainting mask, there is no extra charge for input assets or computation.

Can Qwen Image 2.1 Edit automatically match the original aspect ratio?

Yes. The Edit endpoint defaults size to auto. In auto mode, the model reads and inherits the first reference image's original aspect ratio, preventing cropping or stretching caused by a mismatch. To expand or recompose the original image into a specific format, select another preset such as 1:1, 16:9, or 9:16.