Qwen-Image Edit Max

alibaba/qwen-image-edit-max — a image model by Alibaba. Call it through the gateway’s standard OpenAI-compatible door using the catalog slug; the full parameter schema is reproduced in full below.

Catalog slug	alibaba/qwen-image-edit-max
Kind	image
Vendor	Alibaba
Native model id	qwen-image-edit-max

How to call

Through the Sociaro SDK / OpenAI-compatible door

from sociaro_ai import Sociaro

client = Sociaro(api_key="gw_live_...")

img = client.images.generate(
    model="alibaba/qwen-image-edit-max",
    prompt="make it night",
    extra_body={"image": "https://example.com/input.png"},  # edit input (URL or data-URI); or "images": [...]
    # size / n / negative_prompt / seed … — see the schema below
)

This is an edit model — pass your input image via image (a URL/data-URI string or array) or images (array). Without it the provider rejects the request. Raw door: POST https://api.sociaro.com/v1/images/generations with {"model": "alibaba/qwen-image-edit-max", "prompt": "…", "image": "https://…"}. See media doors.

Through Alibaba DashScope’s native API (advanced)

Optional: send Alibaba DashScope’s native request to the /alibaba prefix, using the native model id qwen-image-edit-max. The gateway injects the upstream Alibaba DashScope credential and forwards the body unchanged (catalog, pricing and entitlements still apply).

curl https://api.sociaro.com/alibaba/<native-path> \
  -H "Authorization: Bearer $SOCIARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "qwen-image-edit-max", ... }'

The exact path, request body and response shape are documented in full in the schema below.

Parameters — full schema

The complete, one-to-one API schema for this model, transcribed from the official source. Nothing omitted. Examples in the schema may use a representative model of the family — for this model use the slug alibaba/qwen-image-edit-max (or the native id qwen-image-edit-max for the native API) as shown in How to call above.

COVERAGE MAP — which official page documents each requested slug

requested slug	documented on page(s)	gen / edit	dated snapshots
qwen-image-2.0	qwen-image-api (text2image) AND qwen-image-edit-api (edit)	both	qwen-image-2.0-2026-03-03
qwen-image-2.0-pro	qwen-image-api (text2image) AND qwen-image-edit-api (edit)	both	qwen-image-2.0-pro-2026-04-22, qwen-image-2.0-pro-2026-03-03
qwen-image-edit-max	qwen-image-edit-api	edit only	qwen-image-edit-max-2026-01-16
qwen-image-edit-plus	qwen-image-edit-api	edit only	qwen-image-edit-plus-2025-12-15, qwen-image-edit-plus-2025-10-30
wan2.6-image	wan-image-generation-api-reference	both (edit / interleaved t2i)	— (no dated snapshot)
wan2.7-image	wan-image-generation-and-editing-api-reference	both	—
wan2.7-image-pro	wan-image-generation-and-editing-api-reference	both	—
z-image-turbo	z-image-api-reference	gen only	—

Also documented on the same pages (related slugs, included for completeness):

• qwen-image-max (== qwen-image-max-2025-12-30), qwen-image-plus (== qwen-image-plus-2026-01-09 / == qwen-image), qwen-image — all on qwen-image-api.
• qwen-image-edit — on qwen-image-edit-api (single/multi-image edit, NO custom size, NO prompt_extend, n fixed 1).

Async support summary:

• Qwen text2image async: ONLY qwen-image-plus and qwen-image. (qwen-image-2.0 / -2.0-pro / -max have NO async.)
• Qwen image-EDIT: NO async at all (sync only).
• Wan2.6-image: sync and async.
• Wan2.7-image / -pro: sync and async.
• Z-Image turbo: sync only (no async section in source).

---

CRITICAL PER-MODEL DIFFERENCES (do not mix parameter sets)

1. Shared endpoint, NOT shared parameter set. All synchronous calls in this family hit the SAME endpoint POST .../api/v1/services/aigc/multimodal-generation/generation, and the input.messages[].content shape (one text + zero-or-more image objects) is shared. But the parameters object differs sharply per family. The “shared request body” is effectively the Qwen/Z-Image shape; Wan2.6 and Wan2.7 add/remove parameters.

2. prompt_extend: present on Qwen text2image (default true), Qwen edit except qwen-image-edit (default true), Wan2.6-image (default true, effective only in edit mode enable_interleave=false), Z-Image turbo (default false; enabling it ADDS COST and returns reasoning + rewritten prompt). ABSENT on Wan2.7 (Wan2.7 uses thinking_mode instead).

3. negative_prompt: present on Qwen text2image, Qwen edit, Wan2.6-image. ABSENT on Wan2.7 and Z-Image turbo.

