All Products
Search

This Product

    Alibaba Cloud Model Studio:Qwen Image Generation and Editing 3.0 API Reference

    Document Center

    Alibaba Cloud Model Studio:Qwen Image Generation and Editing 3.0 API Reference

    Last Updated:Jul 20, 2026

    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.

    Important

    This model is currently in limited preview. Apply for access on the Model Gallery before use.

    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

    Prerequisites

    Before making a call, get an API key and export the API key as an environment variable.

    To call the API using the SDK, install the DashScope SDK. The SDK is available for Python and Java.

    Important

    The China (Beijing) and Singapore regions have separate API keys and request endpoints. They cannot be used interchangeably. Cross-region calls lead to authentication failures or service errors.

    Important

    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.

    HTTP

    Singapore region: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

    China (Beijing) region: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

    Replace {WorkspaceId} with your actual Workspace ID.

    Request parameters

    Text-to-image (T2I)

    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
    }
}'

    Image-to-image / Image editing (I2I)

    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": [
                    {
                        "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
                    },
                    {
                        "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. She changes from her beige knit top into an elegant urban professional outfit: a champagne silk blouse with a well-tailored dark grey casual blazer and matching high-waisted wide-leg trousers. The scene is in a modern minimalist upscale coffee shop with floor-to-ceiling windows showing a bustling city view. Dark wood tables and leather chairs furnish the interior, with a silver laptop, documents, and a steaming Americano on the table. She sits relaxed, leaning slightly back with one arm on the armrest and the other holding a coffee cup, gazing at the camera with calm, slightly languid eyes and an elegant smile. Polished formal makeup with clean base, defined brows, and mauve lipstick. Soft afternoon light enters from the side through the windows, creating delicate light transitions on her face and clothing. Natural bokeh background in earth tones, greys and warm whites, creating a serene, sophisticated urban office atmosphere."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'
    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. The currently available model is qwen-image-3.0-pro.

    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.

    content array (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): Contains 1-3 {"image": "..."} objects and 1 {"text": "..."} object.

    Properties

    image string (Optional)

    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:

    • Image format: JPG, JPEG, PNG, BMP, TIFF, WEBP, and GIF.

    • Image resolution: The width and height should be between 384 and 2048 pixels for best results.

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

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

    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, which significantly improves results for simple descriptions.

    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 range from 512*512 to 2048*2048.

    • Image-to-image (I2I): Pixel range from 512*512 to 2048*2048.

    negative_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]. A fixed seed helps maintain relatively stable results.

    watermark boolean (Optional)

    Whether to add a watermark. Default: false.

    Response parameters

    Success

    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": {
        "width": 1024,
        "height": 1024,
        "image_count": 1
    },
    "request_id": "571ae02f-5c9d-436c-83c2-f221e6df0xxx"
}

    Error

    If the task fails, the response includes the error code and message. See Error codes for troubleshooting.

    {
    "request_id": "31f808fd-8eef-9004-xxxxx",
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided."
}

    output object

    Contains the model generation results.

    Properties

    choices array

    The list of result options.

    Properties

    finish_reason string

    The reason why the task stopped. The value is stop when the task completes normally.

    message object

    The message returned by the model.

    Properties

    role string

    The role of the message. Fixed as assistant.

    content array

    The message content containing the generated image information.

    Properties

    image string

    The URL of the generated image in PNG format. The link is valid for 24 hours. Please download and save the image promptly.

    usage object

    The resource usage of this call. Only returned on success.

    Properties

    width integer

    The width of the generated image in pixels.

    height integer

    The height of the generated image in pixels.

    image_count integer

    The number of generated images.

    request_id string

    Unique request identifier for tracing and troubleshooting.

    code string

    Error code. Returned only for failed requests. See Error codes.

    message string

    Detailed error message. Returned only for failed requests. See Error codes.

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

    Java

    import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
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";

        // [Method 1] Use a public image URL
        String imageUrl = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png";

        // [Method 2] Use a Base64-encoded image
        // String imageUrl = encodeFile("/path/to/your/image.png");

        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage userMessage = MultiModalMessage.builder()
            .role(Role.USER.getValue())
            .content(Arrays.asList(
                Collections.singletonMap("image", imageUrl),
                Collections.singletonMap("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.")
            ))
            .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();
        }
    }

    public static String encodeFile(String filePath) {
        Path path = Paths.get(filePath);
        if (!Files.exists(path)) {
            throw new IllegalArgumentException("File does not exist: " + filePath);
        }
        String mimeType = null;
        try {
            mimeType = Files.probeContentType(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot detect file type: " + filePath);
        }
        if (mimeType == null || !mimeType.startsWith("image/")) {
            throw new IllegalArgumentException("Unsupported or unrecognized image format");
        }
        byte[] fileBytes = null;
        try {
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot read file content: " + filePath);
        }
        String encodedString = Base64.getEncoder().encodeToString(fileBytes);
        return "data:" + mimeType + ";base64," + encodedString;
    }
}

    Error codes

    If the model call fails and returns an error message, see Error codes for resolution.