The Qwen Image Generation and Editing 3.0 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 1-3 reference images combined with editing instructions.
Model overview
Model | Description | Output image specifications |
|---|---|---|
qwen-image-3.0-pro | Qwen Image Generation and Editing 3.0 model that supports both text-to-image (T2I) and image-to-image/image editing (I2I). | Image resolution:
Image format: PNG |
qwen-image-3.0 | Qwen Image Generation and Editing 3.0 standard model that supports both text-to-image (T2I) and image-to-image/image editing (I2I). Balances quality and speed. |
Availability
The model, endpoint URL, and API key must belong to the same region. Cross-region calls fail.
- Select a model: Verify that the model is available in your target region.
- Select a URL: Choose the endpoint URL that matches your model's region. Both HTTP and DashScope SDK URLs are supported.
- Configure an API key: Get an API key for the region, and then configure the API key as an environment variable.
- Install the SDK: To make API calls with the SDK, install the DashScope SDK.
Synchronous API (recommended)
HTTP
- Singapore
- 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{WorkspaceId} with your actual workspace ID.
Request parametersHeadersContent-Typestring (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 bodymodelstring (Required)The model name. Available values: qwen-image-3.0-pro and qwen-image-3.0.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 role string (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:
Properties image string (Required for I2I)The URL or Base64 encoded data of the input image. In I2I scenarios, 1-3 images are supported. When multiple images are provided, the order is defined by the array sequence.Image requirements:
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.Note: Only one text object is allowed. Omitting it or providing multiple text objects will result in an error.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:
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.
string (Optional)The negative prompt that describes content you do not want to appear in the image.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. |
Response parametersoutputobjectContains 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 role stringThe 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.objectThe resource usage of this call. Only returned on success.
Properties 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.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 data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. |
SDK
The following examples demonstrate how to call the API using Python and Java SDKs for image-to-image / image editing (I2I).
Asynchronous API
In addition to the synchronous call described above, Qwen Image Generation and Editing 3.0 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.
HTTP
Asynchronous calls use a two-step workflow:
- Create a task to get a task ID: Send a request to create a task. The response contains a task ID (task_id).
- Poll for results using the task ID: Use the task_id to poll the task status until the task completes and the image URL is returned.
Step 1: Create a task to get a task ID
- Singapore
- China (Beijing)
- China (Hong Kong)
- Germany (Frankfurt)
- Japan (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generationRequest parametersHeadersContent-Typestring (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. HTTP requests support only asynchronous calls. Must be enable.Request bodymodelstring (Required)The model name. Available values: qwen-image-3.0-pro and qwen-image-3.0.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 role string (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:
Properties image string (Required for I2I)The URL or Base64 encoded data of the input image. In I2I scenarios, 1-3 images are supported. When multiple images are provided, the order is defined by the array sequence.Image requirements:
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.Note: Only one text object is allowed. Omitting it or providing multiple text objects will result in an error.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:
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.
string (Optional)The negative prompt that describes content you do not want to appear in the image.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. |
Response parametersoutputobjectThe 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.stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes. |
Save the task_id to query the task status and result. |
Step 2: Poll for results using the task ID
- Singapore
- China (Beijing)
- China (Hong Kong)
- Germany (Frankfurt)
- Japan (Tokyo)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Request parametersHeadersAuthorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.URL path parameterstask_idstring (Required)The ID of the task. |
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. |
Response parametersoutputobjectThe task output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
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 role stringThe 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.objectThe resource usage of this call. Only returned on success.
Properties 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.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 data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. |