Generate images from text descriptions with the text-to-image API. This service, provided by Alibaba Cloud Model Studio, features the Wan, Qwen-Image, and Z-Image model families.
Try it online: Beijing | Singapore
Model performance
Qwen-Image
Complex layout
| Long paragraph
| Realistic portrait
|
UI design
| PPT
| Illustration design
|
Wanxiang
Portrait photography
| Photorealistic photography
| Artistic styles
|
Text rendering
| Poster design
| Image set generation
|
Model selection
qwen-image-3.0-pro: The flagship Qwen Image 3.0 model. Supports intelligent prompt rewriting and excels at rendering text that blends naturally with physical materials in both Chinese and English.
wan2.7-image-pro: Offers the most features, including multi-image generation, resolutions up to 4096x4096, and enhanced control over facial features, colors, and long text rendering.
z-image-turbo: Delivers fast, cost-effective image generation, excelling at highly realistic portraits and product images.
Quick start
Prerequisites
Before you begin, get an API key, then set the API key as an environment variable. If you use the DashScope SDK, you must also install the SDK.
Sample code
Calling methods:
Qwen text-to-image models all support synchronous calls. The qwen-image-3.0 series,
qwen-image-plusandqwen-imagemodels also support asynchronous calls. For more information, see Qwen - Image Generation and Editing 3.0 and Qwen - Text-to-Image.All Wan text-to-image models support asynchronous calls. The
wan2.7-image-pro,wan2.7-image,wan2.6-image, andwan2.6-t2imodels also support synchronous calls. For more information, see Wan - Image Generation and Editing 2.7, Wan - Image Generation and Editing 2.6, and Wan - Text-to-Image V2.
Qwen - synchronous call
Python
import os
import dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'
response = MultiModalConversation.call(
api_key=os.getenv("DASHSCOPE_API_KEY"),
model="qwen-image-3.0-pro",
messages=[{
"role": "user",
"content": [
{"text": "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."}
]
}],
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}")Java
import java.util.Arrays;
import java.util.Collections;
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}.cn-beijing.maas.aliyuncs.com/api/v1";
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("text", "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.")
))
.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();
}
}
}curl
Request example
curl --location 'https://{WorkspaceId}.cn-beijing.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": [
{
"text": "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."
}
]
}
]
},
"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"
}Wan - asynchronous call
Python
Request example
import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
# This is the base URL for the China (Beijing) region; base URLs are region-specific.
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'
# If the environment variable is not set, replace the following line with your Model Studio API key: api_key="sk-xxx"
# API keys vary by region. To get an API key, visit: https://help.aliyun.com/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
def main():
message = Message(
role="user",
content=[
{"text": "A young woman in a natural, casual selfie style. An ultra-high-definition, realistic lifestyle photo. She is wearing a yellow floral long-sleeved top, and her long, slightly wavy hair falls naturally. The background is an outdoor natural scene with green plants nearby and water and mountains in the distance. Soft, natural sunlight falls on her face and body, creating natural light and shadow effects. The camera angle is a medium shot from a selfie perspective, as if held by her. She is standing naturally, projecting a relaxed and comfortable state. The angle is natural, in the style of a casual snapshot—an unguarded moment."}
]
)
# Submit an asynchronous task.
print("Submitting the asynchronous task...")
response = ImageGeneration.async_call(
model="wan2.7-image-pro",
api_key=api_key,
messages=[message],
enable_sequential=False,
n=1,
size="2K"
)
if response.status_code == 200:
print(f"Task submitted successfully. Task ID: {response.output.task_id}")
# Wait for the task to complete.
status = ImageGeneration.wait(task=response, api_key=api_key)
if status.output.task_status == "SUCCEEDED":
print("Task completed!")
print(f"Result:")
print(status)
else:
print(f"Task failed. Status: {status.output.task_status}")
else:
print(f"Task creation failed: {response.code} - {response.message}")
if __name__ == "__main__":
try:
main()
except Exception as e:
print(f"Error: {e}")Response example
1. Task creation response
{
"status_code": 200,
"request_id": "4fb3050f-de57-4a24-84ff-e37ee5xxxxxx",
"code": "",
"message": "",
"output": {
"text": null,
"finish_reason": null,
"choices": null,
"audio": null,
"task_id": "77093787-a217-4c29-9cd4-ca7b5ac86xxx",
"task_status": "PENDING"
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"characters": 0
}
}2. Task status query response
The usage field is included in the raw HTTP API response. In the Python SDK, the ImageGeneration.wait() method returns a response object where the output property contains task status fields (such as task_status, task_id, choices, submit_time, scheduled_time, end_time, finished), but does not include the usage field. To access billing information (such as image_count, total_tokens, size), use the raw HTTP response or query the task status API directly.
The image URL is valid for 24 hours. Download the image promptly.
{
"status_code": 200,
"request_id": "56e318fd-ed60-99e8-8ca1-cdef25ca4xxx",
"code": "",
"message": "",
"output": {
"text": null,
"finish_reason": null,
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
"type": "image"
}
]
}
}
],
"audio": null,
"task_id": "77093787-a217-4c29-9cd4-ca7b5ac86xxx",
"task_status": "SUCCEEDED",
"submit_time": "2026-03-31 23:04:46.166",
"scheduled_time": "2026-03-31 23:04:46.208",
"end_time": "2026-03-31 23:05:11.664",
"finished": true
},
"usage": {
"input_tokens": 720,
"output_tokens": 11,
"characters": 0,
"size": "2048*2048",
"total_tokens": 731,
"image_count": 1
}
}Java
Request example
import com.alibaba.dashscope.aigc.imagegeneration.*;
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 java.util.Collections;
public class Main {
// This is the base URL for the China (Beijing) region; base URLs are region-specific.
static String baseUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
// If the environment variable is not set, replace the following line with your Model Studio API key: apiKey="sk-xxx"
// API keys vary by region. To get an API key, visit: https://help.aliyun.com/en/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static ImageGenerationResult waitTask(String taskId)
throws ApiException, NoApiKeyException {
ImageGeneration imageGeneration = new ImageGeneration(apiKey, baseUrl);
return imageGeneration.wait(taskId, apiKey);
}
public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "A young woman in a natural, casual selfie style. An ultra-high-definition, realistic lifestyle photo. She is wearing a yellow floral long-sleeved top, and her long, slightly wavy hair falls naturally. The background is an outdoor natural scene with green plants nearby and water and mountains in the distance. Soft, natural sunlight falls on her face and body, creating natural light and shadow effects. The camera angle is a medium shot from a selfie perspective, as if held by her. She is standing naturally, projecting a relaxed and comfortable state. The angle is natural, in the style of a casual snapshot—an unguarded moment.")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.7-image-pro")
.messages(Collections.singletonList(message))
.enableSequential(false)
.n(1)
.size("2K")
.build();
ImageGeneration imageGeneration = new ImageGeneration(apiKey, baseUrl);
ImageGenerationResult taskResult = null;
try {
System.out.println("----async call, creating task----");
taskResult = imageGeneration.asyncCall(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println("Task created: " + JsonUtils.toJson(taskResult));
// Wait for the task to complete.
String taskId = taskResult.getOutput().getTaskId();
ImageGenerationResult result = waitTask(taskId);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
asyncCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}Response example
1. Task creation response
{
"requestId": "7d026dc1-e8c9-9caa-84ac-e82e2da97xxx",
"output": {
"task_id": "2de18c56-c151-4b80-8105-1d164733exxx",
"task_status": "PENDING"
},
"status_code": 200,
"code": "",
"message": ""
}2. Task status query response
{
"requestId": "daea7295-4ce0-928a-9a11-4d2bea058xxx",
"usage": {
"input_tokens": 720,
"output_tokens": 11,
"total_tokens": 731,
"image_count": 1,
"size": "2048*2048"
},
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
"type": "image"
}
]
}
}
],
"task_id": "2de18c56-c151-4b80-8105-1d164733exxx",
"task_status": "SUCCEEDED",
"finished": true,
"submit_time": "2026-03-31 19:49:53.124",
"scheduled_time": "2026-03-31 19:49:53.175",
"end_time": "2026-03-31 19:50:53.160"
},
"status_code": 200,
"code": "",
"message": ""
}Curl
For an asynchronous call, you must set the Header parameter
X-DashScope-Asynctoenable.The
task_idof an asynchronous task can be queried for 24 hours. After this period, the task status changes toUNKNOWN.This method works for all models. For beginners, we recommend using Postman to call the API.
Step 1: Create a task
The request returns a task ID (task_id).
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "X-DashScope-Async: enable" \
--data '{
"model": "wan2.7-image-pro",
"input": {
"messages": [
{
"role": "user",
"content": [
{"text": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"}
]
}
]
},
"parameters": {
"size": "2K",
"n": 1,
"watermark": false,
"thinking_mode": true
}
}'
Step 2: Query task result
Use the task_id from the previous step to poll the API for the task status until the task_status changes to SUCCEEDED or FAILED.
Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID.
curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"Key capabilities
1. Prompt following
Parameters: messages.content.text or input.prompt (required), and negative_prompt (optional).
prompt: Describes the desired content for the image, including the subject, scene, style, lighting, and composition. This is the core parameter for controlling text-to-image generation.
negative prompt: Describes what to exclude from the image, such as "blurry" or "extra fingers." This parameter helps refine the output quality.
For best results, use a structured prompt. For more information, see Text-to-image prompt guide.
The negative_prompt parameter is not supported by wan2.7-image-pro and wan2.7-image. To exclude unwanted elements, describe them in the prompt (for example, "do not include xxx").2. Enable prompt rewriting
Parameter: parameters.prompt_extend (Boolean, defaults to true).
This feature automatically expands and optimizes short prompts to improve image quality. Enabling this feature adds 3 to 5 seconds to the generation time, as a large model is used to rewrite the prompt.
Recommendations:
Enable this feature for brief or general prompts to significantly improve image quality.
Disable this feature if you need precise control over image details, have provided a comprehensive prompt, or if response latency is a concern. To disable it, set the
prompt_extendparameter tofalse.
Theprompt_extendparameter is not supported by wan2.7-image-pro and wan2.7-image. To improve image quality for these models, enablethinking_modeinstead. The qwen-image-3.0-pro and qwen-image-3.0 models support theprompt_extendparameter (enabled by default).
Parameter: parameters.prompt_extend_mode (string, optional, defaults to direct). Supported only by qwen-image-3.0-pro and qwen-image-3.0. Specifies the rewriting method used when prompt_extend is enabled:
direct: Direct Prompt Enhancement (DPE), suitable for most scenarios. Supported for both text-to-image (T2I) and image-to-image/editing (I2I).agent: Agent Prompt Enhancement (APE), provides more refined rewriting. Only supported for text-to-image (T2I). Passingagentfor image-to-image/editing (I2I) returns a 400 error.
3. Set the output image resolution
Parameter: parameters.size (string), in the "width*height" format.
Model | Size format | Pixel range | Default | Aspect ratio |
wan2.7-image-pro | Shorthand |
|
| 1:8 – 8:1 |
Custom | 768*768 – 4096*4096 | |||
wan2.7-image | Shorthand |
|
| 1:8 – 8:1 |
Custom | 768*768 – 2048*2048 | |||
wan2.6-image (interleaved text-image output mode) | Custom | 768*768 – 1280*1280 | Matches input aspect ratio (≤1280*1280) | 1:4 – 4:1 |
wan2.6-t2i, wan2.5-t2i-preview | Custom | 1280*1280 – 1440*1440 | 1280*1280 | 1:4 – 4:1 |
wan2.2 and earlier t2i models | Custom | [512, 1440], and total pixels ≤1440*1440 | 1024*1024 | - |
qwen-image-3.0-pro, qwen-image-3.0 | Custom | 512*512 – 2048*2048 | Auto-recommended by model | 1:8 – 8:1 |
qwen-image-2.0 series | Custom | 512*512 – 2048*2048 | 2048*2048 | - |
qwen-image-max / qwen-image-plus series | Fixed preset sizes only | See preset sizes below | 1664*928 (16:9) | - |
The wan2.7-image-pro model supports 4K resolution and custom resolutions up to 4096*4096, but only for text-to-image tasks (where no image is input and image set generation is disabled). All other scenarios are limited to 2K resolution (2048*2048).The qwen-image-max and qwen-image-plus series support only the following five fixed resolutions:
1664*928(default): 16:91472*1104: 4:31328*1328: 1:11104*1472: 3:4928*1664: 9:16
Recommended resolutions:
Aspect ratio | 4K (wan2.7-image-pro) | 2K (wan2.7-image, qwen-image-3.0-pro, qwen-image-3.0, qwen-image-2.0) | 1K (Wan t2i) |
1:1 | 4096*4096 | 2048*2048 | 1280*1280 |
16:9 | 4096*2304 | 2688*1536 | 1696*960 |
9:16 | 2304*4096 | 1536*2688 | 960*1696 |
4:3 | 4096*3072 | 2368*1728 | 1472*1104 |
3:4 | 3072*4096 | 1728*2368 | 1104*1472 |
4. Image set generation
Parameter: parameters.enable_sequential (Boolean, defaults to false). Supported only by wan2.7-image-pro and wan2.7-image.
Set to true to enable image set generation mode. In this mode, the model uses the prompt and any reference images to generate multiple, story-coherent images from a single request.
Number of images: Controlled by the
nparameter. When this mode is enabled, this value can range from 1 to 12, with a default of 12. The model determines the actual number of images it generates, which will not exceedn.Note: When image set generation is enabled, the
thinking_modeandcolor_paletteparameters are unavailable.
5. Thinking mode
Parameter: parameters.thinking_mode (Boolean, defaults to true). Supported only by wan2.7-image-pro and wan2.7-image.
When enabled, the model enhances its reasoning capabilities to improve image quality. This increases the generation time.
Available only when image set generation is disabled (enable_sequential=false).6. Custom color palette
Parameter: parameters.color_palette (array). Supported only by wan2.7-image-pro and wan2.7-image.
Define the image's color scheme by providing an array of objects, where each object specifies a hex color and its ratio. You must provide 3 to 10 colors (8 is recommended), and the sum of all ratios must equal 100.00%.
Available only when image set generation is disabled (enable_sequential=false).Production deployment
Fault tolerance
Handling rate limiting: When the API returns the
Throttlingerror code or the HTTP 429 status code, rate limiting has been triggered. To handle rate limiting, see Rate Limiting.Polling for asynchronous tasks: When polling for the result of an asynchronous task, implement a reasonable polling strategy to avoid triggering rate limiting. For example, poll every 3 seconds for the first 30 seconds, then increase the polling interval. Set a final timeout for the task (e.g., 2 minutes). If the task times out, mark it as failed.
Risk prevention
Persist results: The API's image URLs are valid for 24 hours. Your production system must download the image immediately after receiving the URL and transfer it to your own persistent storage service, such as Alibaba Cloud Object Storage Service (OSS).
Content moderation: All
promptandnegative_promptinputs are subject to content moderation. If the input is non-compliant, the request is blocked and aDataInspectionFailederror is returned.Copyright and compliance risks of generated content: Ensure that your prompts comply with all applicable laws and regulations. Generating content that includes brand trademarks, celebrity likenesses, or copyrighted intellectual property (IP) may pose infringement risks. You are responsible for evaluating and bearing all associated risks.
API reference
Billing and rate limiting
For free quotas and pricing, see model pricing.
For rate limits, see Image generation.
You are charged only for successfully generated images. Failed requests and processing errors do not incur charges or consume the free quota for new users.
Error codes
If the model call fails and returns an error message, see Error codes for resolution.
FAQ
Q: How long are image URLs valid? How do I save images permanently?
A: Image URLs expire after 24 hours. You must programmatically download the image immediately and save it to persistent storage, such as a local server or Alibaba Cloud Object Storage Service.
Q: My API call returns a DataInspectionFailed error. How do I resolve this?
A: This error means your input triggered content moderation. Review your prompt or negative_prompt, remove any non-compliant content, and then retry the request.
Q: When should I enable or disable the prompt_extend parameter?
A: Keep it enabled (the default) for concise prompts or for more creative output. Set it explicitly to false when your prompt is already detailed and specialized, or when you are sensitive to API latency.
Note: The wan2.7-image-pro and wan2.7-image models do not support the prompt_extend parameter. To improve image quality, enable thinking_mode instead.