4. n (image count):

   • qwen-image-2.0 / -2.0-pro series (text2image): 1–6 (default 1).
   • qwen-image-max & qwen-image-plus & qwen-image (text2image sync): fixed 1 (other values error).
   • qwen-image async (plus / qwen-image): fixed 1.
   • Qwen EDIT: qwen-image-2.0 / qwen-image-edit-max / qwen-image-edit-plus series → 1–6; qwen-image-edit → fixed 1.
   • wan2.6-image: edit mode 1–4 (default 4); interleave mode must be 1 (use max_images).
   • wan2.7: image-set disabled 1–4 (default 1); image-set enabled 1–12 (default 12, model decides actual ≤ n).
   • z-image-turbo: no n parameter (fixed 1).

5. size:

   • Qwen text2image: width*height string. 2.0 series total px 512×512..2048×2048 (default 2048*2048); max/plus default 1664*928.
   • Qwen edit: width*height; 2.0 series total px 512×512..2048×2048; edit-max/edit-plus width & height each [512,2048]; system snaps to nearest multiple of 16; NOT supported on qwen-image-edit.
   • wan2.6: 1K(default, edit)/2K, or width*height (edit [768768,20482048] / interleave [768768,12801280], ratio [1:4,4:1]).
   • wan2.7: 1K/2K(default)/4K, or width*height; 4K only on wan2.7-image-pro text-to-image; wan2.7-image has NO 4K.
   • z-image-turbo: width*height, default 1024*1536 (range 512×512..2048×2048).

6. Wan2.7-only params: bbox_list (interactive box editing), enable_sequential (image-set), thinking_mode, color_palette. Wan2.6-only params: enable_interleave, max_images, stream (+ X-DashScope-SSE header for streaming interleave). Z-Image is the simplest: size + prompt_extend + seed only.

7. watermark text: Qwen stamps “Qwen-Image”; Wan2.6 / Wan2.7 stamp “AI Generated”; Z-Image has NO watermark param.

8. seed is universal across all five pages: integer, range [0, 2147483647], optional, random if omitted, same semantics (probabilistic — same seed only yields similar, not identical, output).

9. Response content shape differs:

   • Qwen (text2image + edit): content[] items are {"image": url} only (no type field).
   • Wan2.6 / Wan2.7: each content[] item carries a type field ("text" | "image") and output.finished (bool) is present.
   • Z-Image: content[] includes BOTH {"image": url} and {"text": ...} items, plus message.reasoning_content (only when prompt_extend=true).

10. usage object differs:

    • Qwen: {image_count, width, height} (+ input_tokens, output_tokens = 0 in SDK responses).
    • Wan2.6 / Wan2.7: {image_count, input_tokens, output_tokens, total_tokens, size} — token fields returned but NOT billed (billing is per image).
    • Z-Image: {width, height, image_count, input_tokens, output_tokens, total_tokens} + output_tokens_details.reasoning_tokens (only when prompt_extend=true). All tokens 0 when prompt_extend=false.

11. Image input (edit) constraints:

    • Qwen edit: 1–3 images, formats JPG/JPEG/PNG/BMP/TIFF/WEBP/GIF (GIF first frame only), recommended 384–3072 px/side, ≤10 MB. Output always PNG.
    • wan2.6: enable_interleave=false (edit) → 1–4 required; enable_interleave=true → 0–1. Formats JPEG/JPG/PNG(no alpha)/BMP/WebP, 240–8000 px/side, ≤10 MB.
    • wan2.7: 0–9 images. Formats JPEG/JPG/PNG(no alpha)/BMP/WEBP, 240–8000 px/side, aspect 1:8..8:1, ≤20 MB.
    • All accept public HTTP/HTTPS URL OR Base64 data URI data:{MIME_type};base64,{base64_data}. For multi-image, order = array sequence; output aspect ratio follows the LAST input image.

12. Regions / endpoints have SEPARATE API keys and request endpoints (NOT cross-region):

    • Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com (per-workspace host; replace {WorkspaceId}).
    • Beijing: https://dashscope.aliyuncs.com.
    • wan2.6 additionally: US (Virginia) https://dashscope-us.aliyuncs.com; global deployment scope (Frankfurt) is async-only.

13. Prompt text limits: qwen-image-2.0 series ≤1300 tokens, other Qwen text2image ≤800 tokens (sync) / ≤800 characters (async); Qwen edit: 2.0 series ≤1300 tokens, others ≤800 tokens; wan2.6 ≤2000 characters; wan2.7 ≤5000 characters; z-image-turbo ≤800 characters. negative_prompt ≤500 characters everywhere it exists. Excess is auto-truncated.

14. Billing: per successfully-generated image; failed attempts are free. For Wan2.6/Wan2.7 the usage token fields are not billed. For Z-Image, cost depends on success count AND whether prompt_extend was enabled (enabling it increases cost).

---

SHARED ELEMENTS (Qwen text2image / Qwen edit / Z-Image / Wan sync)

Sync endpoint (all families):

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation   (Singapore)
POST https://dashscope-us.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation                        (US-Virginia; wan2.6 only)
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation                           (Beijing)

