Skip to main content

Qwen Image Generation and Editing API Reference

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:

  • Text-to-image (T2I): Total pixels must be between 512*512 and 2048*2048.

  • Image-to-image (I2I): Total pixels must be between 512*512 and 2048*2048.

  • Default: When size is not specified, the model automatically recommends a resolution based on the prompt.

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.
The sample code in this topic applies to the Singapore region.
Alibaba 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.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from https://dashscope-intl.aliyuncs.com to https://{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

OpenAI-compatible

Applications already built on the OpenAI Images protocol or the OpenAI SDK. Switch base_url and model to migrate. Synchronous calls only. Image input supports both public URL and Base64.

DashScope synchronous

Recommended. Full feature coverage, including both public URL and Base64 image input.

DashScope asynchronous

Batch generation, or when you do not want to hold a connection open. Submit a task and poll for results with task_id.

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.
The 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
  • US (Virginia)
  • China (Beijing)
  • China (Hong Kong)
  • Germany (Frankfurt)
  • Japan (Tokyo)
HTTP endpoint: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generationsbase_url for SDK calls: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Replace {WorkspaceId} with your actual workspace ID.

Request parameters

Headers

Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

Request body

Unlike the DashScope protocol, the OpenAI-compatible mode places all parameters at the top level of the request body. There is no input or parameters nesting.model string (Required)The model name. Available values: qwen-image-3.0-pro, qwen-image-3.0, qwen-image-2.1-pro, and qwen-image-2.1-turbo.prompt string (Required)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 string or array (Optional)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: null and empty arrays are rejected with a 400 error.Image requirements:
  • Image format: JPG, JPEG, PNG, BMP, TIFF, WEBP, and GIF.
  • Image resolution: The width and height must be between 1 and 8000 pixels; exceeding this returns a 400 error. For best results, use 384 to 2048 pixels.
  • Aspect ratio: The ratio of the longer side to the shorter side must not exceed 10:1.
  • Image size: Up to 10 MB.
Supported input formats
  1. Public URL: HTTP and HTTPS protocols are supported.
  2. Base64 encoding: Format is data:{MIME_type};base64,{base64_data}.
n integer (Optional)The number of output images. Value range: 1 to 6. Default: 1. Must be an integer. A string value such as "1" returns a 400 error.size string (Optional)The output image resolution in the format widthxheight, for example "1024x1024". You can also pass auto. If not specified, the model automatically recommends a resolution based on the prompt.
The OpenAI protocol uses the letter x as the separator (1024x1024), not the asterisk * used by the DashScope protocol (1024*1024). Update this value when migrating from DashScope.
  • Text-to-image (T2I): Pixel area from 512x512 to 2048x2048. Aspect ratio: 1:8 to 8:1.
  • Image-to-image (I2I): Pixel area from 512x512 to 2048x2048. Aspect ratio: 1:8 to 8:1.
negative_prompt string (Optional)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 integer (Optional)The random seed. Value range: [0, 2147483647]. If omitted, the service generates a random seed. Use a fixed seed for reproducible results.prompt_extend boolean (Optional)Whether to enable intelligent prompt rewriting. Default: true (recommended). When enabled, the model optimizes the positive prompt using the method specified by prompt_extend_mode, which significantly improves results for simple descriptions.prompt_extend_mode string (Optional)The prompt rewriting method. Default: direct. Options:
  • direct: Direct Prompt Enhancement (DPE), suitable for most scenarios. Supported for both T2I and I2I.
  • agent: Agent Prompt Enhancement (APE), provides more refined rewriting. Only supports text-to-image (T2I). Passing agent for image-to-image (I2I) will return a 400 error.
enable_thinking boolean (Optional)Enables thinking mode. The default is true. This enhances model reasoning to improve image quality, but increases generation time. It requires prompt_extend=true. Supported for Direct T2I, Direct I2I, and Agent T2I. Not supported for I2I Agent.watermark boolean (Optional)Whether to add a watermark. Default: false.
image, negative_prompt, seed, prompt_extend, prompt_extend_mode, enable_thinking, and watermark are Model Studio extension fields, not official OpenAI parameters. For raw HTTP requests, place them at the top level of the request body. When using an OpenAI SDK, pass them through extra_body.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "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,
    "prompt_extend": true
}'

Response parameters

created integerThe Unix timestamp, in seconds, when the response was created.data arrayThe list of generated results. When n is greater than 1, the array contains multiple elements.

Properties

