The Qwen Image Generation and Editing model supports both text-to-image (T2I) and image-to-image/image editing (I2I). It can generate images directly from text prompts or edit images based on reference images combined with editing instructions. Supports both the OpenAI-compatible and DashScope protocols.
Model overview
Model | Description | Output image specifications |
|---|---|---|
qwen-image-3.0-pro | Qwen Image Generation and Editing 3.0 model that supports both text-to-image (T2I) and image-to-image/image editing (I2I). | Image resolution:
Image format: PNG |
qwen-image-3.0 | Qwen Image Generation and Editing 3.0 standard model that supports both text-to-image (T2I) and image-to-image/image editing (I2I). Balances quality and speed. | |
qwen-image-2.1-pro | Qwen Image Generation and Editing 2.1 Pro model. Image-to-image/image editing (I2I) supports up to 10 reference images. It can also automatically decide whether to output a standard image or an image with a transparent (alpha) channel based on the prompt description. | |
qwen-image-2.1-turbo | Qwen Image Generation and Editing 2.1 Turbo model. The most balanced and cost-effective model in the Qwen-Image series. Image-to-image/image editing (I2I) supports up to 10 reference images. It can also automatically decide whether to output a standard image or an image with a transparent (alpha) channel based on the prompt description. |
Availability
The model, endpoint URL, and API key must belong to the same region. Cross-region calls fail.
- Select a model: Verify that the model is available in your target region.
- Select a URL: Choose the endpoint URL that matches your model's region. Both HTTP and DashScope SDK URLs are supported.
- Configure an API key: Get an API key for the region, and then configure the API key as an environment variable.
- Install the SDK: To make API calls with the SDK, install the DashScope SDK.
NoteThe sample code in this topic applies to the Singapore region.
ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
- China (Beijing): from
https://dashscope.aliyuncs.comtohttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
https://dashscope-intl.aliyuncs.comtohttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.
Access methods
Qwen Image Generation and Editing offers three access methods with identical model capabilities. Choose the one that fits your application:
Access method | When to use |
|---|---|
Applications already built on the OpenAI Images protocol or the OpenAI SDK. Switch | |
Recommended. Full feature coverage, including both public URL and Base64 image input. | |
Batch generation, or when you do not want to hold a connection open. Submit a task and poll for results with |
OpenAI-compatible
If your application is already built on the OpenAI Images protocol or the OpenAI SDK, you can call Qwen Image Generation and Editing through the OpenAI-compatible mode without changing your request structure. Text-to-image (T2I) and image-to-image/image editing (I2I) share the same endpoint: omit image for T2I, and provide image for I2I.
NoteThe OpenAI-compatible mode is a synchronous, non-streaming endpoint. Image editing uses the image extension field on /images/generations. It does not use the multipart file upload format of the official OpenAI /images/edits endpoint. The following are not yet supported: asynchronous calls, streaming output, partial images, /images/edits, multipart, and mask. Passing response_format=b64_json does not raise an error, but it is ignored and the response still contains image URLs. For asynchronous calls, use DashScope asynchronous.
URL
Singapore
HTTP endpoint: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url for SDK calls: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
US (Virginia)
HTTP endpoint: POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url for SDK calls: https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
China (Beijing)
HTTP endpoint: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url for SDK calls: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
China (Hong Kong)
HTTP endpoint: POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url for SDK calls: https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
Germany (Frankfurt)
HTTP endpoint: POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url for SDK calls: https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
Japan (Tokyo)
HTTP endpoint: POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
base_url for SDK calls: https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
Replace {WorkspaceId} with your actual workspace ID.
Request parametersHeadersContent-Type The content type of the request. Must be Authorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. Request bodyUnlike the DashScope protocol, the OpenAI-compatible mode places all parameters at the top level of the request body. There is no model The model name. Available values: prompt The positive prompt that describes the image content, style, and composition you want to generate or edit. Both Chinese and English are supported. Recommended maximum: 4,500 tokens. Cannot be an empty string. image The URL or Base64 encoded data of the input image. Omit this parameter for text-to-image (T2I). Provide it for image-to-image (I2I), where the qwen-image-2.1 series supports 1-10 images, and the qwen-image-3.0 series supports 1-3 images. Pass a string for a single image, or an array of strings for multiple images. When multiple images are provided, the order is defined by the array sequence. Note:
n The number of output images. Value range: 1 to 6. Default: 1. Must be an integer. A string value such as size The output image resolution in the format WarningThe OpenAI protocol uses the letter
negative_prompt The negative prompt that describes content you do not want to appear in the image. Only the qwen-image-3.0 series supports this parameter. seed The random seed. Value range: prompt_extend Whether to enable intelligent prompt rewriting. Default: prompt_extend_mode The prompt rewriting method. Default:
enable_thinking Enables thinking mode. The default is watermark Whether to add a watermark. Default: Note | |
Response parameterscreated The Unix timestamp, in seconds, when the response was created. data The list of generated results. When usage The resource usage of this call. Only returned on success. These are image input and output metering fields, not token usage. error The error details. Only returned for failed requests. NoteUnlike the DashScope protocol, the OpenAI-compatible mode does not return | SuccessImage URLs are retained for only 24 hours and then automatically purged. Save generated images promptly. ErrorIf the request fails, the response contains an |
SDK
Install or upgrade the OpenAI Python SDK first:
pip install -U openai
ImportantImage generation can take a long time. Set an explicit, generous client timeout. For multi-image output (a larger n) or concurrent requests, start at 600 seconds so the client does not disconnect early.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="A vertical outdoor portrait photograph with a warm afternoon street atmosphere. Deep green vines and small orange flowers cascade from building eaves across the upper area. A dark blue sign reads 'Il Messaggero' in white Gothic lettering, partially obscured by foliage. Below, a newsstand displays newspapers behind black metal-framed glass, blurred by shallow depth of field. Strong backlight streams from the street's end. Center-right, a young woman in a black spaghetti-strap backless dress looks back at the camera with a warm smile. Her long, thick wavy black hair is outlined by golden rim light. She has fair skin, bright eyes, soft coral-red lips, and holds a large bouquet of orange, apricot, pink and peach roses contrasting with her black dress. The sunlit city street stretches into the blurred background. Warm film-like tones with fine grain, soft contrast and pronounced backlit edge glow create a romantic, bright, urban strolling atmosphere.",
size="1024x1024",
n=1,
# All parameters above are official OpenAI parameters. Extension fields such as
# image and prompt_extend go through extra_body. See the I2I example.
)
for item in response.data:
print(item.url)
print(f"request_id: {response._request_id}")
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop.",
size="1024x1024",
n=1,
extra_body={
# A single image can also be passed as a plain string. Base64 is also accepted:
# data:{MIME_type};base64,{base64_data}
"image": [
"https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
],
"prompt_extend": True,
},
)
for item in response.data:
print(item.url)
print(f"request_id: {response._request_id}")
import os
from openai import OpenAI, APIStatusError
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
try:
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="A vertical outdoor portrait photograph with a warm afternoon street atmosphere.",
)
print(response.data[0].url)
except APIStatusError as exc:
print(f"status_code: {exc.status_code}")
print(f"request_id: {exc.request_id}")
print(exc)
DashScope synchronous API (recommended)
HTTP
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
US (Virginia)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
China (Beijing)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
China (Hong Kong)
POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Germany (Frankfurt)
POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Japan (Tokyo)
POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Replace {WorkspaceId} with your actual workspace ID.
Request parametersHeadersContent-Type The content type of the request. Must be Authorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. Request bodymodel The model name. Available values: input The input parameter object, which contains the following fields: parameters Additional parameters to control image generation. | |
Response parametersoutput Contains the model generation results. usage The resource usage of this call. Only returned on success. These are image input and output metering fields, not token usage. request_id Unique request identifier for tracing and troubleshooting. code Error code. Returned only for failed requests. See Error codes. message Detailed error message. Returned only for failed requests. See Error codes. | SuccessTask data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. ErrorIf the task fails, the response includes the error code and message. See Error codes for troubleshooting. |
SDK
The following examples demonstrate how to call the API using Python and Java SDKs for image-to-image / image editing (I2I).
import os
import base64
import mimetypes
import dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
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}"
# [Method 1] Use a public image URL
image_url = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
# [Method 2] Use a Base64-encoded image
# image_url = encode_file("./your_image.png")
response = MultiModalConversation.call(
api_key=os.getenv("DASHSCOPE_API_KEY"),
model="qwen-image-3.0-pro",
messages=[{
"role": "user",
"content": [
{"image": image_url},
{"text": "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop."}
]
}],
prompt_extend=True
)
print(response)
if response.status_code == 200:
url = response.output.choices[0].message.content[0]["image"]
print(f"Generated image URL: {url}")
else:
print(f"Error: {response.code} - {response.message}")
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";
// [Method 1] Use a public image URL
String imageUrl = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png";
// [Method 2] Use a Base64-encoded image
// 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", "Generate a sophisticated urban-style female portrait. Perfectly preserve the facial features and smooth black long hair of the young woman in the input image. Change her outfit to an elegant urban professional look. Set the scene in a modern minimalist upscale coffee shop.")
))
.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;
}
}
DashScope asynchronous API
In addition to the synchronous call described above, Qwen Image Generation and Editing also supports asynchronous calls. The asynchronous API shares the same request parameter structure as the synchronous API. You only need to add the X-DashScope-Async: enable header. After the service accepts the request, it returns a task ID (task_id), which you then use to poll the query API for the final result.
ImportantThe endpoint for the asynchronous API differs from the synchronous API. Use the endpoints in this section instead of the synchronous endpoint.
HTTP
Asynchronous calls use a two-step workflow:
- Create a task to get a task ID: Send a request to create a task. The response contains a task ID (task_id).
- Poll for results using the task ID: Use the task_id to poll the task status until the task completes and the image URL is returned.
Step 1: Create a task to get a task ID
Singapore
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
US (Virginia)
POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
China (Beijing)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
China (Hong Kong)
POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Germany (Frankfurt)
POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Japan (Tokyo)
POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Request parametersHeadersContent-Type The content type of the request. Must be Authorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. X-DashScope-Async Enables asynchronous processing. Must be ImportantIf this request header is missing, the error "current user api does not support synchronous calls" is returned. Request bodymodel The model name. Available values: input The input parameter object, which contains the following fields: parameters Additional parameters to control image generation. | |
Response parametersoutput The task acceptance information. request_id Unique request identifier for tracing and troubleshooting. code Error code. Returned only for failed requests. See Error codes. | Successful responseSave the Error responseTask creation failed. See Error codes. |
Step 2: Poll for results using the task ID
Singapore
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
US (Virginia)
GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
China (Beijing)
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
China (Hong Kong)
GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_id}
Germany (Frankfurt)
GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
Japan (Tokyo)
GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
You must use the same region, workspace, and API key as when you created the task. Cross-region or cross-workspace queries are not supported.
Request parametersHeadersAuthorization Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. URL path parameterstask_id The ID of the task. | Query task resultReplace |
Response parametersoutput The task output information. usage The resource usage of this call. Only returned on success. These are image input and output metering fields, not token usage. request_id Unique request identifier for tracing and troubleshooting. code Error code. Returned only for failed requests. See Error codes. message Detailed error message. Returned only for failed requests. See Error codes. | Task succeededTask data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. Task failedWhen a task fails, |
Error codes
If the model call fails and returns an error message, see Error codes for resolution.