Qwen-Image-Edit API: Integration Guide, Pricing & Code

Alibaba sells image editing under three different naming layers at once. The open-weights lineage goes Qwen-Image-Edit → -2509 → -2511; Alibaba Cloud Model Studio sells dedicated editing tiers called qwen-image-edit, qwen-image-edit-plus, and qwen-image-edit-max; and the newer qwen-image-2.0 / 2.0-pro / 3.0 generations fold editing into the same model IDs they use for generation. Reseller pages bill per image, per megapixel, or not at all — one provider’s “Qwen Image Edit API: Pricing” page currently consists of a single line saying the model is unavailable on its serverless API. If you just want to know which model ID to call, what one edited image costs today, and how to run a first request, the official documentation makes you assemble that from three pages in two regions.

This guide does it in one pass as of September 9, 2026: what the Qwen image editing API actually is, the model lineup and naming map, official per-image prices read from the live pricing page today, runnable curl and Python for the direct Alibaba route, the parameter traps that cost the most debugging time, and the aggregator route through Modellix for when you do not want a per-vendor Alibaba project. One disclosure up front: Modellix operates this blog and has a commercial interest in the second route, so both sides carry their own prices and the comparison stays like-for-like. For the full family map — qwen-image, plus, max, and the 3.0 generation tiers — see our Qwen Image API guide; this article is the editing deep dive.

What the Qwen image editing API is in 2026: one capability, three naming layers

The Qwen image editing API is instruction-based editing: you send one to three images plus a sentence describing the change, and the model returns an edited PNG. No mask is required — unlike classic inpainting pipelines, there is no mask-drawing step, no separate segmentation pass, and no per-region prompt. You describe the edit (“change the background to a modern cafe”, “remove the person on the left”, “make the sign read ‘Grand Opening’ in the same font”) and the model handles localization itself. That mask-free workflow is the family’s defining trait and why editing calls reuse the generation API’s request shape.

What editing models are called is where the confusion starts. Three naming layers describe overlapping capabilities, and most pages document only one of them:

Layer	Model IDs you can call	What it is
Open checkpoints	Qwen-Image-Edit, -2509, -2511 (Hugging Face / ModelScope)	The open-weights releases. Not API names — platforms wrap them under their own IDs
Dedicated editing tiers (Model Studio)	qwen-image-edit, qwen-image-edit-plus, qwen-image-edit-max	Editing-only models, priced per image, each pinned to a dated snapshot (e.g. qwen-image-edit-max-2026-01-16)
Unified generation + editing (Model Studio)	qwen-image-2.0, qwen-image-2.0-pro, qwen-image-3.0, qwen-image-3.0-pro	One model ID does text-to-image and image editing; the 3.0 series bills input images separately

The dedicated tiers are the original editing lineup. qwen-image-edit-plus carries the cheapest bulk rate on the page ($0.03 per image, up to six outputs per call); qwen-image-edit is the minimal tier (single-image editing and multi-image fusion, fixed one output); qwen-image-edit-max is the top tier (industrial design, geometric reasoning, character consistency). Alibaba’s own editing API reference documents all of them on one page with the same endpoint and the same parameter set. Since Qwen Image 3.0 launched in July 2026, the newer generations serve editing through the unified model IDs instead — Alibaba’s 3.0 reference describes the same 1–3 input images plus instruction, with 3.0-series input images billed at $0.003 each. If you are integrating the 2.0 generation specifically, our Qwen Image 2.0 API deep dive covers its dated snapshot IDs and endpoint quirks.

One disambiguation for the search-confused: Qwen-Image-2512 is a generation checkpoint, not an editing one — the editing checkpoints are 2509 and 2511.

The three naming layers of Qwen image editing, as of September 9, 2026. Diagram generated for this article, not a screenshot of a console.

Qwen image edit API pricing, read September 9, 2026

Official pricing is per successfully generated image — if a call returns three of four requested outputs, you pay for three, and failed calls cost nothing and do not consume free quota. The rates below were read from Alibaba’s Model Studio pricing page on September 9, 2026, Singapore (International) deployment — the one to use without a Chinese mainland account:

Model ID	Output price (Singapore)	Outputs per call	Free quota
qwen-image-edit	$0.045 / image	Fixed 1	100 images
qwen-image-edit-plus (= -2025-10-30; -2025-12-15 snapshot also $0.03)	$0.03 / image	1–6	100 images
qwen-image-edit-max (= -2026-01-16)	$0.075 / image	1–6	100 images
qwen-image-2.0 / 2.0-pro (unified, edit = same rate as generation)	$0.035 / $0.075	1–6	100 images
qwen-image-3.0	$0.03 output + $0.003 per input image	1–6	10 images
qwen-image-3.0-pro	$0.04 (1K) / $0.075 (2K) output + $0.003 per input image	1–6	10 images