Headers (all): Content-Type: application/json (required), Authorization: Bearer $DASHSCOPE_API_KEY (required). (wan2.6 streaming-interleave additionally: X-DashScope-SSE: enable.)

Shared request envelope:

{
  "model": "<slug>",
  "input": { "messages": [ { "role": "user", "content": [ {"text": "..."}, {"image": "<url|base64>"} ] } ] },
  "parameters": { ...per-family... }
}

• input.messages is single-turn only (exactly ONE element). role must be user.
• content is an array mixing exactly one {"text":...} and zero-or-more {"image":...} objects. Per-family image-count bounds differ (see §11 above); for edit / wan2.6-edit at least one image is REQUIRED.
• Generated image URLs expire after 24 hours; output is PNG.

HTTP-level failure (all families, sync): top-level { "request_id", "code", "message" }.

---

1) Qwen-Image — Text-to-image

Page: qwen-image-api. Slugs: qwen-image-2.0, qwen-image-2.0-pro (+ snapshots) and qwen-image-max, qwen-image-plus, qwen-image. Sync endpoint = shared multimodal-generation path.

1a) Request body parameters (SYNC text2image)

name	type	required	default	allowed / range	description
model	string	yes	—	qwen-image-2.0, qwen-image-2.0-pro, qwen-image-max, qwen-image-plus, qwen-image (+ dated snapshots)	Model name.
input	object	yes	—	—	Wrapper for messages.
input.messages	array	yes	—	exactly 1 element	Single-turn only.
input.messages[].role	string	yes	—	user	Sender role.
input.messages[].content	array	yes	—	exactly one text object (no image for text2image)	Content list.
input.messages[].content[].text	string	yes	—	Chinese/English; qwen-image-2.0 series ≤1300 tokens, other models ≤800 tokens (excess truncated)	Positive prompt. Exactly one text field; omitting or duplicating → error.
parameters	object	no	—	—	Image params.
parameters.negative_prompt	string	no	— (none)	Chinese/English, ≤500 chars (truncated)	What to exclude.
parameters.size	string	no	2048*2048 (2.0 series) / 1664*928 (max & plus series)	width*height. 2.0 series: total px 512×512..2048×2048; recommended 2688*1536(16:9), 1536*2688(9:16), 2048*2048(1:1,default), 2368*1728(4:3), 1728*2368(3:4). max/plus series: 1664*928(16:9,default), 1472*1104(4:3), 1328*1328(1:1), 1104*1472(3:4), 928*1664(9:16)	Output resolution.
parameters.n	integer	no	1	qwen-image-2.0 series: 1–6; qwen-image-max & qwen-image-plus & qwen-image: fixed 1 (other values error)	Number of output images.
parameters.prompt_extend	bool	no	true	true / false	Smart prompt rewrite (positive prompt only; does not affect negative). false = tighter control. Actual rewritten prompt returned ONLY on async calls.
parameters.watermark	bool	no	false	true / false	Adds “Qwen-Image” watermark to bottom-right corner.
parameters.seed	integer	no	random	[0, 2147483647]	Random seed; same seed → similar (not guaranteed identical) output.

1b) Response (SYNC) shape

{
  "output": {
    "choices": [
      { "finish_reason": "stop",
        "message": { "role": "assistant",
                     "content": [ {"image": "https://...png?Expires=..."} ] } }
    ]
  },
  "usage": { "input_tokens": 0, "output_tokens": 0, "width": 2048, "image_count": 1, "height": 2048 },
  "request_id": "..."
}

Fields:

• output.choices[] — exactly one element. finish_reason = stop on natural stop.
• output.choices[].message.content[].image — PNG URL, valid 24h.
• output.task_metric {TOTAL, SUCCEEDED, FAILED} — returned for max/plus series; NOT returned for qwen-image-2.0 series.
• usage — {image_count, width, height}; SDK responses also return input_tokens, output_tokens (= 0). image_count = requested n (1–6) for 2.0 series, fixed 1 for max/plus.
• request_id, plus code/message only on failure.

1c) Async (text2image) — ONLY qwen-image-plus & qwen-image

Step 1 — create: POST .../api/v1/services/aigc/text2image/image-synthesis Headers: Content-Type: application/json, Authorization: Bearer ..., X-DashScope-Async: enable (required — missing → error “current user api does not support synchronous calls”). Async body uses a FLAT input shape (NOT messages):

{ "model":"qwen-image-plus",
  "input": { "prompt":"...", "negative_prompt":"..." },
  "parameters": { "size":"1664*928", "n":1, "prompt_extend":true, "watermark":false, "seed":0 } }