url stringThe URL of the generated image in PNG format. The link is valid for 24 hours. Download and save the image promptly.
usage objectThe resource usage of this call. Only returned on success. These are image input and output metering fields, not token usage.

Properties

  • qwen-image-3.0 series
  • qwen-image-2.1 series
output_width integerThe width of the final output image in pixels.output_height integerThe height of the final output image in pixels.input_image_count integerThe number of input images in the request. Returns 0 for text-to-image (T2I), and the actual count for image-to-image (I2I).input_image_type stringThe input image billing tier. Determined by the output resolution pixel area: qima_input_1k if area ≤ 2,250,000, or qima_input_2k if area > 2,250,000.output_image_count integerThe actual number of output images returned.output_image_type stringThe output image billing tier. Determined by the output resolution pixel area: qima_output_1k if area ≤ 2,250,000, or qima_output_2k if area > 2,250,000.
error objectThe error details. Only returned for failed requests.

Properties

message stringDetailed error message.type stringThe error type, such as invalid_request_error.param stringThe name of the parameter that caused the error, or null when the error cannot be attributed to a specific parameter.code stringError code. See Error codes.
Unlike the DashScope protocol, the OpenAI-compatible mode does not return request_id in the response body. The unique request identifier is returned in the x-request-id HTTP response header. With the OpenAI Python SDK, read response._request_id on success and APIStatusError.request_id on failure. Include this identifier when reporting an issue.
  • Success
  • Error
Image URLs are retained for only 24 hours and then automatically purged. Save generated images promptly.
{
    "created": 1788339600,
    "data": [
        {
            "url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
        }
    ],
    "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"
    }
}

SDK

Install or upgrade the OpenAI Python SDK first:
pip install -U openai
Image 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}")

HTTP

  • Singapore
  • US (Virginia)
  • China (Beijing)
  • China (Hong Kong)
  • Germany (Frankfurt)
  • Japan (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Replace {WorkspaceId} with your actual workspace ID.

Request parameters

Headers
Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
Request body
model string (Required)The model name. Available values: qwen-image-3.0-pro, qwen-image-3.0, qwen-image-2.1-pro, and qwen-image-2.1-turbo.input object (Required)The input parameter object, which contains the following fields:

Properties

messages array (Required)The request content array. Only single-round conversations are supported, so the array must contain exactly one object with role and content properties.

Properties

rolestring (Required)The role of the message sender. Must be set to user.contentarray (Required)The message content array, with different combinations depending on the use case:
  • Text-to-image (T2I): Contains only one {"text": "..."} object.
  • Image-to-image (I2I): the qwen-image-2.1 series contains 1-10 {"image": "..."} objects, the qwen-image-3.0 series contains 1-3, and 1 {"text": "..."} object.

Properties

image string (Required for I2I)The URL or Base64 encoded data of the input image. In I2I scenarios, the qwen-image-2.1 series supports 1-10 images, and the qwen-image-3.0 series supports 1-3 images. When multiple images are provided, the order is defined by the array sequence.Image requirements:
  • Image format: JPG, JPEG, PNG, BMP, TIFF, WEBP, and GIF.
  • Image resolution: The width and height must be between 1 and 8000 pixels; exceeding this returns a 400 error. For best results, use 384 to 2048 pixels.
  • Aspect ratio: The ratio of the longer side to the shorter side must not exceed 10:1.
  • Image size: Up to 10 MB.
Supported input formats
  1. Public URL: HTTP and HTTPS protocols are supported.
  2. Base64 encoding: Format is data:{MIME_type};base64,{base64_data}.
textstring(Required)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.Note: Only one text object is allowed. Omitting it or providing multiple text objects will result in an error.
parameters object (Optional)Additional parameters to control image generation.

Properties

prompt_extend boolean (Optional)Whether to enable intelligent prompt rewriting. Default: true (recommended). When enabled, the model optimizes the positive prompt using the method specified by prompt_extend_mode, which significantly improves results for simple descriptions.prompt_extend_mode string (Optional)The prompt rewriting method. Default: direct. Options:
  • direct: Direct Prompt Enhancement (DPE), suitable for most scenarios. Supported for both T2I and I2I.
  • agent: Agent Prompt Enhancement (APE), provides more refined rewriting. Only supports text-to-image (T2I). Passing agent for image-to-image (I2I) will return a 400 error.
enable_thinking boolean (Optional)Enables thinking mode. The default is true. This enhances model reasoning to improve image quality, but increases generation time. It requires prompt_extend=true. Supported for Direct T2I, Direct I2I, and Agent T2I. Not supported for I2I Agent.n integer (Optional)The number of output images. Value range: 1 to 6. Default: 1.size string (Optional)The output image resolution in the format width*height, for example "1024*1024". If not specified, the model automatically recommends a resolution based on the prompt.
  • Text-to-image (T2I): Pixel area from 512*512 to 2048*2048. Aspect ratio: 1:8 to 8:1.
  • Image-to-image (I2I): Pixel area from 512*512 to 2048*2048. Aspect ratio: 1:8 to 8:1.
negative_prompt string (Optional)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 integer (Optional)The random seed. Value range: [0, 2147483647]. If omitted, the service generates a random seed. Use a fixed seed for reproducible results.watermark boolean (Optional)Whether to add a watermark. Default: false.
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
    }
}'

