Qwen-Image API reference
Qwen-Image is a general-purpose image generation model that supports multiple artistic styles and excels at complex text rendering . It handles multi-line layouts, paragraph-level text generation, and fine-grained detail rendering.
Quick access: User guide | Try it online (Beijing | Singapore) | Technical blog |
Examples
Prompt | Generated image |
|---|---|
A winter city street scene in Beijing. Two adjacent traditional Chinese shops stand side by side. One has bluish-gray tiled roofs and vermilion walls. Warm lanterns with paper-cut horse designs hang under the eaves. On an overcast day, soft diffused light casts gentle halos that reflect off the damp cobblestone pavement. To the left is a calligraphy shop. An indigo-blue aged signboard displays bold cursive script reading “Text Rendering”. A sign hangs on the shop’s glass door, written top to bottom in Tian Yingzhang’s hard-pen script: “Professional Slides, Bilingual Posters, Advanced Infographics”, with a red seal reading “1k token”. Three vertical calligraphy works hang on the shop wall: “Alibaba”, “Qwen”, and “Image Generation”. An elderly man with white hair stands with his back to the camera, viewing the display. To the right is a flower shop. Its signboard spells “Real Texture” using fresh flowers. Multi-tiered flower racks hold red roses, pink peonies, and green plants. A circular floral border label on the door reads “2k resolution”. A colorful neon sign near the entrance reads “Fine Detailing: People, Nature, Architecture”. Between the two shops sits a snowman holding an old-fashioned blackboard. Chalk on the board reads “Qwen-Image-2.0 Official Release”. On the left side of the street, a young couple leans close together. The woman has a slim face and wears an off-white cashmere coat and skin-tone tights. She holds a heart-shaped transparent balloon printed with white text: “Text-to-Image + Editing = One Tool”. Inside the balloon is a fluffy capybara plush toy. The man wears a well-tailored dark gray wool coat and a light-colored turtleneck sweater. On the right side of the street, a delivery rider speeds past, his backpack printed with “Smaller Model, Faster Speed”. Light and shadow interweave across the entire street. Motion and stillness balance each other. |
|
Model overview
| Model | Description | Output image specifications |
|---|---|---|
qwen-image-2.0-pro
| Qwen Pro series for image generation and editing. Offers stronger text rendering, realistic texture, and semantic adherence.
| Resolution: Set width and height freely. Total pixels must be between 512×512 and 2048×2048. Default resolution is 2048×2048. Format: PNG Number of images: 1–6 |
qwen-image-2.0-pro-2026-06-22 | ||
qwen-image-2.0-pro-2026-04-22 | ||
qwen-image-2.0-pro-2026-03-03 | ||
qwen-image-2.0
| Qwen accelerated series for image generation and editing. Balances quality and response speed.
| |
qwen-image-2.0-2026-03-03 |
For the models supported in each region, see the Model Studio console.
Prerequisites
Before making a call, get an API key and export the API key as an environment variable. To make calls using the SDK, install the DashScope SDK.
ImportantThe 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.
ImportantAlibaba Cloud Model Studio provides workspace-specific domains for the China (Beijing) and Singapore regions, delivering superior performance and higher stability for inference requests. We recommend migrating to the new domains:
- China (Beijing) region: migrate from
https://dashscope.aliyuncs.comtohttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore region: migrate from
https://dashscope-intl.aliyuncs.comtohttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} is your workspace ID, which you can view on the Workspace details page of the Alibaba Cloud Model Studio console. The existing domains remain available.
Synchronous API
HTTP
The Qwen image models support a synchronous API that returns results in a single request, making the call flow simple. It is recommended for most scenarios.
Beijing:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Singapore:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Replace {WorkspaceId} with your actual workspace ID.
Request parametersRequest headersContent-Type The content type of the request. This parameter must be set to Authorization Request authentication. This API authenticates requests with an Alibaba Cloud Model Studio API key. Example: Bearer sk-xxxx. Request bodymodel Model name. Example: input Basic input information. parameters Image processing parameters. | Text-to-image |
Response parametersoutput Task output information. usage Output statistics. Counts only successful results. request_id Unique request identifier. Useful for request tracing and troubleshooting. code Error code returned when the request fails. This parameter is not returned for successful requests. For details, see Error codes. message Detailed error message returned when the request fails. This parameter is not returned for successful requests. For details, see Error codes. | Task succeededImage URLs are retained for only 24 hours and are automatically purged after that. Save generated images promptly. Task failedIf the task fails for any reason, the response returns related information, and the code and message fields clearly indicate the error cause. See Error codes for resolution. |
DashScope SDK call
The DashScope SDK supports Python and Java.
The parameter names in the SDK closely match the HTTP parameters, and the parameter structures follow language-specific conventions. For synchronous call parameters, see HTTP.
Python
NoteInstall the latest DashScope Python SDK to avoid runtime errors: Install SDK.
Request example
import json
import os
import dashscope
from dashscope import MultiModalConversation
# China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'
messages = [
{
"role": "user",
"content": [
{"text": "A winter street scene in Beijing featuring two adjacent traditional Chinese shops with gray-tiled roofs and vermilion-red exterior walls standing side by side. Warm-glow lanterns adorned with paper-cut horse motifs hang beneath the eaves, casting soft halos under overcast diffused light that gently reflects off the damp cobblestone pavement. On the left is a calligraphy shop: an aged indigo signboard bears the bold running-script characters “Text Rendering.” A vertical scroll on the storefront glass reads from top to bottom in Tian Yingzhang’s hard-pen style: “Professional Slides, Bilingual Posters, Advanced Infographics,” stamped with a cinnabar seal reading “1k token.” Inside, three vertically mounted calligraphy works are faintly visible on the wall—the first says “Alibaba,” the second “Qwen,” and the third “Image Generation.” An elderly white-haired man stands with his back to the camera, admiring the art. On the right is a flower shop whose sign spells out “Realistic Texture” using fresh blooms. Multi-tiered shelves inside display red roses, pink peonies, and greenery. A circular floral-patterned badge on the door reads “2k resolution,” and a colorful neon sign at the entrance displays the text “Detailed Depiction: People, Nature, Architecture.” Between the two shops sits a snowman holding an old-fashioned chalkboard with the words “Qwen-Image-2.0 Officially Released” scrawled in chalk. On the left side of the street, a young couple leans close together—the woman has a slender face, wears a beige cashmere coat and nude-toned sheer tights, and holds a transparent heart-shaped balloon printed with white text: “Image Generation and Editing in One.” Inside the balloon is a fluffy capybara plush toy. The man wears a well-tailored dark gray wool overcoat layered over a light turtleneck sweater. On the right side of the street, a delivery rider speeds past with “Smaller Model, Faster Speed” written across his back. The entire street blends dynamic motion with serene stillness through interwoven light and shadow."}
]
}
]
# API keys differ between Beijing and Singapore regions. Get your API key: https://help.aliyun.com/en/model-studio/get-api-key
# If you haven't set the environment variable, replace the line below with: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")
response = MultiModalConversation.call(
api_key=api_key,
model="qwen-image-2.0-pro",
messages=messages,
result_format='message',
stream=False,
watermark=False,
prompt_extend=True,
negative_prompt="Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-figure appearance, lack of facial detail, excessive smoothness, AI-looking artifacts, chaotic composition, blurry or warped text.",
size='2048*2048'
)
if response.status_code == 200:
print(json.dumps(response, ensure_ascii=False))
else:
print(f"HTTP status code: {response.status_code}")
print(f"Error code: {response.code}")
print(f"Error message: {response.message}")
print("See documentation: https://help.aliyun.com/en/model-studio/developer-reference/error-code")
Response example
Image URLs expire after 24 hours. Download the images promptly.
{
"status_code": 200,
"request_id": "d2d1a8c0-325f-9b9d-8b90-xxxxxx",
"code": "",
"message": "",
"output": {
"text": null,
"finish_reason": null,
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png?Expires=xxx"
}
]
}
}
]
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"width": 2048,
"image_count": 1,
"height": 2048
}
}
Java
NoteYou must install the latest DashScope Java SDK. Otherwise, runtime errors may occur: Install SDK.
Request example
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.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.io.IOException;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
public class QwenImage {
static {
// China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
}
// API keys differ between Beijing and Singapore regions. Get your API key: https://help.aliyun.com/en/model-studio/get-api-key
// If you haven't set the environment variable, replace the line below with: static String apiKey ="sk-xxx"
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void call() throws ApiException, NoApiKeyException, UploadFileException, IOException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("text", "A winter street scene in Beijing featuring two adjacent traditional Chinese shops with gray-tiled roofs and vermilion-red exterior walls standing side by side. Warm-glow lanterns adorned with paper-cut horse motifs hang beneath the eaves, casting soft halos under overcast diffused light that gently reflects off the damp cobblestone pavement. On the left is a calligraphy shop: an aged indigo signboard bears the bold running-script characters “Text Rendering.” A vertical scroll on the storefront glass reads from top to bottom in Tian Yingzhang’s hard-pen style: “Professional Slides, Bilingual Posters, Advanced Infographics,” stamped with a cinnabar seal reading “1k token.” Inside, three vertically mounted calligraphy works are faintly visible on the wall—the first says “Alibaba,” the second “Qwen,” and the third “Image Generation.” An elderly white-haired man stands with his back to the camera, admiring the art. On the right is a flower shop whose sign spells out “Realistic Texture” using fresh blooms. Multi-tiered shelves inside display red roses, pink peonies, and greenery. A circular floral-patterned badge on the door reads “2k resolution,” and a colorful neon sign at the entrance displays the text “Detailed Depiction: People, Nature, Architecture.” Between the two shops sits a snowman holding an old-fashioned chalkboard with the words “Qwen-Image-2.0 Officially Released” scrawled in chalk. On the left side of the street, a young couple leans close together—the woman has a slender face, wears a beige cashmere coat and nude-toned sheer tights, and holds a transparent heart-shaped balloon printed with white text: “Image Generation and Editing in One.” Inside the balloon is a fluffy capybara plush toy. The man wears a well-tailored dark gray wool overcoat layered over a light turtleneck sweater. On the right side of the street, a delivery rider speeds past with “Smaller Model, Faster Speed” written across his back. The entire street blends dynamic motion with serene stillness through interwoven light and shadow.")
)).build();
Map<String, Object> parameters = new HashMap<>();
parameters.put("watermark", false);
parameters.put("prompt_extend", true);
parameters.put("negative_prompt", "Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-figure appearance, lack of facial detail, excessive smoothness, AI-looking artifacts, chaotic composition, blurry or warped text.");
parameters.put("size", "2048*2048");
MultiModalConversationParam param = MultiModalConversationParam.builder()
.apiKey(apiKey)
.model("qwen-image-2.0-pro")
.messages(Collections.singletonList(userMessage))
.parameters(parameters)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
call();
} catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
Response example
Image URLs expire after 24 hours. Download the images promptly.
{
"requestId": "5b6f2d04-b019-40db-a5cc-xxxxxx",
"usage": {
"image_count": 1,
"width": 2048,
"height": 2048
},
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png?Expires=xxx"
}
]
}
}
]
}
}
Use with the OpenAI Agents SDK
Image generation models such as Qwen-Image are called through the DashScope native API and do not support OpenAI-compatible (compatible-mode) mode, so they cannot be used directly as the reasoning model of an Agent in the OpenAI Agents SDK.
In agent frameworks such as the OpenAI Agents SDK, you can wrap image generation as a tool (function tool) and let a text chat model that supports OpenAI-compatible mode (such as qwen-plus) act as the Agent's reasoning core to orchestrate it. For example:
Before running, install the dependencies: pip install openai-agents dashscope.
import os
import asyncio
import dashscope
from openai import AsyncOpenAI
from dashscope import MultiModalConversation
from agents import Agent, Runner, function_tool, OpenAIChatCompletionsModel
# Read the Model Studio API Key from an environment variable
# (or replace with api_key="sk-xxx")
API_KEY = os.getenv("DASHSCOPE_API_KEY")
# China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
# The text chat model (the Agent's reasoning core) is accessed via OpenAI-compatible mode
client = AsyncOpenAI(api_key=API_KEY, base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1")
# Wrap image generation as a function tool for the Agent to call
@function_tool
def generate_image(prompt: str) -> str:
"""Generate an image from a text description and return its URL. prompt: the text description of the image."""
rsp = MultiModalConversation.call(
api_key=API_KEY,
model="qwen-image-2.0-pro",
messages=[{"role": "user", "content": [{"text": prompt}]}],
result_format="message",
)
if rsp.status_code != 200:
return f"Generation failed: {rsp.code} {rsp.message}"
return rsp.output.choices[0].message.content[0]["image"]
agent = Agent(
name="Image Assistant",
instructions="You are an image generation assistant. When the user wants an image, call the generate_image tool and return the image URL to the user.",
model=OpenAIChatCompletionsModel(model="qwen-plus", openai_client=client),
tools=[generate_image],
)
async def main():
result = await Runner.run(agent, "Draw a corgi running on the grass")
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())
Billing and rate limiting
- For free quotas and pricing, see Model pricing.
- For rate limits, see Qwen-Image.
- Billing details: Each successfully generated image is billed. Failed calls or processing errors do not incur charges or consume your new user free quota.
Error codes
If the model call fails and returns an error message, see Error codes for resolution.
FAQ
Q: Should I enable or disable the prompt_extend parameter?
A: Enable this option (default) if you want more diverse image content and for the model to add details. Disable it if you need tighter control over image details, and optimize your prompts using the Text-to-Image Prompt Guide.
Q: What are the differences between qwen-image-2.0 series models?
A:
-
Combined image generation and editing models: Support both text-to-image and image editing.
qwen-image-2.0-proandqwen-image-2.0-pro-2026-04-22: Same capabilities. The Pro series delivers more professional text rendering, finer realistic textures, detailed realistic scenes, and stronger semantic adherence. Supports synchronous calls only.qwen-image-2.0andqwen-image-2.0-2026-03-03: Same capabilities. The accelerated version balances model performance and quality. Supports synchronous calls only.
Q: How do I get the domain name whitelist for image storage?
A: Images generated by models are stored in Alibaba Cloud OSS. The API returns a temporary public URL (valid for 24 hours; download and save it promptly). The image URL domain format is dashscope-{marker}.oss-accelerate.aliyuncs.com or dashscope-{marker}.oss-cn-{region}.aliyuncs.com. If you need to configure a firewall whitelist for the download address, note the following: because the underlying storage changes dynamically, the bucket names below are for reference only and may change at any time: dashscope-a717, dashscope-66f3, dashscope-7c2c, dashscope-2522, dashscope-c72b, dashscope-0484, dashscope-7e0f, dashscope-5859, dashscope-5496, dashscope-35f9, dashscope-31d9, dashscope-7f1f, dashscope-cc75, dashscope-64e9. To prevent outdated information from affecting access, this document does not provide a fixed OSS domain whitelist. If you have security control requirements, contact your account manager to obtain the latest OSS domain list. The API currently returns URLs only and does not support base64 output.