name	type	required	default	allowed / range	description
input.prompt	string	yes	—	Chinese/English ≤800 chars (truncated)	Positive prompt.
input.negative_prompt	string	no	—	≤500 chars	Negative prompt.
parameters.size	string	no	1664*928	same size rules as §1a	Resolution.
parameters.n	integer	no	1	fixed 1 (other values error)	Image count.
parameters.prompt_extend	bool	no	true	true/false	Rewrite.
parameters.watermark	bool	no	false	true/false	”Qwen-Image” watermark.
parameters.seed	integer	no	random	[0,2147483647]	Seed.

Create response: { "output": {"task_status":"PENDING","task_id":"..."}, "request_id":"..." }. Create failure: top-level { "code", "message", "request_id" }.

Step 2 — poll: GET .../api/v1/tasks/{task_id} with Authorization header. task_id valid 24h. Recommended poll interval ~10s. task_status enum: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, UNKNOWN. Success:

{ "request_id":"...",
  "output": { "task_id":"...","task_status":"SUCCEEDED",
    "submit_time":"YYYY-MM-DD HH:mm:ss.SSS","scheduled_time":"...","end_time":"...",
    "results":[ {"orig_prompt":"...","actual_prompt":"...","url":"https://...png?Expires=..."} ] },
  "usage": {"image_count":1} }

• orig_prompt = original input prompt; actual_prompt = optimized prompt, returned ONLY when prompt_extend enabled.
• url = generated image, expires 24h. Times are UTC+8. FAILED poll shape (note: code/message are directly inside output, no results array):

{ "request_id":"...",
  "output": { "task_id":"...","task_status":"FAILED",
    "submit_time":"...","scheduled_time":"...","end_time":"...",
    "code":"InvalidParameter","message":"..." } }

1d) Examples

Minimal (sync):

curl '.../services/aigc/multimodal-generation/generation' \
 -H 'Content-Type: application/json' -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
 -d '{"model":"qwen-image-2.0-pro","input":{"messages":[{"role":"user","content":[{"text":"an orange cat"}]}]}}'

Full (sync):

{ "model":"qwen-image-2.0-pro",
  "input":{"messages":[{"role":"user","content":[{"text":"Healing-style hand-drawn poster ..."}]}]},
  "parameters":{ "negative_prompt":"low resolution, blurry text","prompt_extend":true,"watermark":false,"size":"2048*2048","n":2,"seed":42 } }

---

2) Qwen-Image — Image editing

Page: qwen-image-edit-api. Sync only (NO async). Same multimodal-generation endpoint. Slugs: qwen-image-edit-max, qwen-image-edit-plus (+ snapshots), qwen-image-2.0, qwen-image-2.0-pro, qwen-image-edit. Content array carries 1–3 image objects + exactly one text.

2a) Request body parameters

name	type	required	default	allowed / range	description
model	string	yes	—	qwen-image-edit-max, qwen-image-edit-plus, qwen-image-2.0, qwen-image-2.0-pro, qwen-image-edit (+ dated snapshots)	Model name.
input.messages	array	yes	—	exactly 1 element	Single-turn.
input.messages[].role	string	yes	—	user	Role.
input.messages[].content	array	yes	—	1–3 image objects + exactly 1 text object	Mixed content.
input.messages[].content[].image	string	yes	—	URL (HTTP/HTTPS) or Base64 data URI data:image/jpeg;base64,.... Formats JPG/JPEG/PNG/BMP/TIFF/WEBP/GIF (GIF first frame only); recommended 384–3072 px/side; ≤10 MB; 1–3 images (order matters, last image sets output ratio)	Input image(s). Output always PNG.
input.messages[].content[].text	string	yes	—	Chinese/English; qwen-image-2.0 series ≤1300 tokens, others ≤800 tokens	Editing instruction / positive prompt. Exactly one.
parameters	object	no	—	—	Edit params.
parameters.n	integer	no	1	qwen-image-2.0 / qwen-image-edit-max / qwen-image-edit-plus series: 1–6; qwen-image-edit: fixed 1	Output image count.
parameters.negative_prompt	string	no	—	≤500 chars	Exclusions.
parameters.size	string	no	total px near 1024*1024, aspect ratio of last input image	width*height. qwen-image-2.0 series: total px 512×512..2048×2048. qwen-image-edit-max / edit-plus: width & height each [512,2048]. System snaps each dimension to nearest multiple of 16 (e.g. 1033*1032 → 1040*1024). Recommended: 1:1 1024*1024/1536*1536; 2:3 768*1152/1024*1536; 3:2 1152*768/1536*1024; 3:4 960*1280/1080*1440; 4:3 1280*960/1440*1080; 9:16 720*1280/1080*1920; 16:9 1280*720/1920*1080; 21:9 1344*576/2048*872. NOT supported by qwen-image-edit (resolution not customizable).	Output resolution.
parameters.prompt_extend	bool	no	true	true/false. NOT supported by qwen-image-edit	Smart rewrite of positive prompt.
parameters.watermark	bool	no	false	true/false	”Qwen-Image” watermark, bottom-right.
parameters.seed	integer	no	random	[0,2147483647]	Seed.

2b) Response