Response parameters

output objectContains the model generation results.

Properties

rewrite_status stringThe prompt rewriting status. The value depends on whether rewriting was enabled in the request and the result of the rewrite.choices arrayThe list of result options.

Properties

finish_reason stringThe reason why the task stopped. The value is stop when the task completes normally.message objectThe message returned by the model.

Properties

rolestringThe role of the message. Fixed as assistant.contentarrayThe message content containing the generated image information.

Properties

image stringThe URL of the generated image in PNG format. The link is valid for 24 hours. Please download and save the image promptly.
usage objectThe resource usage of this call. Only returned on success. These are image input and output metering fields, not token usage.

Properties

  • qwen-image-3.0 series
  • qwen-image-2.1 series
output_width integerThe width of the final output image in pixels.output_height integerThe height of the final output image in pixels.input_image_count integerThe number of input images in the request. Returns 0 for text-to-image (T2I), and the actual count for image-to-image (I2I).input_image_type stringThe input image billing tier. Determined by the output resolution pixel area: qima_input_1k if area ≤ 2,250,000, or qima_input_2k if area > 2,250,000.output_image_count integerThe actual number of output images returned.output_image_type stringThe output image billing tier. Determined by the output resolution pixel area: qima_output_1k if area ≤ 2,250,000, or qima_output_2k if area > 2,250,000.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Success
  • Error
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.
{
    "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"
}

SDK

