Text-to-image

• Model Experience Center: Click a Try it online link above (Singapore, Beijing) to open it. You can select a model, set the output resolution, turn on prompt rewriting, and submit to generate images.

​

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.

​

Usage options

​

Quick start

​

Prerequisites

​

Sample code

• Qwen text-to-image models all support synchronous calls. The qwen-image-3.0 series, qwen-image-plus and qwen-image models 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, and wan2.6-t2i models 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.

import os
import dashscope
from dashscope import MultiModalConversation

dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.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}")

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}.ap-southeast-1.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 --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": [
                    {
                        "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
    }
}'

{
    "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": 0,
        "input_image_type": "qima_input_1k",
        "output_image_count": 1,
        "output_image_type": "qima_output_1k"
    },
    "request_id": "571ae02f-5c9d-436c-83c2-f221e6df0xxx"
}

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 Singapore region; base URLs are region-specific.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.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://www.alibabacloud.com/help/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}")

{
    "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
    }
}

{
    "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
    }
}

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 Singapore region; base URLs are region-specific.
    static String baseUrl = "https://{WorkspaceId}.ap-southeast-1.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://www.alibabacloud.com/help/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());
        }
    }
}

{
    "requestId": "7d026dc1-e8c9-9caa-84ac-e82e2da97xxx",
    "output": {
        "task_id": "2de18c56-c151-4b80-8105-1d164733exxx",
        "task_status": "PENDING"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

{
    "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 --location 'https://{WorkspaceId}.ap-southeast-1.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
        }
    }'

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

​

Key capabilities

​

1. Prompt following

• 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.

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

• 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_extend parameter to false.

The prompt_extend parameter is not supported by wan2.7-image-pro and wan2.7-image. To improve image quality for these models, enable thinking_mode instead. The qwen-image-3.0-pro and qwen-image-3.0 models support the prompt_extend parameter (enabled by default).

• 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). Passing agent for image-to-image/editing (I2I) returns a 400 error.

​

3. Set the output image resolution

The wan2.7-image-pro model supports 4K resolution and custom resolutions up to 40964096, 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 (20482048).

• 1664*928 (default): 16:9
• 1472*1104: 4:3
• 1328*1328: 1:1
• 1104*1472: 3:4
• 928*1664: 9:16

​

4. Image set generation

• Number of images: Controlled by the n parameter. 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 exceed n.
• Note: When image set generation is enabled, the thinking_mode and color_palette parameters are unavailable.

​

5. Thinking mode

Available only when image set generation is disabled (enable_sequential=false).

​

6. Custom color palette

Available only when image set generation is disabled (enable_sequential=false).

"color_palette": [
    {
        "hex": "#C2D1E6",
        "ratio": "23.51%"
    },
    {
        "hex": "#CDD8E9",
        "ratio": "20.13%"
    },
    {
        "hex": "#B5C8DB",
        "ratio": "15.88%"
    },
    {
        "hex": "#C0B5B4",
        "ratio": "13.27%"
    },
    {
        "hex": "#DAE0EC",
        "ratio": "10.11%"
    },
    {
        "hex": "#636574",
        "ratio": "8.93%"
    },
    {
        "hex": "#CACAD2",
        "ratio": "5.55%"
    },
    {
        "hex": "#CBD4E4",
        "ratio": "2.62%"
    }
]

​

Production deployment

• Fault tolerance
  • Handling rate limiting: When the API returns the Throttling error 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 prompt and negative_prompt inputs are subject to content moderation. If the input is non-compliant, the request is blocked and a DataInspectionFailed error 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

• Qwen - Image Generation and Editing 3.0
• Qwen-Image
• Wan2.7 - image generation and editing
• Wan2.6 - image generation and editing
• Wan - text-to-image v2
• Z-Image - text-to-image

​

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

​

FAQ