{ "output": { "choices": [ { "finish_reason":"stop",
      "message": { "role":"assistant",
        "content": [ {"image":"https://...png?Expires=..."}, {"image":"https://...png?Expires=..."} ] } } ] },
  "usage": { "width":1536, "image_count":2, "height":1024 },
  "request_id":"..." }

• For multi-image output, content[] has one {image} per generated image.
• usage = {image_count, width, height} (success only).
• HTTP-level failure: top-level {request_id, code, message}.

2c) Base64 helper

Encode as data:{MIME_type};base64,{base64_data} (MIME must start with image/). Output PNG regardless of input format.

2d) Examples

Minimal:

{ "model":"qwen-image-edit-max",
  "input":{"messages":[{"role":"user","content":[
     {"image":"https://.../input.png"}, {"text":"remove the background"}]}]} }

Full (multi-image fusion):

{ "model":"qwen-image-2.0-pro",
  "input":{"messages":[{"role":"user","content":[
     {"image":"https://.../input1.png"},{"image":"https://.../input2.png"},{"image":"https://.../input3.png"},
     {"text":"The girl from Image 1 is wearing the black dress from Image 2 and sitting in the pose from Image 3."}]}]},
  "parameters":{"n":2,"negative_prompt":" ","prompt_extend":true,"watermark":false,"size":"1024*1536"} }

---

3) Wan2.6 — Image generation & editing (wan2.6-image)

Page: wan-image-generation-api-reference. Sync (multimodal-generation path) + async; interleaved text-image output is streaming-only on the sync path. Regions: Singapore, US (Virginia) dashscope-us.aliyuncs.com, Beijing; Frankfurt/global = async only. Optional header X-DashScope-SSE: enable (set when enable_interleave=true on the sync path; omit otherwise).

3a) Request body parameters

name	type	required	default	allowed / range	description
model	string	yes	—	wan2.6-image	Model name.
input.messages	array	yes	—	exactly 1 element	Single-turn.
input.messages[].role	string	yes	—	user	Role.
input.messages[].content	array	yes	—	exactly one text object + image objects per enable_interleave rule	Mixed content.
input.messages[].content[].text	string	yes	—	Chinese/English ≤2000 chars (truncated)	Positive prompt. Exactly one text object.
input.messages[].content[].image	string	no*	—	URL or Base64 data URI. Formats JPEG/JPG/PNG (no alpha)/BMP/WebP; 240–8000 px/side; ≤10 MB. Count: enable_interleave=true → 0–1; enable_interleave=false (edit) → MUST be 1–4	Input image(s). *Required in edit mode.
parameters	object	no	—	—	Generation params.
parameters.negative_prompt	string	no	—	Chinese/English ≤500 chars	Exclusions.
parameters.size	string	no	1K (edit mode) / ratio-of-input (interleave)	edit mode (enable_interleave=false): 1K(default, ~1280×1280) / 2K(~2048×2048) keeping last-input aspect ratio, OR width*height total px [768×768, 2048×2048], aspect [1:4,4:1]. interleave mode (true): ratio-of-input default (≤1280×1280 keep as-is; >1280×1280 scaled to ~1280×1280; no image → 1280×1280) OR width*height total px [768×768, 1280×1280], aspect [1:4,4:1]. Output snapped to nearest multiple of 16. Recommended: 1:1 1280*1280, 2:3 800*1200, 3:2 1200*800, 3:4 960*1280, 4:3 1280*960, 9:16 720*1280, 16:9 1280*720, 21:9 1344*576	Output resolution (two methods).
parameters.enable_interleave	bool	no	false	false = image-editing mode (1–4 input images required, 1–4 outputs); true = interleaved text+image output mode (0–1 input image, mixed text/image output)	Generation mode.
parameters.n	integer	no	4 (edit mode) / 1 (interleave)	edit mode (enable_interleave=false): 1–4, default 4; interleave mode (true): must be 1 (else error)	Number of images (edit mode). Affects cost.
parameters.max_images	integer	no	5	1–5; effective ONLY when enable_interleave=true	Upper bound of images in interleaved response (model may emit fewer). Affects cost.
parameters.prompt_extend	bool	no	true	true/false; effective ONLY when enable_interleave=false	Smart rewrite (positive prompt only).
parameters.stream	bool	no	false	true/false; REQUIRED true when enable_interleave=true on the sync path	Streaming output. (Async calls do not require it.)
parameters.watermark	bool	no	false	true/false	Adds “AI Generated” watermark, bottom-right.
parameters.seed	integer	no	random	[0,2147483647]	Seed.

3b) Response (SYNC)

Non-stream success:

{ "output": {
    "choices": [ { "finish_reason":"stop",
        "message": { "content": [ {"image":"https://...png?Expires=...","type":"image"} ], "role":"assistant" } } ],
    "finished": true },
  "usage": { "image_count":1, "input_tokens":0, "output_tokens":0, "size":"1376*768", "total_tokens":0 },
  "request_id":"..." }