Three reading notes. First, the free quota exists only in the Singapore region, is valid 90 days from account activation or the model’s release (whichever is later), and does not apply to other regions — Alibaba’s page says so explicitly for every editing model. Second, the two billing generations differ in structure: the dedicated editing tiers and the 2.0 series charge output only, while the 3.0 series adds a $0.003 input fee per image you send (so a single-image 3.0 edit at 1K costs $0.033, and a Pro edit at 2K costs $0.078). Third, treat the whole table as a dated snapshot — these prices move, and the Alibaba API pricing guide tracks the provider catalog if you are budgeting across models.

Calling the Qwen image edit API directly on Alibaba Cloud Model Studio

You need three things: a Model Studio account, an API key, and the workspace ID embedded in the endpoint. The editing models are synchronous and single-turn — the API reference states “asynchronous interfaces are not supported”, and each request carries exactly one user message containing one to three images plus exactly one text instruction. Only the legacy text-to-image models qwen-image and qwen-image-plus support the async task workflow; every editing call on this family is a direct request-response.

Base URL and auth. Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation. Beijing is a separate deployment ({WorkspaceId}.cn-beijing.maas.aliyuncs.com) with its own API key — keys and endpoints are region-scoped and cannot be mixed; a Beijing key against a Singapore endpoint fails with an auth or service error. Input images can be public HTTPS URLs or Base64 (data:image/jpeg;base64,...), up to 10 MB each, in JPG/JPEG/PNG/BMP/TIFF/WEBP/GIF (animated GIFs: only the first frame is processed).

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "qwen-image-edit-max",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            { "image": "https://your-cdn.example.com/product-shot.png" },
            { "text": "Change the background to a clean bright studio scene and keep the product pixel-identical." }
          ]
        }
      ]
    },
    "parameters": {
      "n": 2,
      "negative_prompt": "blurry, distorted, extra objects",
      "prompt_extend": true,
      "watermark": false,
      "size": "1536*1024"
    }
}'

The response returns the edited images as temporary URLs:

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            { "image": "https://dashscope-result-xxx.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=..." },
            { "image": "https://dashscope-result-xxx.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=..." }
          ]
        }
      }
    ],
    "usage": { "width": 1536, "height": 1024, "image_count": 2 },
    "request_id": "bf37ca26-0abe-98e4-8065-xxxxxx"
  }
}

The Python equivalent with the DashScope SDK is the same shape, with the region base URL set explicitly:

import os
import dashscope
from dashscope import MultiModalConversation

dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"  # Singapore; replace {WorkspaceId}

response = MultiModalConversation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen-image-edit-max",
    messages=[{
        "role": "user",
        "content": [
            {"image": "https://your-cdn.example.com/product-shot.png"},
            {"text": "Change the background to a clean bright studio scene and keep the product pixel-identical."},
        ],
    }],
    parameters={"n": 2, "prompt_extend": True, "watermark": False},
)

if response.status_code == 200:
    urls = [c["image"] for c in response.output.choices[0].message.content if "image" in c]
    print(urls)  # download these now — they expire in 24 hours

Download result URLs immediately: output images and task data are retained for 24 hours and then purged. The usage object reports image_count — that is what you are billed on.

Every Qwen editing call on the direct route is one synchronous request: images plus an instruction in, edited PNG URLs out. No mask, no async task, no second endpoint. Diagram generated for this article.

Qwen image edit API parameters that actually matter

The parameter set is small and mostly optional, and four knobs change your results more than the rest:

• n — number of output images, 1–6 on edit-plus, edit-max, and the 2.0/3.0 unified models; fixed at 1 on qwen-image-edit.
• size — on edit-plus/edit-max, each dimension can range 512–2048 (recommended presets for 1:1, 2:3, 3:2, 4:3, 9:16, 16:9, and 21:9 are documented on the reference page); on the 2.0 series, total pixels must land between 512² and 2048²; on qwen-image-edit, resolution is not customizable — output follows the input. Values snap to the nearest multiple of 16.
• prompt_extend — defaults to true and silently rewrites your instruction for more detail. Leave it on for natural-language edits, off when you need tight composition control. Not supported on qwen-image-edit.
• negative_prompt — up to 500 characters, supported on all tiers except the base qwen-image-edit. Useful for “low resolution, distorted hands, warped text”-style exclusions on batch edits.

