The Qwen-Image-Edit model supports multi-image input and multi-image output. It can precisely modify text in images, add, remove, or move objects, change subject poses, transfer image styles, and enhance image details.
QuickStart
Before making calls, you need to obtain and configure an API Key, and then configure the API Key as an environment variable.
To make calls through the SDK, please install the DashScope SDK. Currently, the SDK supports Python and Java.
Please replace
DASHSCOPE_API_HOSTin the sample code with the obtained API Host.
Python
import os
import base64
import mimetypes
import dashscope
# 以下为新加坡地域的配置,调用时请将{WorkspaceId}替换为真实的业务空间ID,各地域的region取值不同。
# 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx"
# 各地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key
client = dashscope.Client(
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
def encode_file(file_path):
mime_type, _ = mimetypes.guess_type(file_path)
if not mime_type or not mime_type.startswith("image/"):
raise ValueError("Unsupported or unrecognized image format")
with open(file_path, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
return f"data:{mime_type};base64,{encoded_string}"
# [方法一] 使用公网图像URL
image_url = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
# [方法二] 使用Base64编码图像
# image_url = encode_file("./your_image.png")
response = client.multimodal.chat.create(
model="qwen-image-3.0-pro",
messages=[{
"role": "user",
"content": [
{"image": image_url},
{"text": "帮我生成一张充满高级感的都市风格女性写真,画面中人物完美保留输入图片中这位年轻女性的面部特征与一头柔顺的黑色长发。人物换上一套彰显高雅气质的都市职场穿搭,场景设定在一家装修现代简约的高端咖啡店内。"}
]
}],
parameters={"prompt_extend": True},
)
# 2.0 SDK:生成结果从 message.content_parts 读取,图像 part 形如 {"image": URL, "type": "image"}
message = response.choices[0].message
for part in (message.content_parts or []):
if "image" in part:
print(f"Generated image URL: {part['image']}")
Java
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.utils.Constants;
public class ImageEditExample {
public static void main(String[] args) {
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
// [方法一] 使用公网图像URL
String imageUrl = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png";
// [方法二] 使用Base64编码图像
// String imageUrl = encodeFile("/path/to/your/image.png");
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("image", imageUrl),
Collections.singletonMap("text", "帮我生成一张充满高级感的都市风格女性写真,画面中人物完美保留输入图片中这位年轻女性的面部特征与一头柔顺的黑色长发。人物换上一套彰显高雅气质的都市职场穿搭,场景设定在一家装修现代简约的高端咖啡店内。")
))
.build();
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen-image-3.0-pro")
.messages(Arrays.asList(userMessage))
.parameter("prompt_extend", true)
.build();
try {
MultiModalConversationResult result = conv.call(param);
System.out.println(result);
} catch (Exception e) {
e.printStackTrace();
}
}
public static String encodeFile(String filePath) {
Path path = Paths.get(filePath);
if (!Files.exists(path)) {
throw new IllegalArgumentException("File does not exist: " + filePath);
}
String mimeType = null;
try {
mimeType = Files.probeContentType(path);
} catch (IOException e) {
throw new IllegalArgumentException("Cannot detect file type: " + filePath);
}
if (mimeType == null || !mimeType.startsWith("image/")) {
throw new IllegalArgumentException("Unsupported or unrecognized image format");
}
byte[] fileBytes = null;
try {
fileBytes = Files.readAllBytes(path);
} catch (IOException e) {
throw new IllegalArgumentException("Cannot read file content: " + filePath);
}
String encodedString = Base64.getEncoder().encodeToString(fileBytes);
return "data:" + mimeType + ";base64," + encodedString;
}
}
curl
The following is the URL for the Singapore region, and URLs vary by region. If you use a model in the China (Beijing) region, replace the URL with: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
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-3.0-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
},
{
"text": "帮我生成一张充满高级感的都市风格女性写真,画面中人物完美保留输入图片中这位年轻女性的面部特征与一头柔顺的黑色长发。人物脱下原本的米色针织上衣,换上一套彰显高雅气质的都市职场穿搭,身穿一件质感垂顺的香槟色真丝衬衫,外搭一件剪裁利落的深灰色休闲西装外套,下身搭配同色系的高腰阔腿裤,整体造型既干练又富有女人味。场景设定在一家装修现代简约的高端咖啡店内,背景是通透的落地玻璃窗,窗外隐约可见繁华的城市街景,室内摆放着深色实木长桌和舒适的皮质座椅,桌面上放置着一台打开的银色笔记本电脑、一份文件和一杯热气腾腾的美式咖啡。人物呈现出慵懒而放松的办公姿态,身体微微后仰倚靠在椅背上,一只手臂自然搭在扶手上,另一只手轻轻握着咖啡杯置于桌边,头部微侧,眼神清澈从容且带有一丝慵懒地直视镜头,嘴角挂着一抹优雅自信的微笑。人物化着精致得体的正式场合妆容,底妆清透干净,眉眼线条清晰利落,唇部涂抹着显气色的豆沙色口红,展现出成熟知性的魅力。光线采用午后柔和的自然光,从侧面透过落地窗洒入,在人物的面部轮廓和衣物褶皱上留下细腻的光影过渡,背景呈现自然的景深虚化效果,色彩以大地色、灰色和暖白色为主调,营造出宁静、高级且充满故事感的都市办公氛围,构图采用经典的竖幅七分身人像视角,人物位于画面视觉中心略偏右,比例协调,画质清晰细腻。"
}
]
}
]
},
"parameters": {
"prompt_extend": true
}
}'
Response example
{
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"content": [
{
"image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
}
],
"role": "assistant"
}
}
]
},
"usage": {
"output_height": 1024,
"output_width": 1024,
"input_image_count": 1,
"input_image_type": "qima_input_1k",
"output_image_count": 1,
"output_image_type": "qima_output_1k"
},
"request_id": "571ae02f-5c9d-436c-83c2-f221e6df0xxx"
}
Download the image to your local machine via the URL
# 需要安装requests以下载图像: pip install requests
import requests
def download_image(image_url, save_path='output.png'):
try:
response = requests.get(image_url, stream=True, timeout=300) # 设置超时
response.raise_for_status() # 如果HTTP状态码不是200,则引发异常
with open(save_path, 'wb') as f:
for chunk in response.iter_content(chunk_size=8192):
f.write(chunk)
print(f"图像已成功下载到: {save_path}")
except requests.exceptions.RequestException as e:
print(f"图像下载失败: {e}")
image_url = "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
download_image(image_url, save_path='output.png')
import java.io.FileOutputStream;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
public class ImageDownloader {
public static void downloadImage(String imageUrl, String savePath) {
try {
URL url = new URL(imageUrl);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setConnectTimeout(5000);
connection.setReadTimeout(300000);
connection.setRequestMethod("GET");
InputStream inputStream = connection.getInputStream();
FileOutputStream outputStream = new FileOutputStream(savePath);
byte[] buffer = new byte[8192];
int bytesRead;
while ((bytesRead = inputStream.read(buffer)) != -1) {
outputStream.write(buffer, 0, bytesRead);
}
inputStream.close();
outputStream.close();
System.out.println("图像已成功下载到: " + savePath);
} catch (Exception e) {
System.err.println("图像下载失败: " + e.getMessage());
}
}
public static void main(String[] args) {
String imageUrl = "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx?Expires=xxx";
String savePath = "output.png";
downloadImage(imageUrl, savePath);
}
}
Model selection recommendations
qwen-image-3.0-pro(Ultimate performance): Qwen-Image 3.0 Ultimate Edition, with comprehensively upgraded image generation and editing capabilities and stronger text rendering, realistic texture, and semantic adherence.qwen-image-2.1-pro(Best balance of speed, quality, and cost): Supports passing in up to 10 reference images, automatically decides whether to output a normal image or an image with a transparent channel based on the prompt, and does not supportnegative_prompt.qwen-image-2.1-turbo(Ultimate cost-effectiveness): Delivers the best overall cost-effectiveness in the Qwen-Image series, supports passing in up to 10 reference images, automatically decides whether to output a normal image or an image with a transparent channel based on the prompt, and does not supportnegative_prompt.qwen-image-3.0: Qwen-Image 3.0 Standard Edition, balancing quality and speed.
For models supported in each region, see the model list in the Model Studio console.
Input description
Input images (messages)
messages is an array and must contain only one object. The object must contain the role and content properties. Specifically, role must be set to user, and content must contain both image and text (an editing instruction). The qwen-image-3.0 series supports 1 to 3 images, and the qwen-image-2.1 series supports 1 to 10 images.
Input images must meet the following requirements:
-
Image formats: JPG, JPEG, PNG, BMP, TIFF, WEBP, and GIF.
Output images are in PNG format. For animated GIF images, only the first frame is processed.
-
Image resolution: For best results, both the width and height of images are recommended to be between 384 and 3,072 pixels. A resolution that is too low may result in blurry generated output, while one that is too high increases processing time.
-
File size: A single image file must not exceed 10 MB.
"messages": [
{
"role": "user",
"content": [
{ "image": "图1的公网URL或Base64数据" },
{ "image": "图2的公网URL或Base64数据" },
{ "image": "图3的公网URL或Base64数据" },
{ "text": "您的编辑指令,例如:'图1中的女生穿着图2中的黑色裙子按图3的姿势坐下'" }
]
}
]
Image input order
When multiple images are input, the image order is defined by their order in the array. Therefore, the image numbers referenced in the prompt must correspond one-to-one with the order in the image array, for example: the first image in the array is "Image 1", the second is "Image 2", or use markers such as "[Image 1]" and "[Image 2]".
{
"content": [
{"text": "编辑指令,如:将图1中的闹钟放置到图2的餐桌的花瓶旁边位置"},
{"image": "https://example.com/image1.png"},
{"image": "https://example.com/image2.png"}
]
}
Input image | Output image | ||
|---|---|---|---|
Image 1 |
Image 2 |
Prompt: Move Image 1 onto Image 2 |
Prompt: Move Image 2 onto Image 1 |
Image Input Methods
Public URL- Provide a publicly accessible image address that supports the HTTP or HTTPS protocol.
- Example value:
https://xxxx/img.png.
Convert the image file into a Base64-encoded string and assemble it in the format: data:{mime_type};base64,{base64_data}.
{mime_type}: the media type of the image, which must match the file format.{base64_data}: the Base64-encoded string of the file.- Example value:
data:image/jpeg;base64,GDU7MtCZz...(truncated for demonstration only)
For the complete sample code, see Python SDK calls and Java SDK calls.
More Parameters
You can adjust the generation results with the following optional parameters:
- n: the number of output images (default 1, up to 6). n directly affects the fee.
- negative_prompt: describes content you do not want to appear (such as "blurry" or "extra fingers") to help optimize generation quality. The qwen-image-2.1 series does not support this parameter; describe it in the positive prompt instead.
- size: the output resolution, in the format
width*height. The qwen-image-3.0 series and qwen-image-2.1 series support 512*512 to 2048*2048 (aspect ratio from 1:8 to 8:1); if not specified, the model automatically recommends one. - prompt_extend: intelligent prompt rewriting (enabled by default). It is recommended for concise prompts; disable it for detailed prompts or latency-sensitive scenarios.
- seed: the random seed; using the same value keeps generation results relatively stable.
- watermark: whether to add a watermark (disabled by default).
For the complete parameter list, see Qwen Image Edit API.
Effect Overview
Multi-image Fusion
Input image 1 | Input image 2 | Input image 3 | Output image |
|---|---|---|---|
|
|
|
The girl in image 1 wears the necklace from image 2 and carries the bag from image 3 on her left shoulder |
Subject Consistency Preservation
Input image | Output image 1 | Output image 2 | Output image 3 |
|---|---|---|---|
|
Change to an ID photo with a blue background; the person wears a white shirt, a black suit, and a striped tie |
The person wears a white shirt, a gray suit, and a striped tie, touching the tie with one hand, against a light-colored background |
The person wears a black hoodie featuring the words "Qwen Image" in a bold brush font, leaning against a railing with sunlight shining on her hair, with a bridge and the sea behind her |
|
Place this air conditioner in the living room, next to the sofa |
Add mist coming out of the air conditioner vent, extending all the way to the sofa, and add green leaves. |
Add white handwritten text "Natural Fresh Air, Breathe Freely" at the top |
Sketch Creation
Input image | Output image | |
|---|---|---|
|
Generate an image that matches the refined shape outlined in image 1 and follows this description: a young woman smiling on a sunny day, wearing a pair of round brown sunglasses with leopard-print frames. Her hair is neatly pulled up, she wears pearl earrings, a dark blue scarf with a purple star pattern around her neck, and a black leather jacket. |
Generate an image that matches the refined shape outlined in image 1 and follows this description: an elderly man smiling at the camera, his face covered in wrinkles, his hair messy in the wind, wearing a pair of round reading glasses. Around his neck is a worn red scarf with a star pattern. He is wearing a padded cotton coat. |
Cultural and creative design
Input image | Output image | ||
|---|---|---|---|
|
Let this bear sit under the moon (represented by a light gray crescent moon outline on a white background), holding a guitar, with small stars and poem bubbles such as “Be Kind” floating around. |
Print this pattern on a T-shirt and a handheld paper bag. A female model is displaying these items. The girl also wears a peaked cap with the words "Be kind" on it. |
A hyper-realistic 1/7 scale character model, designed as a finished commercial product, placed on an iMac desk with a white keyboard. The model stands on a clean, round, transparent acrylic base with no labels or text. Professional studio lighting highlights the sculpted details. On the iMac screen in the background, the ZBrush modeling process of the same model is shown. Next to the model, place a packaging box with a transparent window on the front, showing only the transparent plastic shell inside, slightly taller than the model and reasonably sized to hold it. |
This bear is wearing a spacesuit, pointing into the distance with its finger |
This bear is wearing an ornate dance dress, with arms outstretched, performing an elegant dance move |
This bear is wearing sportswear, holding a basketball in its hand, with one leg bent | |
Generate images from a depth map
Input image | Output image | |
|---|---|---|
|
Generate an image that matches the depth map outlined in Figure 1 and follows this description: a blue bicycle parked in an alley by the street, with a few weeds growing out of stone crevices in the background |
Generate an image that matches the depth map outlined in Figure 1 and follows this description: a red, worn-out bicycle parked on a muddy path, with a dense primeval forest in the background |
Generate images from keypoints
Input image | Output image | |
|---|---|---|
|
Generate an image that matches the human pose outlined in Figure 1 and follows this description: a beautiful Chinese woman wearing Hanfu, holding an oil-paper umbrella in the rain, with a Suzhou garden in the background. |
Generate an image that matches the human pose outlined in Figure 1 and follows this description: a young man standing on a subway platform, wearing a baseball cap on his head, dressed in a T-shirt and jeans. Behind him, a train speeds past. |
Text editing
Input image | Output image | Input image | Output image |
|---|---|---|---|
|
Replace 'HEALTH INSURANCE' on the Scrabble tile with 'Tomorrow will be better' |
|
Change the phrase “Take a Breather” on the note to “Relax and Recharge” |
Input image | Output image | ||
|---|---|---|---|
|
Change “Qwen-Image” to a black ink-drip font |
Change “Qwen-Image” to a black handwritten font |
Change “Qwen-Image” to a black pixel font |
Change “Qwen-Image” to red |
Change “Qwen-Image” to a blue-purple gradient |
Change “Qwen-Image” to candy colors | |
Change the “Qwen-Image” material to metal |
Change the “Qwen-Image” material to clouds |
Change the “Qwen-Image” material to glass | |
Add, remove, and modify
Capabilities | Input image | Output image |
|---|---|---|
Add elements |
|
Add a small wooden sign in front of the penguin that reads “Welcome to Penguin Beach”. |
Delete elements |
|
Remove hair from the plate |
Viewpoint conversion
Input image | Output image | Input image | Output image |
|---|---|---|---|
|
Obtain a front view |
|
Facing the left side |
|
Obtain a rear view |
|
Facing the right side |
Old photo processing
Capabilities | Input image | Output image |
|---|---|---|
Old photo restoration and colorization |
|
Restore old photos, remove scratches, reduce noise, enhance details, high resolution, realistic visuals, natural skin tones, clear facial features, and no distortion. |
|
Intelligently colorize images based on their content, making them more vivid |
API reference
For the API input and output parameters, see Qwen-Image-Edit.
Error codes
If a model call fails and returns an error message, see Error codes for troubleshooting.
FAQ
Q: Which languages does the Qwen image editing model support?
A: Simplified Chinese and English are currently officially supported. You can try other languages on your own, but the results may be uncertain.
Q: How do I view model usage?
A: One hour after the model call is complete, go to the Monitoring (Singapore) or Monitoring (Beijing) page to view metrics such as the number of model calls and the success rate. For more information, see Bill query and cost management.
Q: How do I obtain the access domain whitelist for image storage?
A: Images generated by the model are stored in Alibaba Cloud OSS, and the API returns a temporary public URL. If you need to configure a firewall whitelist for this download address, note that the underlying storage dynamically changes based on business conditions. To prevent expired information from affecting access, this documentation does not provide a fixed OSS domain whitelist. If you have security control requirements, contact your account manager to obtain the latest list of OSS domains.
For more questions, see Image generation FAQ.





























