• Each content[] item has a type field ("text" | "image"); output.finished is a boolean.
• usage token fields are returned but NOT billed (fixed 0 in edit mode; count text tokens in interleave mode). usage.size = output resolution string. Billing per image.

Streaming (interleave, X-DashScope-SSE: enable + stream: true): newline-delimited JSON chunks; each chunk’s content[] item is {type:"text",text} or {type:"image",image}, with finish_reason "null" until the final chunk where it is "stop". Example chunk:

{"output":{"choices":[{"message":{"content":[{"type":"text","text":"meat"}],"role":"assistant"},"finish_reason":"null"}],"finished":true},"usage":{"total_tokens":571,"image_count":3,"output_tokens":543,"size":"1280*1280","input_tokens":28},"request_id":"..."}

HTTP-level failure (sync): top-level {request_id, code, message}.

3c) Async

Step 1 — create: POST .../api/v1/services/aigc/image-generation/generation (NOTE: different path from Qwen async, which uses .../aigc/text2image/image-synthesis.) Headers + X-DashScope-Async: enable (required). Same body as sync (no stream needed for async interleave). Create response: { "output": {"task_status":"PENDING","task_id":"..."}, "request_id":"..." }.

Step 2 — poll: GET .../api/v1/tasks/{task_id}. Status enum same as Qwen async. Success (note: choices and finished are inside output alongside task_id/task_status/times):

{ "request_id":"...",
  "output": { "task_id":"...","task_status":"SUCCEEDED",
    "submit_time":"...","scheduled_time":"...","end_time":"...","finished":true,
    "choices": [ { "finish_reason":"stop",
        "message": { "role":"assistant", "content": [ {"image":"https://...png?Expires=...","type":"image"} ] } } ] },
  "usage": { "size":"1376*768","total_tokens":0,"image_count":2,"output_tokens":0,"input_tokens":0 } }

Poll failure: top-level {request_id, code, message}.

3d) Examples

Minimal (edit):

{ "model":"wan2.6-image","input":{"messages":[{"role":"user","content":[
   {"text":"make it a watercolor painting"},{"image":"https://.../in.png"}]}]} }

Full (edit):

{ "model":"wan2.6-image",
  "input":{"messages":[{"role":"user","content":[
     {"text":"Generate a tomato and egg stir-fry based on the style of image 1 and the background of image 2"},
     {"image":"https://.../umbrella1.png"},{"image":"https://.../bg.webp"}]}]},
  "parameters":{"prompt_extend":true,"watermark":false,"n":1,"enable_interleave":false,"size":"1K","negative_prompt":" ","seed":7} }

Interleave (streaming, sync): set header X-DashScope-SSE: enable and parameters:{ "enable_interleave":true, "stream":true, "max_images":3, "size":"1280*1280" }.

---

4) Wan2.7 — Image generation & editing (wan2.7-image, wan2.7-image-pro)

Page: wan-image-generation-and-editing-api-reference. Sync (multimodal-generation path) + async. NO negative_prompt, NO prompt_extend — uses thinking_mode instead. Supports text-to-image, image editing, interactive (bbox) editing, image-set generation. Regions: Singapore, Beijing (separate keys/endpoints).

4a) Request body parameters

name	type	required	default	allowed / range	description
model	string	yes	—	wan2.7-image-pro, wan2.7-image	Model name.
input.messages	array	yes	—	exactly 1 element	Single-turn.
input.messages[].role	string	yes	—	user	Role.
input.messages[].content	array	yes	—	text and/or image objects	Mixed content.
input.messages[].content[].text	string	no	—	Chinese/English ≤5000 chars (truncated)	Text prompt.
input.messages[].content[].image	string	no	—	URL or Base64 data URI. Formats JPEG/JPG/PNG (no alpha)/BMP/WEBP; 240–8000 px/side; aspect 1:8..8:1; ≤20 MB. Count: 0–9 images (order matters, last sets output ratio)	Input image(s).
parameters	object	no	—	—	Model params.
parameters.bbox_list	List[List[List[int]]]	no	—	length MUST equal number of input images; empty [] for an image with no box; each box [x1,y1,x2,y2] absolute px, top-left origin (0,0); max 2 boxes per image	Bounding boxes for interactive editing.
parameters.enable_sequential	boolean	no	false	false = default output mode; true = image-set output mode	Image-set toggle.
parameters.size	string	no	2K	wan2.7-image-pro — Method 1: 1K(1024×1024) / 2K(2048×2048, default) / 4K(4096×4096); 4K only for text-to-image (no image input, not image-set); other scenarios 1K & 2K only. Method 2 width*height: text-to-image total px [768×768, 4096×4096] aspect [1:8,8:1]; other scenarios [768×768, 2048×2048] aspect [1:8,8:1]. wan2.7-image — 1K & 2K (default 2K), NO 4K; Method 2 width*height all scenarios [768×768, 2048×2048] aspect [1:8,8:1]. Output px may differ slightly from requested.	Output resolution (two mutually exclusive methods).
parameters.n	int	no	1 (image-set: 12)	image-set disabled: 1–4 (default 1) = number of images; image-set enabled: 1–12 (default 12) = max images (model decides actual ≤ n)	Image count. Affects cost.
parameters.thinking_mode	boolean	no	true	true/false; effective ONLY when image-set disabled AND no image input	Enhances inference quality (slower).
parameters.color_palette	array	no	—	array of {hex, ratio} objects; 3–10 colors (8 recommended); only when enable_sequential=false	Custom color theme.
parameters.color_palette[].hex	string	yes (in object)	—	HEX e.g. #C2D1E6	Color value.
parameters.color_palette[].ratio	string	yes (in object)	—	percentage to 2 decimals, e.g. "25.00%"; sum of all ratios = 100.00%	Color percentage.
parameters.watermark	bool	no	false	true/false	Adds “AI Generated” watermark, bottom-right.
parameters.seed	integer	no	random	[0,2147483647]	Seed.