Three input constraints bite more often than the parameters do. Exactly one text object per request — the content array must contain one to three image objects and a single instruction; a second text object is an error, and multi-turn conversation is not supported, so wrap each edit in its own call. Image dimensions between 384 and 3072 pixels give the best results; smaller inputs come back blurry, larger ones just slow the call down. Prompt length is capped at 1,300 tokens for the 2.0 series and 800 tokens for the other editing models, with excess silently truncated — if a detailed instruction keeps losing its tail, that cap is why. And the base qwen-image-edit takes no n, no size, no negative_prompt, and no prompt_extend — it is the minimal fusion tier, not a cheaper copy of plus.

Calling Qwen image editing through Modellix: the two 3.0 Edit endpoints

The direct Alibaba route is the whole story when Qwen editing is your only image workload. The aggregator route exists for the situation where you want Qwen image editing and other vendors’ models behind one key and one bill, without creating a per-vendor cloud account. Same disclosure as the top: Modellix runs this blog and has a commercial interest in this route. What follows is what Modellix’s own catalog shows today, not a claim about any other gateway.

As of September 9, 2026, Modellix does not list the legacy dedicated tiers — requesting qwen-image-edit, edit-plus, or edit-max on its Alibaba provider renders “Model Not Found”. What it does list are the current-generation editing endpoints: Qwen Image 3.0 Edit at a displayed $0.0297/image and Qwen Image 3.0 Pro Edit at $0.0702/image, each documented with the request shape below. Those are flat per-image list prices read from the model pages today — Modellix displays one rate where Alibaba’s 3.0 pricing decomposes into output plus a $0.003 input fee, so treat them as a same-day snapshot and re-verify before budgeting.

curl --request POST \
  --url https://api.modellix.ai/api/v1/alibaba/qwen-image-3.0-edit \
  --header 'Authorization: Bearer $MODELLIX_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "images": [
      "https://your-cdn.example.com/product-shot.png"
    ],
    "prompt": "Change the background to a modern cafe"
  }'

Media generation on Modellix is asynchronous, so the first call returns a task handle rather than an image; poll the returned get_result URL until the status is success, then download the output. If you prefer not to poll, send an X-Webhook-URL header and Modellix POSTs the result when the task finishes — the pattern is in the Modellix API documentation and on the per-model Qwen Image 3.0 Edit reference.

Qwen Image Edit on the Modellix API

See the async task routes and request schema for the Qwen Image 3.0 Edit endpoints behind one Modellix key.

View Docs

Why pick the gateway over direct? The honest reasons: one key for Qwen editing and the rest of a multi-vendor media pipeline, no Chinese mainland account needed, per-call cost logs, and pay-as-you-go billing with no prepaid packages. The honest boundary: for a single editing model at high volume, direct Alibaba billing can still be cheaper per image — the Modellix trade is one key and one bill across many vendors, not a guaranteed lower unit price. When editing is one of ten models in a pipeline rather than the whole product, that trade usually wins; our unified AI API explainer covers the architecture.

Common Qwen image edit API errors and how to fix them

The failures that burn the most time on a first integration are mostly naming and region problems, not model problems:

1. Region mismatch. A Beijing key against the Singapore endpoint fails, and vice versa. Keys, endpoints, and workspace IDs are region-scoped — pick one region and keep all three in sync.
2. InvalidApiKey. The key is wrong, or it belongs to a different region/deployment than the endpoint you called. Both arrive in the same {"code", "message", "request_id"} envelope — check the code before assuming the key is dead.
3. More than one text object in the content array. Exactly one instruction per request and no multi-turn conversation — each edit is its own call.
4. n rejected on qwen-image-edit. The base tier is fixed at one output image and takes no custom size, negative prompt, or prompt extension. Sending those parameters returns an error, not a graceful ignore.
5. Dead image URL by deploy time. Result URLs and task data expire after 24 hours. Download to your own storage (S3, R2, your server) at generation time.
6. Instruction tail silently dropped. Prompts over 800 tokens (1,300 on the 2.0 series) are truncated without warning — cut length before blaming the model.
7. Image rejected at input. Over 10 MB or an unsupported format fails the request; keep input dimensions between 384 and 3072 pixels for best results.

Choosing an editing model and a route

Editing-model choice comes down to output flexibility and quality tier; route choice comes down to how many vendors your pipeline touches:

Your editing workload	Start with
Batch edits at the lowest price, 1–6 outputs per call	qwen-image-edit-plus ($0.03)
Character/object consistency, geometric or industrial edits	qwen-image-edit-max ($0.075)
Multi-image fusion or single fixed output, minimal params	qwen-image-edit ($0.045) — or qwen-image-edit-plus at n=1 ($0.03) when you only need a single output
One model ID for generation and editing	qwen-image-2.0/2.0-pro, or qwen-image-3.0/3.0-pro if you also want the newest text rendering
Many vendors’ models behind one key, no per-vendor account	Modellix (qwen-image-3.0-edit / 3.0-pro-edit)
Self-hosting on your own GPUs	Open checkpoints (2509/2511) on Hugging Face / ModelScope

For the cross-vendor picture of production editing workflows, our image manipulation API guide maps how editing APIs fit into a pipeline end to end.

A practical first step that costs a few cents: run the same edit instruction through both routes once, keep the outputs you trust, and log the per-image cost from each bill. Prices above were read on September 9, 2026; pin the date when you record a number and re-check the live pages before you scale.

Start Editing with Qwen on Modellix

Log in to Modellix to call Qwen Image 3.0 Edit and 200+ other image and video models through one API key.

Login

Frequently Asked Questions

What is the Qwen image editing API?

The Qwen image editing API is Alibaba’s hosted interface to Qwen’s instruction-based image editing models: send one to three images plus a natural-language instruction, and the model returns edited PNGs without any mask or segmentation step. It is available through Alibaba Cloud Model Studio (DashScope) with dedicated editing tiers (qwen-image-edit, edit-plus, edit-max), through the unified generation-and-editing models (qwen-image-2.0/2.0-pro/3.0/3.0-pro), and through aggregators such as Modellix.

How much does the Qwen image edit API cost?

As of September 9, 2026, Singapore-region prices are $0.045 per image for qwen-image-edit, $0.03 for edit-plus, and $0.075 for edit-max, billed per successfully generated image; the 3.0 series charges $0.003 per input image plus $0.03–$0.075 per output depending on model and resolution. All editing models carry a free quota in the Singapore region only (100 images for the dedicated tiers and 2.0 series, 10 for the 3.0 series, valid 90 days).

Do I need a mask to edit with Qwen-Image-Edit?

No. Editing is instruction-based and mask-free: you describe the change in natural language and the model localizes it, unlike classic inpainting pipelines that require a drawn mask and a per-region prompt. It shares the generation API’s request shape for that reason.

What is the difference between qwen-image-edit, edit-plus, and edit-max?

They are quality tiers of the dedicated editing lineup. qwen-image-edit is the minimal tier: single-image editing and multi-image fusion, one fixed output, no size control. qwen-image-edit-plus ($0.03) adds 1–6 outputs and custom resolutions at the lowest price. qwen-image-edit-max ($0.075) is the top tier, positioned for industrial design, geometric reasoning, and character consistency.

Can Qwen image editing be called through Modellix?

Yes — but not every tier. As of September 9, 2026, Modellix’s catalog lists the current-generation endpoints Qwen Image 3.0 Edit ($0.0297/image) and Qwen Image 3.0 Pro Edit ($0.0702/image) on its Alibaba provider; the legacy qwen-image-edit/edit-plus/edit-max tiers are not listed. Calls use one API key, one async submit-and-poll pattern, and pay-as-you-go billing.

Is Qwen-Image-Edit open source?

The model family is open weights: the original Qwen-Image-Edit release and its 2509/2511 checkpoints are distributed on Hugging Face and ModelScope under an Apache-2.0 license — NVIDIA’s model card lists Apache-2.0 and commercial use — which is why fal, Replicate, and others host it. Open weights mean you can self-host; the hosted APIs are still billed per image.

How many images can I edit per request?

One to three input images (used for editing and for multi-image fusion, with the last image setting the output aspect ratio) and one to six output images, except on the base qwen-image-edit, which accepts a single output only. The output format is always PNG.

Do I need a Chinese account for the Qwen image edit API?

No. The Singapore (International) region of Model Studio is open to international accounts and has its own API key and endpoint. Do not mix Singapore and Beijing keys — the two deployments are region-scoped and cross-region calls fail.

---

Provider details and pricing reflect public information as of September 9, 2026 and change frequently — the editing models, their snapshots, and aggregator listings shift without notice. Validate against Alibaba’s official pricing page and the specific provider’s live model page before committing budget. This article was written by Modellix, an API aggregator with a commercial interest in the single-key route it describes; the official Alibaba integration material above is vendor-neutral, and the Modellix prices quoted are a same-day snapshot rather than a standing claim. Access image and video models, including the leading Chinese models, through a single API key at modellix.ai.

Cover image: illustrative Modellix artwork; it is not an Alibaba product screenshot or source evidence.