Qwen-Image is a general-purpose image generation model. It supports multiple artistic styles and excels at complex text rendering. The model supports multi-line and paragraph-level text generation, along with fine-grained detail rendering, enabling complex designs that combine text and images.
Quick links: User guide | Try it online (Singapore | Beijing) | Technical blog (more examples) |
Performance showcase
Input prompt | Output image |
Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere. |
|
Model overview
Model name | Model description | Output image specifications |
qwen-image-max Currently has the same capabilities as qwen-image-max-2025-12-30. | Qwen-Image-Max improves upon the Plus series by enhancing the realism and naturalness of images. It effectively reduces AI-generated artifacts and excels in rendering character textures, fine details, and text. | Image resolution: For available resolutions and their corresponding aspect ratios, see the size parameter settings. Image format: PNG Number of images: Fixed at 1 |
qwen-image-max-2025-12-30 | ||
qwen-image-plus Currently has the same capabilities as qwen-image. | Supports a variety of artistic styles and excels at rendering complex text in images, allowing for mixed text-and-image layout designs. | |
qwen-image-plus-2026-01-09 | ||
qwen-image |
Currently, only the qwen-image-plus and qwen-image models support asynchronous API calls.
Before making a call, check the Model list to confirm model availability in your region.
Prerequisites
Before making a call, obtain an API key and set the API key as an environment variable. To make calls using the SDK, install the DashScope SDK.
The Beijing and Singapore regions have separate API keys and request endpoints. Do not use them interchangeably. Cross-region calls result in authentication failures or service errors.
Synchronous API (recommended)
HTTP call
Qwen-Image supports a synchronous API, which lets you retrieve results with a single request. Because the calling process is simple, this API is recommended for most scenarios.
Singapore: POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
China (Beijing): POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Request parameters | Text-to-image |
Request headers | |
Content-Type The content type of the request. Must be | |
Authorization The authentication credentials using a Model Studio API key. Example: | |
Request body | |
model The model name. Example: | |
input The basic input information for the model. | |
parameters Image processing parameters. |
Response parameters | Task successfulTask data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. Abnormal task executionIf a task fails, the response includes information about the error. The code and message fields indicate the cause of the error. For more information about how to resolve the issue, see Error messages. |
output Task output information. | |
usage Usage statistics for the output. Only successful results are counted. | |
request_id Unique identifier for the request. Use for tracing and troubleshooting issues. | |
code The error code. Returned only when the request fails. See error codes for details. | |
message Detailed error message. Returned only when the request fails. See error codes for details. |
DashScope SDK
The DashScope SDK currently supports Python and Java.
The parameter names in the SDK are mostly consistent with those in the HTTP API. The parameter structure is adapted for each language. For descriptions of the parameters for synchronous calls, see HTTP invocation.
Python
Make sure that you have installed the latest version of the DashScope Python SDK, otherwise a runtime error may occur: Install SDK.
Request example
import json
import os
import dashscope
from dashscope import MultiModalConversation
# The following URL is for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
messages = [
{
"role": "user",
"content": [
{"text": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."}
]
}
]
# The API keys for the Singapore and China (Beijing) regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")
response = MultiModalConversation.call(
api_key=api_key,
model="qwen-image-max",
messages=messages,
result_format='message',
stream=False,
watermark=False,
prompt_extend=True,
negative_prompt="low resolution, low quality, deformed limbs, deformed fingers, oversaturated, waxy, no facial details, overly smooth, AI-like, chaotic composition, blurry text, distorted text.",
size='1664*928'
)
if response.status_code == 200:
print(json.dumps(response, ensure_ascii=False))
else:
print(f"HTTP status code: {response.status_code}")
print(f"Error code: {response.code}")
print(f"Error message: {response.message}")
print("For more information, see the documentation: https://www.alibabacloud.com/help/en/model-studio/error-code")Response example
The image URL is valid for 24 hours. Download the image promptly.
{
"status_code": 200,
"request_id": "d2d1a8c0-325f-9b9d-8b90-xxxxxx",
"code": "",
"message": "",
"output": {
"text": null,
"finish_reason": null,
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png?Expires=xxx"
}
]
}
}
],
"task_metric": {
"TOTAL": 1,
"FAILED": 0,
"SUCCEEDED": 1
}
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"width": 1328,
"image_count": 1,
"height": 1328
}
}Java
Make sure that you have installed the latest version of the DashScope SDK for Java. Otherwise, you may encounter runtime errors. For more information, see Install the SDK.
Request example
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.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import java.io.IOException;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
public class QwenImage {
static {
// The following is the base_url for the Singapore region. If you use a model in the China (Beijing) region, replace the base_url with: https://dashscope.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// The API keys for the Singapore and China (Beijing) regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If you have not configured an environment variable, replace the following line with your Model Studio API key: static String apiKey="sk-xxx"
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void call() throws ApiException, NoApiKeyException, UploadFileException, IOException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("text", "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.")
)).build();
Map<String, Object> parameters = new HashMap<>();
parameters.put("watermark", false);
parameters.put("prompt_extend", true);
parameters.put("negative_prompt", "low resolution, low quality, deformed limbs, deformed fingers, oversaturated, waxy, no facial details, overly smooth, AI-like, chaotic composition, blurry text, distorted text.");
parameters.put("size", "1664*928");
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(apiKey)
.model("qwen-image-max")
.messages(Collections.singletonList(userMessage))
.parameters(parameters)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
call();
} catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
Response example
The image URL is valid for 24 hours. Download the image promptly.
{
"requestId": "5b6f2d04-b019-40db-a5cc-xxxxxx",
"usage": {
"image_count": 1,
"width": 1328,
"height": 1328
},
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png?Expires=xxx"
}
]
}
}
]
}
}Asynchronous API
Currently, only the qwen-image-plus and qwen-image models support asynchronous API calls.
HTTP call
Qwen-Image also supports an asynchronous API. The HTTP call flow consists of two steps:
Create a task to obtain a task ID: Send a request to create a task. The response returns a task ID (task_id).
Query the result using the task ID: Use the task_id to poll the task status until the task is complete and you retrieve the image URL.
Step 1: Create a task to get a task ID
Singapore: POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
China (Beijing): POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
After the task is created, use the returned
task_idto query the result. Thetask_idis valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.For a beginner's tutorial, see Postman.
Request parameters | Text-to-imageCurrently, only the |
Request headers | |
Content-Type The content type of the request. Must be | |
Authorization The authentication credentials using a Model Studio API key. Example: | |
X-DashScope-Async Enables asynchronous processing. Must be Important Returns "current user api does not support synchronous calls" error if not included. | |
Request body | |
model The model name. Currently, only the Example: | |
input The basic input information, such as the prompt. | |
parameters Image processing parameters. |
Response parameters | Successful responseSave the Error responseTask creation failed. See error codes to resolve the issue. |
output Task output information. | |
request_id Unique identifier for the request. Use for tracing and troubleshooting issues. | |
code The error code. Returned only when the request fails. See error codes for details. | |
message Detailed error message. Returned only when the request fails. See error codes for details. |
Step 2: Query the result using the task ID
Singapore: GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}
Beijing: GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
Polling recommendation: The model takes about 15 seconds to run. We recommend that you use a polling mechanism with a reasonable query interval, such as 3 seconds, to retrieve the result. The actual time depends on the number of tasks in the queue and network conditions.
Task status flow: PENDING (in queue) -> RUNNING (processing) -> SUCCEEDED (successful) / FAILED (failed).
Result link: After a task succeeds, an image link is returned. The link is valid for 24 hours. You should promptly download and transfer the image to a storage space, such as Object Storage Service (OSS).
Request parameters | Query task resultReplace API keys are region-specific. See API key documentation for details. For models in the Beijing region, replace base_url with |
Request headers | |
Authorization The authentication credentials using a Model Studio API key. Example: | |
URL path parameters | |
task_id The ID of the task to query. |
Response parameters | Task successfulTask 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, |
output Task output information. | |
usage Usage statistics for the output. Only successful results are counted. | |
request_id Unique identifier for the request. Use for tracing and troubleshooting issues. |
DashScope SDK
The DashScope SDK currently supports Python and Java.
The parameter names in the SDK are mostly consistent with those in the HTTP API. The parameter structure depends on the SDK implementation for each language. For parameter descriptions for asynchronous invocations, see HTTP Invocation.
Because image models require long processing times, the underlying service is asynchronous. The SDK builds on this by providing the following two calling modes:
Synchronous call (blocking mode): The SDK automatically waits for the task to complete and then directly returns the final result. The calling experience is consistent with a regular synchronous call.
Asynchronous call (non-blocking mode): The call immediately returns a task ID. You must use this ID to query the task status and the final result.
Python SDK
Make sure that you have installed the latest version of the DashScope Python SDK, otherwise a runtime error may occur: Install SDK.
Synchronous call
Request example
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope
# The following URL is for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
prompt = "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."
# The API keys for the Singapore and China (Beijing) regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")
print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(api_key=api_key,
model="qwen-image-plus", # Currently, only the qwen-image-plus and qwen-image models support asynchronous API calls.
prompt=prompt,
negative_prompt=" ",
n=1,
size='1664*928',
prompt_extend=True,
watermark=False)
print(f'response: {rsp}')
if rsp.status_code == HTTPStatus.OK:
# Save the image to the current directory.
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print(f'sync_call Failed, status_code: {rsp.status_code}, code: {rsp.code}, message: {rsp.message}')
Response example
The URL is valid for 24 hours. Download the image promptly.
{
"status_code": 200,
"request_id": "a47b1a65-7041-4565-9068-xxxxxx",
"code": null,
"message": "",
"output": {
"task_id": "91093132-475e-43cf-b94e-xxxxxx",
"task_status": "SUCCEEDED",
"results": [
{
"url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxxxx",
"orig_prompt": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.",
"actual_prompt": "Childhood-inspired hand-drawn poster design: Three playful puppies joyfully interact with a colorful ball on a vibrant patch of lush green grass. Delicate decorative elements including fluttering birds and twinkling stars are scattered throughout. At the top center, the bold, blue cartoon-style title “Come Play Ball!” stands out prominently. Directly beneath, the subtitle “Come [Show Off Your Skills]!” is rendered in cheerful green lettering. A whimsical speech bubble near one of the puppies contains the playful text: “Hehe, watch me amaze my little friends next!” At the bottom edge, smaller supplementary text reads: “We get to play ball with our friends again!” The color palette is centered on fresh greens and sky blues, accented with pops of bright pink and sunny yellow, enhancing the cheerful, childlike atmosphere. Style evokes nostalgic, hand-inked illustrations with soft textures, gentle linework, and a whimsical, storybook-like composition."
}
],
"submit_time": "2025-09-09 13:39:20.659",
"scheduled_time": "2025-09-09 13:39:20.717",
"end_time": "2025-09-09 13:39:45.233"
},
"usage": {
"image_count": 1
}
}Asynchronous call
Request example
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope
import time
# The following URL is for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
prompt = "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."
# The API keys for the Singapore and China (Beijing) regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")
def async_call():
print('----Creating Task----')
task_info = create_async_task()
print('----Polling Task Status----')
poll_task_status(task_info)
# Create asynchronous task
def create_async_task():
rsp = ImageSynthesis.async_call(api_key=api_key,
model="qwen-image-plus", # Currently, only the qwen-image-plus and qwen-image models support asynchronous API calls.
prompt=prompt,
negative_prompt=" ",
n=1,
size='1664*928',
prompt_extend=True,
watermark=False)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
else:
print(f'Failed to create task, status_code: {rsp.status_code}, code: {rsp.code}, message: {rsp.message}')
return rsp
# Poll asynchronous task status, query every 5 seconds, maximum polling for 1 minute
def poll_task_status(task):
start_time = time.time()
timeout = 60 # 1 minute timeout
while True:
# Check if timeout
if time.time() - start_time > timeout:
print('Polling timeout (1 minute), task not completed')
return
# Get task status
status_rsp = ImageSynthesis.fetch(task)
print(f'Task status query result: {status_rsp}')
if status_rsp.status_code != HTTPStatus.OK:
print(f'Failed to get task status, status_code: {status_rsp.status_code}, code: {status_rsp.code}, message: {status_rsp.message}')
return
task_status = status_rsp.output.task_status
print(f'Current task status: {task_status}')
if task_status == 'SUCCEEDED':
print('Task completed, downloading image...')
for result in status_rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open(f'./{file_name}', 'wb+') as f:
f.write(requests.get(result.url).content)
print(f'Image saved as: {file_name}')
break
elif task_status == 'FAILED':
print(f'Task execution failed, status: {task_status}, code: {status_rsp.code}, message: {status_rsp.message}')
break
elif task_status == 'PENDING' or task_status == 'RUNNING':
print('Task in progress, continue querying after 5 seconds...')
time.sleep(5)
else:
print(f'Unknown task status: {task_status}, continue querying after 5 seconds...')
time.sleep(5)
# Cancel asynchronous task, only tasks in PENDING status can be canceled
def cancel_task(task):
rsp = ImageSynthesis.cancel(task)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.task_status)
else:
print(f'Failed to cancel task, status_code: {rsp.status_code}, code: {rsp.code}, message: {rsp.message}')
if __name__ == '__main__':
async_call()
Response example
1. Sample response for creating a task
{
"status_code": 200,
"request_id": "31b04171-011c-96bd-ac00-xxxxxx",
"code": "",
"message": "",
"output": {
"task_id": "4f90cf14-a34e-4eae-xxxxxxxx",
"task_status": "PENDING",
"results": []
},
"usage": null
}2. Sample response for querying the task result
The URL is valid for 24 hours. Download the image promptly.
{
"status_code": 200,
"request_id": "a47b1a65-7041-4565-9068-xxxxxx",
"code": null,
"message": "",
"output": {
"task_id": "91093132-475e-43cf-b94e-xxxxxx",
"task_status": "SUCCEEDED",
"results": [
{
"url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxxxx",
"orig_prompt": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.",
"actual_prompt": "Childhood-inspired hand-drawn poster design: Three playful puppies joyfully interact with a colorful ball on a vibrant patch of lush green grass. Delicate decorative elements including fluttering birds and twinkling stars are scattered throughout. At the top center, the bold, blue cartoon-style title “Come Play Ball!” stands out prominently. Directly beneath, the subtitle “Come [Show Off Your Skills]!” is rendered in cheerful green lettering. A whimsical speech bubble near one of the puppies contains the playful text: “Hehe, watch me amaze my little friends next!” At the bottom edge, smaller supplementary text reads: “We get to play ball with our friends again!” The color palette is centered on fresh greens and sky blues, accented with pops of bright pink and sunny yellow, enhancing the cheerful, childlike atmosphere. Style evokes nostalgic, hand-inked illustrations with soft textures, gentle linework, and a whimsical, storybook-like composition."
}
],
"submit_time": "2025-09-09 13:39:20.659",
"scheduled_time": "2025-09-09 13:39:20.717",
"end_time": "2025-09-09 13:39:45.233"
},
"usage": {
"image_count": 1
}
}Java SDK
Make sure that you have installed the latest version of the DashScope SDK for Java. Otherwise, you may encounter runtime errors. For more information, see Install the SDK.
Synchronous call
Request example
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;
public class Text2Image {
static {
// The following URL is for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// The API keys for the Singapore and China (Beijing) regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If you have not configured an environment variable, replace the following line with your Model Studio API key: static String apiKey = "sk-xxx"
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void basicCall() throws ApiException, NoApiKeyException {
String prompt = "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.";
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("negative_prompt", " ");
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
// Currently, only the qwen-image-plus and qwen-image models support asynchronous API calls.
.model("qwen-image-plus")
.prompt(prompt)
.n(1)
.size("1664*928")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageSynthesis.call(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args){
try{
basicCall();
}catch(ApiException|NoApiKeyException e){
System.out.println(e.getMessage());
}
}
}
Response example
The URL is valid for 24 hours. Download the image promptly.
{
"request_id": "9f3044ba-528f-4606-8830-xxxxxx",
"output": {
"task_id": "fecf4c7f-3508-45f4-8454-xxxxxx",
"task_status": "SUCCEEDED",
"results": [
{
"orig_prompt": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.",
"actual_prompt": "Childhood-inspired hand-drawn poster design: Three playful puppies joyfully interact with a colorful ball on a vibrant patch of lush green grass. Delicate decorative elements including fluttering birds and twinkling stars are scattered throughout. At the top center, the bold, blue cartoon-style title “Come Play Ball!” stands out prominently. Directly beneath, the subtitle “Come [Show Off Your Skills]!” is rendered in cheerful green lettering. A whimsical speech bubble near one of the puppies contains the playful text: “Hehe, watch me amaze my little friends next!” At the bottom edge, smaller supplementary text reads: “We get to play ball with our friends again!” The color palette is centered on fresh greens and sky blues, accented with pops of bright pink and sunny yellow, enhancing the cheerful, childlike atmosphere. Style evokes nostalgic, hand-inked illustrations with soft textures, gentle linework, and a whimsical, storybook-like composition.",
"url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxx"
}
]
},
"usage": {
"image_count": 1
}
}Asynchronous call
Request example
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;
public class Text2Image {
static {
// The following URL is for the Singapore region. If you use a model in the China (Beijing) region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
}
// The API keys for the Singapore and China (Beijing) regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
// If you have not configured an environment variable, replace the following line with your Model Studio API key: static String apiKey = "sk-xxx"
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public void asyncCall() {
System.out.println("---Creating task----");
String taskId = this.createAsyncTask();
System.out.println("--Waiting for task to complete and return image url----");
this.waitAsyncTask(taskId);
}
public String createAsyncTask() {
String prompt = "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.";
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("negative_prompt", " ");
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
// Currently, only the qwen-image-plus and qwen-image models support asynchronous API calls.
.model("qwen-image-plus")
.prompt(prompt)
.n(1)
.size("1664*928")
.parameters(parameters)
.build();
try {
ImageSynthesisResult result = new ImageSynthesis().asyncCall(param);
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
System.out.println("task_id=" + taskId);
return taskId;
} catch (Exception e) {
throw new RuntimeException(e.getMessage());
}
}
public void waitAsyncTask(String taskId) {
ImageSynthesis imageSynthesis = new ImageSynthesis();
long startTime = System.currentTimeMillis();
int timeout = 60 * 1000; // 1 minute timeout
int interval = 5 * 1000; // 5 second polling interval
while (true) {
if (System.currentTimeMillis() - startTime > timeout) {
System.out.println("Polling timed out (1 minute), task not completed");
return;
}
try {
ImageSynthesisResult result = imageSynthesis.fetch(taskId, apiKey);
System.out.println("Task status query result: " + JsonUtils.toJson(result));
if (result.getOutput() == null) {
System.out.println("Failed to get task status, output is empty");
return;
}
String taskStatus = result.getOutput().getTaskStatus();
System.out.println("Current task status: " + taskStatus);
switch (taskStatus) {
case "SUCCEEDED":
System.out.println("Task completed");
System.out.println(JsonUtils.toJson(result));
return;
case "FAILED":
System.out.println("Task execution failed, status: " + taskStatus);
return;
case "PENDING":
case "RUNNING":
System.out.println("Task in progress, querying again in 5 seconds...");
Thread.sleep(interval);
break;
default:
System.out.println("Unknown task status: " + taskStatus + ", querying again in 5 seconds...");
Thread.sleep(interval);
break;
}
} catch (ApiException | NoApiKeyException e) {
System.err.println("API call exception: " + e.getMessage());
return;
} catch (InterruptedException e) {
System.err.println("Thread interruption exception: " + e.getMessage());
Thread.currentThread().interrupt();
return;
}
}
}
public static void main(String[] args){
Text2Image text2Image = new Text2Image();
text2Image.asyncCall();
}
}Response example
1. Sample response for creating a task
{
"request_id": "5dbf9dc5-4f4c-9605-85ea-542f97709ba8",
"output": {
"task_id": "7277e20e-aa01-4709-xxxxxxxx",
"task_status": "PENDING"
}
}2. Sample response for querying the task result
The URL is valid for 24 hours. Download the image promptly.
{
"request_id": "9f3044ba-528f-4606-8830-xxxxxx",
"output": {
"task_id": "fecf4c7f-3508-45f4-8454-xxxxxx",
"task_status": "SUCCEEDED",
"results": [
{
"orig_prompt": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.",
"actual_prompt": "Childhood-inspired hand-drawn poster design: Three playful puppies joyfully interact with a colorful ball on a vibrant patch of lush green grass. Delicate decorative elements including fluttering birds and twinkling stars are scattered throughout. At the top center, the bold, blue cartoon-style title “Come Play Ball!” stands out prominently. Directly beneath, the subtitle “Come [Show Off Your Skills]!” is rendered in cheerful green lettering. A whimsical speech bubble near one of the puppies contains the playful text: “Hehe, watch me amaze my little friends next!” At the bottom edge, smaller supplementary text reads: “We get to play ball with our friends again!” The color palette is centered on fresh greens and sky blues, accented with pops of bright pink and sunny yellow, enhancing the cheerful, childlike atmosphere. Style evokes nostalgic, hand-inked illustrations with soft textures, gentle linework, and a whimsical, storybook-like composition.",
"url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxx"
}
]
},
"usage": {
"image_count": 1
}
}Billing and rate limits
For free quota and pricing, see Model pricing.
For the model's rate limits, see Qwen (Qwen-Image).
Billing: You are charged based on the number of successfully generated images. Failed model calls or processing errors do not incur any fees or consume the free quota.
Image access configuration
Generated images are stored in Alibaba Cloud OSS. Each image is assigned an OSS link, such as https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.png. OSS links allow public access, and you can use them to view or download the image. The link is valid for only 24 hours.
If your business has high security requirements and cannot access Alibaba Cloud OSS links, you must configure a whitelist for public access. Add the following domain names to your whitelist to access the image links.
# OSS domain name list
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.comError codes
If a call fails, see Error messages for troubleshooting.
FAQ
Q: Should I enable or disable prompt_extend?
A: Keep this parameter enabled (the default setting) if your input prompt is simple or if you want the model to be more creative. Set it to `false` if your prompt is already detailed and professional, or if you have strict requirements for API response latency.
Q: What are the differences between the qwen-image, qwen-image-plus, qwen-image-max, and qwen-image-edit models?
A:
Text-to-image models: Generate images from text descriptions.
qwen-image-maxandqwen-image-max-2025-12-30: Both models currently have the same capabilities. Compared toqwen-image-plus, they improve the realism and naturalness of generated images and perform better in rendering character textures, fine details, and text.qwen-imageandqwen-image-plus: Both models currently have the same capabilities, butqwen-image-plusis more cost-effective.qwen-image-plus-2026-01-09: A new snapshot version of the Qwen image generation model. It is a distilled and accelerated version ofqwen-image-maxand supports the rapid generation of high-quality images.
Image editing model:
qwen-image-edit: Performs operations such as image-to-image generation and local modifications based on an input image and text instructions. For more information, see Qwen - image editing.