4b) Response (SYNC)

{ "output": {
    "choices": [ { "finish_reason":"stop",
        "message": { "content": [ {"image":"https://...png?Expires=...","type":"image"} ], "role":"assistant" } } ],
    "finished": true },
  "usage": { "image_count":1, "input_tokens":10867, "output_tokens":2, "size":"1488*704", "total_tokens":10869 },
  "request_id":"..." }

• Each content[] item has a type field ("image"); output.finished boolean present.
• usage = {image_count, size, input_tokens, output_tokens, total_tokens}; all token fields NOT billed (per-image billing). HTTP-level failure: top-level {request_id, code, message}.

4c) Async

Step 1 — create: POST .../api/v1/services/aigc/image-generation/generation + header X-DashScope-Async: enable (required). Same body. Create response: { "output": {"task_status":"PENDING","task_id":"..."}, "request_id":"..." }. Step 2 — poll: GET .../api/v1/tasks/{task_id}. Status enum same as Qwen async. Success (choices + finished inside output):

{ "request_id":"...",
  "output": { "task_id":"...","task_status":"SUCCEEDED",
    "submit_time":"...","scheduled_time":"...","end_time":"...","finished":true,
    "choices": [ { "finish_reason":"stop",
        "message": { "role":"assistant", "content": [ {"image":"https://...png?Expires=...","type":"image"} ] } } ] },
  "usage": { "size":"2976*1408","total_tokens":11017,"image_count":1,"output_tokens":2,"input_tokens":11015 } }

Poll failure: top-level {request_id, code, message}.

4d) Examples

Minimal (text-to-image):

{ "model":"wan2.7-image","input":{"messages":[{"role":"user","content":[{"text":"a flower shop"}]}]} }

Full (interactive box edit):

{ "model":"wan2.7-image-pro",
  "input":{"messages":[{"role":"user","content":[
     {"image":"https://.../clock.webp"},{"image":"https://.../room.webp"},
     {"text":"Place the alarm clock from image 1 into the bounding box of image 2; blend lighting naturally."}]}]},
  "parameters":{"bbox_list":[[],[[989,515,1138,681]]],"size":"2K","n":1,"watermark":false,"seed":99} }

Image-set: parameters:{ "enable_sequential":true, "n":4, "size":"2K" }. Color palette: parameters:{ "color_palette":[{"hex":"#C2D1E6","ratio":"50.00%"},{"hex":"#636574","ratio":"30.00%"},{"hex":"#CACAD2","ratio":"20.00%"}] }.

---

5) Z-Image (z-image-turbo)

Page: z-image-api-reference. Sync only (no async). Same multimodal-generation endpoint. Simplest param set: size + prompt_extend + seed. NO negative_prompt, NO n (fixed 1), NO watermark param. Regions: Singapore, Beijing.

5a) Request body parameters

name	type	required	default	allowed / range	description
model	string	yes	—	z-image-turbo	Model name.
input.messages	array	yes	—	exactly 1 element	Single-turn only.
input.messages[].role	string	yes	—	user	Role.
input.messages[].content	array	yes	—	exactly one text object	Content.
input.messages[].content[].text	string	yes	—	Chinese/English ≤800 chars (truncated); zero or multiple text objects → error	Positive prompt.
parameters	object	no	—	—	Generation params.
parameters.size	string	no	1024*1536	width*height. Range 512×512..2048×2048; recommended 1024×1024..1536×1536. Recommended sets — at 1024² total: 1:1 1024*1024, 2:3 832*1248, 3:2 1248*832, 3:4 864*1152, 4:3 1152*864, 7:9 896*1152, 9:7 1152*896, 9:16 720*1280, 9:21 576*1344, 16:9 1280*720, 21:9 1344*576. At 1280² total: 1:1 1280*1280, 2:3 1024*1536, 3:2 1536*1024, 3:4 1104*1472, 4:3 1472*1104, 7:9 1120*1440, 9:7 1440*1120, 9:16 864*1536, 9:21 720*1680, 16:9 1536*864, 21:9 1680*720. At 1536² total: 1:1 1536*1536, 2:3 1248*1872, 3:2 1872*1248, 3:4 1296*1728, 4:3 1728*1296, 7:9 1344*1728, 9:7 1728*1344, 9:16 1152*2048, 9:21 864*2016, 16:9 2048*1152, 21:9 2016*864.	Output resolution.
parameters.prompt_extend	bool	no	false	false = returns image + original prompt; true = LLM rewrite, returns image + optimized prompt + reasoning (INCREASES COST and latency)	Smart prompt rewriting.
parameters.seed	integer	no	random	[0,2147483647]	Seed.