The following examples demonstrate how to call the API using Python and Java SDKs for image-to-image / image editing (I2I).
Python
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}")

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.
The 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:
  1. Create a task to get a task ID: Send a request to create a task. The response contains a task ID (task_id).
  2. 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
  • US (Virginia)
  • China (Beijing)
  • China (Hong Kong)
  • Germany (Frankfurt)
  • Japan (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Request parameters
Headers
Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. Must be enable. The endpoint in this section accepts asynchronous requests only and does not support synchronous calls.
If this request header is missing, the error "current user api does not support synchronous calls" is returned.
Request body
model string (Required)The model name. Available values: qwen-image-3.0-pro, qwen-image-3.0, qwen-image-2.1-pro, and qwen-image-2.1-turbo.input object (Required)The input parameter object, which contains the following fields:

Properties

messages array (Required)The request content array. Only single-round conversations are supported, so the array must contain exactly one object with role and content properties.

Properties

rolestring (Required)The role of the message sender. Must be set to user.contentarray (Required)The message content array, with different combinations depending on the use case:
  • Text-to-image (T2I): Contains only one {"text": "..."} object.
  • Image-to-image (I2I): the qwen-image-2.1 series contains 1-10 {"image": "..."} objects, the qwen-image-3.0 series contains 1-3, and 1 {"text": "..."} object.

Properties

image string (Required for I2I)The URL or Base64 encoded data of the input image. In I2I scenarios, the qwen-image-2.1 series supports 1-10 images, and the qwen-image-3.0 series supports 1-3 images. When multiple images are provided, the order is defined by the array sequence.Image requirements:
  • Image format: JPG, JPEG, PNG, BMP, TIFF, WEBP, and GIF.
  • Image resolution: The width and height must be between 1 and 8000 pixels; exceeding this returns a 400 error. For best results, use 384 to 2048 pixels.
  • Aspect ratio: The ratio of the longer side to the shorter side must not exceed 10:1.
  • Image size: Up to 10 MB.
Supported input formats
  1. Public URL: HTTP and HTTPS protocols are supported.
  2. Base64 encoding: Format is data:{MIME_type};base64,{base64_data}.
textstring(Required)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.Note: Only one text object is allowed. Omitting it or providing multiple text objects will result in an error.
parameters object (Optional)Additional parameters to control image generation.

Properties

prompt_extend boolean (Optional)Whether to enable intelligent prompt rewriting. Default: true (recommended). When enabled, the model optimizes the positive prompt using the method specified by prompt_extend_mode, which significantly improves results for simple descriptions.prompt_extend_mode string (Optional)The prompt rewriting method. Default: direct. Options:
  • direct: Direct Prompt Enhancement (DPE), suitable for most scenarios. Supported for both T2I and I2I.
  • agent: Agent Prompt Enhancement (APE), provides more refined rewriting. Only supports text-to-image (T2I). Passing agent for image-to-image (I2I) will return a 400 error.
enable_thinking boolean (Optional)Enables thinking mode. The default is true. This enhances model reasoning to improve image quality, but increases generation time. It requires prompt_extend=true. Supported for Direct T2I, Direct I2I, and Agent T2I. Not supported for I2I Agent.n integer (Optional)The number of output images. Value range: 1 to 6. Default: 1.size string (Optional)The output image resolution in the format width*height, for example "1024*1024". If not specified, the model automatically recommends a resolution based on the prompt.
  • Text-to-image (T2I): Pixel area from 512*512 to 2048*2048. Aspect ratio: 1:8 to 8:1.
  • Image-to-image (I2I): Pixel area from 512*512 to 2048*2048. Aspect ratio: 1:8 to 8:1.
negative_prompt string (Optional)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 integer (Optional)The random seed. Value range: [0, 2147483647]. If omitted, the service generates a random seed. Use a fixed seed for reproducible results.watermark boolean (Optional)Whether to add a watermark. Default: false.
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": "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 parameters
output objectThe task acceptance information.

Properties

task_id stringThe asynchronous task ID, used to query the task status and result. Make sure to save it.task_status stringThe task status. Usually PENDING when the task is submitted, indicating only that the task has been accepted, not that the image has been generated.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.
  • Successful response
  • Error response
Save the task_id to query the task status and result.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Step 2: Poll for results using the task ID

  • Singapore
  • US (Virginia)
  • China (Beijing)
  • China (Hong Kong)
  • Germany (Frankfurt)
  • Japan (Tokyo)
GET https://{WorkspaceId}.ap-southeast-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 parameters
Headers
Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
URL path parameters
task_id string (Required)The ID of the task.
  • Query task result
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}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
Response parameters
output objectThe task output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
State transitions during polling:
  • PENDING → RUNNING → SUCCEEDED or FAILED.
  • The initial query status is usually PENDING or RUNNING.
  • When the status changes to SUCCEEDED, the response contains the generated image URL.
  • If the status is FAILED, check the error message and retry the task.
submit_time stringThe time when the task was submitted. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.rewrite_status stringThe prompt rewriting status. The value depends on whether rewriting was enabled in the request and the result of the rewrite.choices arrayThe list of result options.

Properties

finish_reason stringThe reason why the task stopped. The value is stop when the task completes normally.message objectThe message returned by the model.

Properties

rolestringThe role of the message. Fixed as assistant.contentarrayThe message content containing the generated image information.

Properties

image stringThe URL of the generated image in PNG format. The link is valid for 24 hours. Please download and save the image promptly.
usage objectThe resource usage of this call. Only returned on success. These are image input and output metering fields, not token usage.

Properties

  • qwen-image-3.0 series
  • qwen-image-2.1 series
output_width integerThe width of the final output image in pixels.output_height integerThe height of the final output image in pixels.input_image_count integerThe number of input images in the request. Returns 0 for text-to-image (T2I), and the actual count for image-to-image (I2I).input_image_type stringThe input image billing tier. Determined by the output resolution pixel area: qima_input_1k if area ≤ 2,250,000, or qima_input_2k if area > 2,250,000.output_image_count integerThe actual number of output images returned.output_image_type stringThe output image billing tier. Determined by the output resolution pixel area: qima_output_1k if area ≤ 2,250,000, or qima_output_2k if area > 2,250,000.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Task succeeded
  • Task failed
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.
{
    "output": {
        "task_id": "17d7d840-82b9-485b-a954-724d06bc88d2",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-07 15:50:14.837",
        "scheduled_time": "2026-08-07 15:50:14.884",
        "end_time": "2026-08-07 15:50:33.607",
        "rewrite_status": "not_use",
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "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": "2bd94002-5624-9129-916b-fbdde107b4ba"
}

Error codes

If the model call fails and returns an error message, see Error codes for resolution.
Text Generation
Image Generation
Video Generation
World models
Audio
  • Audio generation
Realtime API
Text Embedding
Decision Model
TokenPlan
Model Production