5b) Response (SYNC)

{ "output": {
    "choices": [ { "finish_reason":"stop",
        "message": {
          "content": [ {"image":"https://...png?Expires=..."}, {"text":"...prompt..."} ],
          "reasoning_content": "",
          "role":"assistant" } } ] },
  "usage": { "height":1024, "image_count":1, "input_tokens":0, "output_tokens":0, "total_tokens":0, "width":1024 },
  "request_id":"..." }

• content[] includes BOTH a {image} item and a {text} item. The text = input prompt when prompt_extend=false, the rewritten prompt when true.
• message.reasoning_content (string) — model reasoning; returned ONLY when prompt_extend=true (empty string otherwise).
• usage = {width, height, image_count(=1), input_tokens, output_tokens, total_tokens}; when prompt_extend=true, usage.output_tokens_details.reasoning_tokens is also returned. All token values are 0 when prompt_extend=false.
• Billing depends on success count AND prompt_extend status.
• Content moderation: both input prompt and output image are moderated; non-compliant → IPInfringementSuspect or DataInspectionFailed error. HTTP-level failure: top-level {request_id, code, message}.

5c) Examples

Minimal:

{ "model":"z-image-turbo","input":{"messages":[{"role":"user","content":[{"text":"a happy orange cat"}]}]} }

Full:

{ "model":"z-image-turbo",
  "input":{"messages":[{"role":"user","content":[{"text":"Photo of a stylish young woman ... High detail, sharp focus."}]}]},
  "parameters":{"prompt_extend":false,"size":"1024*1024","seed":12345} }

---

Cross-family parameter presence matrix

param	qwen-image text2img	qwen-image edit	wan2.6-image	wan2.7-image(-pro)	z-image-turbo
text (prompt)	yes (≤1300/800 tok)	yes (≤1300/800 tok)	yes (≤2000 ch)	yes (≤5000 ch)	yes (≤800 ch)
image input	no	yes 1–3 (required)	yes 0–1 (interleave) / 1–4 (edit)	yes 0–9	no
negative_prompt	yes (≤500 ch)	yes (≤500 ch)	yes (≤500 ch)	NO	NO
size	yes width*height	yes width*height (not on qwen-image-edit)	1K/2K or w*h	1K/2K/4K or w*h	yes width*height (def 1024*1536)
n	1–6 / fixed 1	1–6 / fixed 1 (qwen-image-edit)	1–4 (def 4) / 1	1–4 (def 1) / 1–12 (def 12)	no param (fixed 1)
prompt_extend	yes (def true)	yes (def true; not on qwen-image-edit)	yes (def true, edit only)	NO	yes (def false)
thinking_mode	NO	NO	NO	yes (def true)	NO
watermark	”Qwen-Image"	"Qwen-Image"	"AI Generated"	"AI Generated”	NO
seed	yes [0,2147483647]	yes	yes	yes	yes
bbox_list / enable_sequential / color_palette	NO	NO	NO	yes	NO
enable_interleave / max_images / stream	NO	NO	yes	NO	NO
async support	only plus / qwen-image	NO	yes	yes	NO
response content type field	no	no	yes (text|image)	yes (image)	no (but adds {text} + reasoning_content)
usage token fields	input/output=0	image_count/width/height only	input/output/total (not billed)	input/output/total (not billed)	input/output/total + reasoning_tokens (when extend)

Endpoint reference (paths)

purpose	path
Sync (all families)	POST /api/v1/services/aigc/multimodal-generation/generation
Qwen async create (plus / qwen-image only)	POST /api/v1/services/aigc/text2image/image-synthesis (header X-DashScope-Async: enable)
Wan2.6 / Wan2.7 async create	POST /api/v1/services/aigc/image-generation/generation (header X-DashScope-Async: enable)
Async poll (Qwen / Wan)	GET /api/v1/tasks/{task_id}

Hosts: Singapore {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com · Beijing dashscope.aliyuncs.com · US-Virginia dashscope-us.aliyuncs.com (wan2.6) · Frankfurt/global (wan2.6, async only).