Appearance
Wan text-to-image V2 API reference
The Wan text-to-image model generates images from text prompts, supporting artistic styles and realistic photographic effects. Quick links: Try online (Singapore | Virginia | Beijing) | Wan official website Note
Wan website features may differ from API capabilities. This document covers the API and is updated as changes occur.
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. Important
The Singapore, Virginia, and Beijing regions have separate API keys and request endpoints . They cannot be used interchangeably. Cross-region calls lead to authentication failures or service errors. For more information, see Select a region and service deployment scope.
HTTP synchronous (wan2.6)
Important
The API in this section uses the new protocol and supports only the wan2.6 model. Retrieve the result in a single request. Recommended for most use cases.
Singapore
POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Virginia
POST https://dashscope-us.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Beijing
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
The global deployment scope (Frankfurt region) supports only asynchronous calls .
Request parameters
## Text-to-image
curl
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \\
--header 'Content-Type: application/json' \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \\
--data '{
"model": "wan2.6-t2i",
"input": {
"messages": \[
{
"role": "user",
"content": \[
{
"text": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
}
\]
}
\]
},
"parameters": {
"prompt_extend": true,
"watermark": false,
"n": 1,
"negative_prompt": "",
"size": "1280*1280"
}
}'Request 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. Example: wan2.6-t2i.
**
**Note ** For wan2.5 and earlier models, see HTTP asynchronous call for HTTP calls.
input *object* (Required) The input object. Properties
messages *array* (Required) The request messages. Currently, only single-turn conversations are supported: pass one set of role and content parameters. Properties
role *string* (Required) The message role. Must be set to user.
content *array* (Required) The message content array. Properties
text *string*** (Required)** The positive prompt describing the desired content, style, and composition of the generated image. Supports Chinese and English, with a maximum length of 2,100 characters. Each Chinese character, letter, number, or symbol counts as one character. Excess characters are automatically truncated. Example: A sitting orange cat, happy, lively, and cute, realistic and accurate. Note: Only one text input is supported. An error will occur if you do not provide a text input or if you provide multiple text inputs.
parameters *object* (Optional) Image generation parameters. Properties
negative_prompt *string* (optional) A negative prompt describing what you do not want in the image. Supports Chinese and English. Maximum length is 500 characters. Excess characters are truncated automatically. Example: Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-like appearance, no facial details, overly smooth surfaces, AI-generated look. Chaotic composition. Blurry or distorted text.
size *string* (Optional) The resolution of the output image, in the format **width*height**.
The default value is
1280*1280.The total pixels must be between 1280×1280 and 1440×1440, with an aspect ratio between 1:4 and 4:1. For example, 768×2700 is a valid resolution. Example: 1280*1280. Recommended resolutions for common aspect ratios
1:1: 1280×1280
3:4: 1104×1472
4:3: 1472×1104
9:16: 960×1696
16:9: 1696×960
n *integer* (Optional)
**
**Important ** The value of n directly affects the cost. Cost = Unit Price × Number of Images. Before you call the API, confirm the model pricing.
The number of images to generate. The value must be an integer from 1 to 4. The default is 4. Billing is based on the number of images generated. Set to 1 for testing.
prompt_extend *bool* (Optional) Enables prompt rewriting. An LLM optimizes the positive prompt to improve results, especially for shorter prompts. Adds 3-4 seconds to processing time.
- true (default)
- false
watermark *bool* (Optional) Adds an "AI Generated" watermark to the lower-right corner of the image.
- false (default)
- true
seed *integer* (optional) Random number seed. Valid range: \[0,2147483647\]. Using the same seed yields similar outputs. If omitted, the algorithm uses a random seed. Note: Image generation is probabilistic. Even with the same seed, results may vary.
Response parameters
## Successful task execution
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.
json
{
"output": {
"choices": \[
{
"finish_reason": "stop",
"message": {
"content": \[
{
"image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxx.png?Expires=xxx",
"type": "image"
}
\],
"role": "assistant"
}
}
\],
"finished": true
},
"usage": {
"image_count": 1,
"input_tokens": 0,
"output_tokens": 0,
"size": "1280*1280",
"total_tokens": 0
},
"request_id": "815505c6-7c3d-49d7-b197-xxxxx"
}## Task execution failed
If the task fails, the API returns error information. Identify the cause from the code and message fields. See Error messages.
json
{
"request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
"code": "InvalidParameter",
"message": "num_images_per_prompt must be 1"
} **output** `*object*` The output object.
Properties
choices *array* The output content generated by the model. Properties
finish_reason *string* The reason the task stopped. stop indicates normal completion.
message *object* The message returned by the model. Properties
role *string* The message role, fixed as assistant.
content *array*Properties
image *string* The URL of the generated image in PNG format. Valid for 24 hours. Download and save the image promptly.
type *string* The output type, fixed as image.
finished *boolean* Whether the task has finished.
- true
- false
usage *object* Usage statistics for the request. Only successful results are counted. Properties
image_count *integer* The number of generated images.
size *string* The resolution of the generated image. Example: 1280*1280.
input_tokens *integer* The number of input tokens. For text-to-image, billing is based on the number of images, so this value is fixed at 0.
output_tokens *integer* The number of output tokens. For text-to-image, billing is based on the number of images, so this value is fixed at 0.
total_tokens *integer* The total number of tokens. For text-to-image, billing is based on the number of images, so this value is fixed at 0.
request_id *string* Unique request identifier for tracing and troubleshooting.
code *string* Error code. Returned only for failed requests. See Error messages.
message *string* Detailed error message. Returned only for failed requests. See Error messages.
HTTP asynchronous (wan2.6)
Important
The API in this section uses the new protocol and supports only the wan2.6 model. The task flow includes two core steps: Create task -> Poll for result. The process is as follows:
Step 1: Create a task and get the task ID
Singapore
POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Virginia
POST https://dashscope-us.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Beijing
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image-generation/generation
Frankfurt
POST https://++<u>{WorkspaceId}.eu-central-1.maas.aliyuncs.com</u>++/api/v1/services/aigc/image-generation/generation
When you make a call, replace WorkspaceId with your Workspace ID. Note
After the task is created, use the returned
task_idto query the result. Thetask_idis valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.For guidance for beginners, see Postman.
Request parameters
## Text-to-image
curl
curl --location 'https://dashscope-intl.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.6-t2i",
"input": {
"messages": \[
{
"role": "user",
"content": \[
{
"text": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
}
\]
}
\]
},
"parameters": {
"prompt_extend": true,
"watermark": false,
"n": 1,
"negative_prompt": "",
"size": "1280*1280"
}
}'Request 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. HTTP requests support only asynchronous calls. Must be enable.
**
**Important ** 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. Example: wan2.6-t2i.
**
**Note ** For wan2.5 and earlier models, see HTTP asynchronous call.
input *object* (Required) The input object. Properties
messages *array* (Required) The request messages. Currently, only single-turn conversations are supported: pass one set of role and content parameters. Properties
role *string* (Required) The message role. Must be set to user.
content *array* (Required) The message content array. Properties
text *string*** (Required)** The positive prompt describing the desired content, style, and composition of the generated image. Supports Chinese and English, with a maximum length of 2,100 characters. Each Chinese character, letter, number, or symbol counts as one character. Excess characters are automatically truncated. Example: A flower shop with exquisite windows, a beautiful wooden door, and flowers on display. Note: Only one text input is supported. An error will occur if you do not provide a text input or if you provide multiple text inputs.
parameters *object* (Optional) Image generation parameters. Properties
negative_prompt *string* (optional) A negative prompt describing what you do not want in the image. Supports Chinese and English. Maximum length is 500 characters. Excess characters are truncated automatically. Example: Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-like appearance, no facial details, overly smooth surfaces, AI-generated look. Chaotic composition. Blurry or distorted text.
size *string* (Optional) The resolution of the output image, in the format **width*height**.
The default value is
1280*1280.The total pixels must be between 1280×1280 and 1440×1440, with an aspect ratio between 1:4 and 4:1. For example, 768×2700 is a valid resolution. Example: 1280*1280. Recommended resolutions for common aspect ratios
1:1: 1280×1280
3:4: 1104×1472
4:3: 1472×1104
9:16: 960×1696
16:9: 1696×960
n *integer* (Optional)
**
**Important ** The value of n directly affects the cost. Cost = Unit Price × Number of Images. Before you call the API, confirm the model pricing.
The number of images to generate. The value must be an integer from 1 to 4. The default is 4. Billing is based on the number of images generated. Set to 1 for testing.
prompt_extend *bool* (Optional) Enables prompt rewriting. An LLM optimizes the positive prompt to improve results, especially for shorter prompts. Adds 3-4 seconds to processing time.
- true (default)
- false
watermark *bool* (Optional) Adds an "AI Generated" watermark to the lower-right corner of the image.
- false (default)
- true
seed *integer* (optional) Random number seed. Valid range: \[0,2147483647\]. Using the same seed yields similar outputs. If omitted, the algorithm uses a random seed. Note: Image generation is probabilistic. Even with the same seed, results may vary.
Response parameters
Successful response
Save the task_id to query the task status and result.
json
{
"output": {
"task_status": "PENDING",
"task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
},
"request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}Error response
Task creation failed. See Error messages.
json
{
"code": "InvalidApiKey",
"message": "No API-key provided.",
"request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
} **output** `*object*` The output object.
Properties
task_id *string* The task ID. Valid for queries for 24 hours.
task_status *string* The status of the task. Enumeration values
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN: The task does not exist or its status is unknown.
request_id *string* Unique request identifier for tracing and troubleshooting.
code *string* Error code. Returned only for failed requests. See Error messages.
message *string* Detailed error message. Returned only for failed requests. See Error messages.
Step 2: Query the result by task ID
Singapore
GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}
Virginia
GET https://dashscope-us.aliyuncs.com/api/v1/tasks/{task_id}
Beijing
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
Frankfurt
GET https://++{WorkspaceId}.eu-central-1.maas.aliyuncs.com++/api/v1/tasks/{task_id}
When you make a call, replace {WorkspaceId} with your actual Workspace ID. Note
Polling recommendation: Image generation is time-consuming. Use a polling mechanism with a reasonable interval, such as 10 seconds.
Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
Result link : After a task succeeds, an image URL valid for 24 hours is returned. Download and save the image to permanent storage, such as OSS.
Request parameters
## 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.
curl
curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY"Request 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.
Response parameters
## Successful task execution
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.
json
{
"request_id": "2ddf53fa-699a-4267-9446-xxxxxx",
"output": {
"task_id": "3cd3fa4e-53ee-4136-9cab-xxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2025-12-18 20:03:01.802",
"scheduled_time": "2025-12-18 20:03:01.834",
"end_time": "2025-12-18 20:03:29.260",
"finished": true,
"choices": \[
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": \[
{
"image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx",
"type": "image"
}
\]
}
}
\]
},
"usage": {
"size": "1280*1280",
"total_tokens": 0,
"image_count": 1,
"output_tokens": 0,
"input_tokens": 0
}
}## Task execution failed
If the task fails, the API returns error information. Identify the cause from the code and message fields. See Error messages.
json
{
"code": "InvalidApiKey",
"message": "No API-key provided.",
"request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
} **output** `*object*` The task output information.
Properties
task_id *string* The task ID. Valid for queries for 24 hours.
task_status *string* The 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 *string* The 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 *string* The 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 *string* The time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.
finished *boolean* Indicates whether the task is finished.
- true
- false
choices *array* The output content generated by the model. Properties
finish_reason *string* The reason the task stopped. stop indicates normal completion.
message *object* The message returned by the model. Properties
role *string* The role of the message, which is fixed as assistant.
content *array*Properties
image *string* The URL of the generated image in PNG format. The link is valid for 24 hours. You must download and save the image promptly.
type *string* The type of output, which is fixed as image.
usage *object* Usage statistics for the request. Only successful results are counted.Properties
image_count *integer* The number of generated images.
size *string* The resolution of the generated image. Example: 1280*1280.
input_tokens *integer* The number of input tokens. This value is currently fixed at 0.
output_tokens *integer* The number of output tokens. This value is currently fixed at 0.
total_tokens *integer* The total number of tokens. This value is currently fixed at 0.
request_id *string* Unique request identifier for tracing and troubleshooting.
code *string* Error code. Returned only for failed requests. See Error messages.
message *string* Detailed error message. Returned only for failed requests. See Error messages.
HTTP asynchronous (wan2.5 and earlier models)
Important
This API uses the old protocol and supports only wan2.5 and earlier models. Because text-to-image tasks can take significant time (typically 1 to 2 minutes), the API uses an asynchronous call. The flow includes two core steps: Create task -> Poll for result. The process is as follows:
Processing time depends on the task queue and service status.
Step 1: Create a task and get the task ID
Singapore
POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
Beijing
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesisNote
After the task is created, use the returned
task_idto query the result. Thetask_idis valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.For guidance for beginners, see Postman.
Request parameters
## Text-to-image
** The API keys for the Singapore and Beijing regions are different. Create an API key The following is the URL for the Singapore region. If you are using a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
curl
curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \\
-H 'X-DashScope-Async: enable' \\
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \\
-H 'Content-Type: application/json' \\
-d '{
"model": "wan2.5-t2i-preview",
"input": {
"prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"
},
"parameters": {
"size": "1280*1280",
"n": 1
}
}'## Text-to-image (with negative prompt)
Use negative_prompt to prevent "people" from appearing in the generated image. The API keys for the Singapore and Beijing regions are different. Create an API key The following is the URL for the Singapore region. If you are using a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
curl
curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \\
-H 'X-DashScope-Async: enable' \\
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \\
-H 'Content-Type: application/json' \\
-d '{
"model": "wan2.2-t2i-flash",
"input": {
"prompt": "Snowy ground, a small white chapel, aurora borealis, winter scene, soft light.",
"negative_prompt": "people"
},
"parameters": {
"size": "1024*1024",
"n": 1
}
}'Request headers
<b>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. HTTP requests support only asynchronous calls. Must be enable.
**
**Important ** 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. For text-to-image models, see Model List. Example: wan2.5-t2i-preview.
**
**Note ** For HTTP calls to the wan2.6 model, see HTTP synchronous call and HTTP asynchronous call.
input *object* (Required) The input object containing the prompt. Properties
prompt *string* (Required) The positive prompt describing the desired content and style of the generated image. This parameter supports Chinese and English. Each Chinese character, letter, or punctuation mark counts as one character. Excess characters are automatically truncated. The length limit varies by model version:
- wan2.5-t2i-preview: Maximum length of 2000 characters.
- wan2.2 and wan2.1 series models: Maximum length of 500 characters.
- wanx2.0-t2i-turbo: Maximum length of 800 characters. Example: A sitting orange cat, happy, lively, and cute, realistic and accurate. For tips on using prompts, see Text-to-image Prompt Guide.
negative_prompt *string* (Optional) The negative prompt specifying content to exclude from the image. Use this to constrain the output. This parameter supports Chinese and English, with a maximum length of 500 characters. Excess characters are automatically truncated. Example: low resolution, error, worst quality, low quality, mutilated, extra fingers, bad proportions, etc.
parameters *object* (Optional) The image generation parameters. Properties
size *string* (Optional) The resolution of the output image, in the format **width*height**. The default value and constraints vary by model version:
wan2.5-t2i-preview: The default value is
1280*1280. The total pixels must be between 1280×1280 and 1440×1440, with an aspect ratio between 1:4 and 4:1. For example, 768×2700 is a valid resolution.wan2.2 and earlier models: The default value is
1024*1024. The image width and height must be between 512 and 1440, with a maximum resolution of 1440×1440. For example, 768×2700 exceeds the single-side limit and is not supported. Example: 1280*1280. Recommended resolutions for common aspect ratios The following resolutions apply to wan2.5-t2i-preview:1:1: 1280×1280
3:4: 1104×1472
4:3 (1472 × 1104)
9:16: 960×1696
16:9: 1696×960
n *integer* (Optional)
**
**Important ** The value of n directly affects the cost. Cost = Unit Price × Number of Images. Before you call the API, confirm the model pricing.
The number of images to generate. The value must be an integer from 1 to 4. The default is 4. Set to 1 for testing.
prompt_extend *boolean* (Optional) Enables prompt rewriting. An LLM rewrites the input prompt to improve results, especially for shorter prompts. Increases processing time.
- true (default)
- false
watermark *boolean* (Optional) Adds an "AI Generated" watermark to the lower-right corner of the image.
- false (default)
- true
seed *integer* (optional) Random number seed. Valid range: \[0,2147483647\]. Using the same seed yields similar outputs. If omitted, the algorithm uses a random seed. Note: Image generation is probabilistic. Even with the same seed, results may vary.
Response parameters
## Successful response
Save the task_id to query the task status and result.
json
{
"output": {
"task_status": "PENDING",
"task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
},
"request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}## Error response
Task creation failed. See Error messages.
json
{
"code": "InvalidApiKey",
"message": "No API-key provided.",
"request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
} **output** `*object*` The task output information.
Properties
task_id *string* The task ID. Valid for queries for 24 hours.
task_status *string* The status of the task. Enumeration values
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN: The task does not exist or its status is unknown.
request_id *string* Unique request identifier for tracing and troubleshooting.
code *string* Error code. Returned only for failed requests. See Error messages.
message *string* Detailed error message. Returned only for failed requests. See Error messages.
Step 2: Query the result by task ID
Singapore
GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}
Beijing
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}Note
Polling recommendation: Image generation is time-consuming. Use a polling mechanism with a reasonable interval, such as 10 seconds.
Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
Result link : After a task succeeds, an image URL valid for 24 hours is returned. Download and save the image to permanent storage, such as OSS.
Request parameters
## Query task result
Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task_id. ** API keys are different for each region. For more information, see Create an API key. If you use a model in the Beijing region, replace base_url with https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx.
curl
curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY"<b>Request 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.
Response parameters
## Successful task execution
Image URLs are valid for only 24 hours and then automatically purged. Save generated images promptly.
json
{
"request_id": "f767d108-7d50-908b-a6d9-xxxxxx",
"output": {
"task_id": "d492bffd-10b5-4169-b639-xxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2025-01-08 16:03:59.840",
"scheduled_time": "2025-01-08 16:03:59.863",
"end_time": "2025-01-08 16:04:10.660",
"results": \[
{
"orig_prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
"actual_prompt": "A flower shop with exquisitely carved windows and a beautiful dark wooden door with a brass handle. Inside, various flowers are displayed, including roses, lilies, and sunflowers, which are colorful and vibrant. The background is a warm indoor scene, with light visible from the street through the window. High-definition realistic photography, medium shot composition.",
"url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png"
}
\],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
}
},
"usage": {
"image_count": 1
}
}## Task failed
When a task fails, task_status is FAILED with an error code and message. See Error messages.
json
{
"request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
"output": {
"task_id": "86ecf553-d340-4e21-af6e-xxxxxx",
"task_status": "FAILED",
"code": "InvalidParameter",
"message": "xxxxxx",
"task_metrics": {
"TOTAL": 4,
"SUCCEEDED": 0,
"FAILED": 4
}
}
}## Partial task failure
The model can generate multiple images per task. If at least one succeeds, the task status is SUCCEEDED and URLs of successful images are returned. Failed images include a failure reason. Usage statistics count only successful results. See Error messages.
json
{
"request_id": "85eaba38-0185-99d7-8d16-xxxxxx",
"output": {
"task_id": "86ecf553-d340-4e21-af6e-xxxxxx",
"task_status": "SUCCEEDED",
"results": \[
{
"url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png"
},
{
"code": "InternalError.Timeout",
"message": "An internal timeout error has occurred during execution, please try again later or contact service support."
}
\],
"task_metrics": {
"TOTAL": 2,
"SUCCEEDED": 1,
"FAILED": 1
}
},
"usage": {
"image_count": 1
}
}## Task query expired
The task_id is valid for 24 hours. After this period, queries return the following error.
json
{
"request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
"output": {
"task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
"task_status": "UNKNOWN"
}
} **output** `*object*`* * The task output information.
Properties
task_id *string* The task ID. Valid for queries for 24 hours.
task_status *string* The 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 *string* The 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 *string* The 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 *string* The time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.
results *array of object* A list of task results. This includes image URLs, prompts, and error messages for partially failed tasks. Data structure
json
{
"results": \[
{
"orig_prompt": "",
"actual_prompt": "",
"url": ""
},
{
"code": "",
"message": ""
}
\]
}Properties
orig_prompt *string* The original input prompt, corresponding to the request parameter prompt.
actual_prompt *string* The optimized prompt used when prompt rewriting is enabled. Not returned when disabled.
url *string* The image URL. This is returned only when task_status is SUCCEEDED. The link is valid for 24 hours and can be used to download the image.
code *string* Error code. Returned only for failed requests. See Error messages.
message *string* Detailed error message. Returned only for failed requests. See Error messages.
task_metrics *object* Statistics for the task result. Properties
TOTAL *integer* The total number of tasks.
SUCCEEDED *integer* The number of successful tasks.
FAILED *integer* The number of failed tasks.
code *string* Error code. Returned only for failed requests. See Error messages.
message *string* Detailed error message. Returned only for failed requests. See Error messages.
usage *object* Usage statistics for the request. Only successful results are counted. Properties
image_count *integer* Number of images successfully generated. Billing: Cost = Number of images × Unit price.
request_id *string* Unique request identifier for tracing and troubleshooting.
DashScope Python SDK
The SDK parameter names align with the HTTP API, with structures adapted for Python.
Because text-to-image tasks can take significant time, the SDK encapsulates the HTTP asynchronous call process and supports both synchronous and asynchronous calls.
Processing time depends on the task queue and service status.
wan2.6
Important
The following code is only for the wan2.6 model.
Make sure your DashScope Python SDK version is at least 1.25.7 before you run the following code. To update, see Install the SDK.
The base_url and API key are region-specific. The following example shows a call in the Singapore region:
Singapore
https://dashscope-intl.aliyuncs.com/api/v1
Virginia
https://dashscope-us.aliyuncs.com/api/v1
Beijing
https://dashscope.aliyuncs.com/api/v1
Frankfurt
https://++{WorkspaceId}.eu-central-1.maas.aliyuncs.com++/api/v1
Replace WorkspaceId with your actual Workspace ID.
The global deployment scope (Frankfurt region) supports only asynchronous calls.
Synchronous call
Request example
HELPCODEESCAPE-python
import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key is region-specific. To obtain an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
message = Message(
role="user",
content=[
{
'text': 'A flower shop with exquisite windows, a beautiful wooden door, and flowers on display'
}
]
)
print("----Sync call, please wait a moment----")
rsp = ImageGeneration.call(
model="wan2.6-t2i",
api_key=api_key,
messages=[message],
negative_prompt="",
prompt_extend=True,
watermark=False,
n=1,
size="1280*1280"
)
print(rsp)Response example
The URL is valid for 24 hours. You must download the image promptly.
HELPCODEESCAPE-json
{
"status_code": 200,
"request_id": "820dd0db-eb42-4e05-8d6a-1ddb4axxxxxx",
"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,
"finished": true
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"characters": 0,
"image_count": 1,
"size": "1280*1280",
"total_tokens": 0
}
}Asynchronous call
Request example
HELPCODEESCAPE-python
import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Role, Message
from http import HTTPStatus
# The following is the base_url for the Singapore region. The base_url is region-specific.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key is region-specific. To obtain an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
# Create an asynchronous task
def create_async_task():
print("Creating async task...")
message = Message(
role="user",
content=[{'text': 'A flower shop with exquisite windows, a beautiful wooden door, and flowers on display'}]
)
response = ImageGeneration.async_call(
model="wan2.6-t2i",
api_key=api_key,
messages=[message],
negative_prompt="",
prompt_extend=True,
watermark=False,
n=1,
size="1280*1280"
)
if response.status_code == 200:
print("Task created successfully:", response)
return response
else:
raise Exception(f"Failed to create task: {response.code} - {response.message}")
# Wait for the task to complete
def wait_for_completion(task_response):
print("Waiting for task completion...")
status = ImageGeneration.wait(task=task_response, api_key=api_key)
if status.output.task_status == "SUCCEEDED":
print("Task succeeded!")
print("Response:", status)
else:
raise Exception(f"Task failed with status: {status.output.task_status}")
# Fetch asynchronous task information
def fetch_task_status(task):
print("Fetching task status...")
status = ImageGeneration.fetch(task=task, api_key=api_key)
if status.status_code == HTTPStatus.OK:
print("Task status:", status.output.task_status)
print("Response details:", status)
else:
print(f"Failed to fetch status: {status.code} - {status.message}")
# Cancel the asynchronous task
def cancel_task(task):
print("Canceling task...")
response = ImageGeneration.cancel(task=task, api_key=api_key)
if response.status_code == HTTPStatus.OK:
print("Task canceled successfully:", response.output.task_status)
else:
print(f"Failed to cancel task: {response.code} - {response.message}")
# Main execution flow
if __name__ == "__main__":
task = create_async_task()
wait_for_completion(task)Response example
Response example for creating a task
HELPCODEESCAPE-json { "status_code": 200, "request_id": "c4f11410-ea42-4996-957d-9c82f9xxxxxx", "code": "", "message": "", "output": { "text": null, "finish_reason": null, "choices": null, "audio": null, "task_id": "f470bbfd-d955-4165-935b-d35b8eexxxxxx", "task_status": "PENDING" }, "usage": { "input_tokens": 0, "output_tokens": 0, "characters": 0 } }Response example for querying a task result
The URL is valid for 24 hours. You must download the image promptly.
HELPCODEESCAPE-json { "status_code": 200, "request_id": "7e57e7e8-00b0-4534-9aff-fe31e0xxxxxx", "code": null, "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": "f470bbfd-d955-4165-935b-d35b8exxxxxx", "task_status": "SUCCEEDED", "submit_time": "2026-01-09 17:18:17.901", "scheduled_time": "2026-01-09 17:18:17.941", "end_time": "2026-01-09 17:18:45.544", "finished": true }, "usage": { "input_tokens": 0, "output_tokens": 0, "characters": 0, "size": "1280*1280", "total_tokens": 0, "image_count": 1 } }
wan2.5 and earlier models
Important
The following code is only for wan2.5 and earlier models.
Make sure your DashScope Python SDK version is at least 1.25.2 before you run the following code.
If the version is too low, errors such as "url error, please check url!" may occur. To update, see Install the SDK.
The base_url and API key are region-specific. The following example shows a call in the Singapore region:
Singapore
https://dashscope-intl.aliyuncs.com/api/v1
Beijing
https://dashscope.aliyuncs.com/api/v1
Synchronous call
Request example
HELPCODEESCAPE-python
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope
# The following is the URL for the Singapore region. If you are using a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and Beijing regions are different. To obtain an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
print('----Sync call, please wait a moment----')
rsp = ImageSynthesis.call(api_key=api_key,
model="wan2.5-t2i-preview",
prompt="A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
negative_prompt="",
n=1,
size='1280*1280',
prompt_extend=True,
watermark=False,
seed=12345)
print('response: %s' % rsp)
if rsp.status_code == HTTPStatus.OK:
# Save the image in the current directory
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('sync_call Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))Response example
The URL is valid for 24 hours. You must download the image promptly.
HELPCODEESCAPE-json
{
"status_code": 200,
"request_id": "9d634fda-5fe9-9968-a908-xxxxxx",
"code": null,
"message": "",
"output": {
"task_id": "d35658e4-483f-453b-b8dc-xxxxxx",
"task_status": "SUCCEEDED",
"results": [{
"url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png",
"orig_prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
"actual_prompt": "An exquisite flower shop, with elegant carvings on the windows and a beautiful wooden door with a brass handle. Inside, a variety of colorful flowers such as roses, tulips, and lilies are displayed. The background is a warm indoor scene with soft light, creating a peaceful and comfortable atmosphere. High-definition realistic photography, close-up center composition."
}],
"submit_time": "2025-01-08 19:36:01.521",
"scheduled_time": "2025-01-08 19:36:01.542",
"end_time": "2025-01-08 19:36:13.270",
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
}
},
"usage": {
"image_count": 1
}
}Asynchronous call
Request example
HELPCODEESCAPE-python
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope
# The following is the URL for the Singapore region. If you are using a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API keys for the Singapore and Beijing regions are different. To obtain an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
def async_call():
print('----Create task----')
task_info = create_async_task()
print('----Wait for task to complete, then save image----')
wait_async_task(task_info)
# Create an asynchronous task
def create_async_task():
rsp = ImageSynthesis.async_call(api_key=api_key,
model="wan2.5-t2i-preview",
prompt="A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
negative_prompt="",
n=1,
size='1280*1280',
prompt_extend=True,
watermark=False,
seed=12345)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
return rsp
# Wait for the asynchronous task to finish
def wait_async_task(task):
rsp = ImageSynthesis.wait(task=task, api_key=api_key)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
# save file to current directory
for result in rsp.output.results:
file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
with open('./%s' % file_name, 'wb+') as f:
f.write(requests.get(result.url).content)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
# Fetch asynchronous task information
def fetch_task_status(task):
status = ImageSynthesis.fetch(task=task, api_key=api_key)
print(status)
if status.status_code == HTTPStatus.OK:
print(status.output.task_status)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(status.status_code, status.code, status.message))
# Cancel the asynchronous task. Only tasks in the PENDING state can be canceled.
def cancel_task(task):
rsp = ImageSynthesis.cancel(task=task, api_key=api_key)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.task_status)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
async_call()Response example
Response example for creating a task
HELPCODEESCAPE-json { "status_code": 200, "request_id": "31b04171-011c-96bd-ac00-f0383b669cc7", "code": "", "message": "", "output": { "task_id": "4f90cf14-a34e-4eae-xxxxxxxx", "task_status": "PENDING", "results": [] }, "usage": null }Response example for querying a task result
The URL is valid for 24 hours. You must download the image promptly.
HELPCODEESCAPE-json { "status_code": 200, "request_id": "9d634fda-5fe9-9968-a908-xxxxxx", "code": null, "message": "", "output": { "task_id": "d35658e4-483f-453b-b8dc-xxxxxx", "task_status": "SUCCEEDED", "results": [{ "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png", "orig_prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display", "actual_prompt": "An exquisite flower shop, with elegant carvings on the windows and a beautiful wooden door with a brass handle. Inside, a variety of colorful flowers such as roses, tulips, and lilies are displayed. The background is a warm indoor scene with soft light, creating a peaceful and comfortable atmosphere. High-definition realistic photography, close-up center composition." }], "submit_time": "2025-01-08 19:36:01.521", "scheduled_time": "2025-01-08 19:36:01.542", "end_time": "2025-01-08 19:36:13.270", "task_metrics": { "TOTAL": 1, "SUCCEEDED": 1, "FAILED": 0 } }, "usage": { "image_count": 1 } }
DashScope Java SDK
The SDK parameter names align with the HTTP API, with structures adapted for Java.
Text-to-image tasks can take significant time. The SDK encapsulates the HTTP asynchronous call flow and supports both synchronous and asynchronous calls.
Processing time depends on the task queue and service status.
wan2.6
Important
The following code applies only to the wan2.6-t2i model.
Make sure that your DashScope Java SDK version is 2.22.6 or later before you run the following code.
The base_url and API key are specific to each region and cannot be used interchangeably. The following examples show how to make a call in the Singapore region:
Singapore
https://dashscope-intl.aliyuncs.com/api/v1
Virginia
https://dashscope-us.aliyuncs.com/api/v1
Beijing
https://dashscope.aliyuncs.com/api/v1
Frankfurt
https://++{WorkspaceId}.eu-central-1.maas.aliyuncs.com++/api/v1
Replace WorkspaceId with your actual Workspace ID.
The global deployment scope (Frankfurt region) supports only asynchronous calls.
Synchronous call
Request example
HELPCODEESCAPE-java
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.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Collections;
public class Main {
static {
// This is the URL for the Singapore region. The base_url varies by region.
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey="sk-xxx"
// The API key is different for each region. To get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void basicCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-t2i")
.n(1)
.size("1280*1280")
.negativePrompt("")
.promptExtend(true)
.watermark(false)
.messages(Collections.singletonList(message))
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageGeneration.call(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
basicCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}Response example
The URL is valid for 24 hours. You must download the image promptly.
HELPCODEESCAPE-json
{
"status_code": 200,
"request_id": "50b57166-eaaa-4f17-b1e0-35a5ca88672c",
"code": "",
"message": "",
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{
"image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
"type": "image"
}
]
}
}
],
"finished": true
},
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"image_count": 1,
"size": "1280*1280",
"total_tokens": 0
}
}Asynchronous call
Request example
HELPCODEESCAPE-java
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.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.Collections;
public class Main {
static {
// This is the URL for the Singapore region. The base_url varies by region.
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey="sk-xxx"
// The API key is different for each region. To get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException {
ImageGenerationMessage message = ImageGenerationMessage.builder()
.role("user")
.content(Collections.singletonList(
Collections.singletonMap("text", "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display")
)).build();
ImageGenerationParam param = ImageGenerationParam.builder()
.apiKey(apiKey)
.model("wan2.6-t2i")
.n(1)
.size("1280*1280")
.negativePrompt("")
.promptExtend(true)
.watermark(false)
.messages(Collections.singletonList(message))
.build();
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = null;
try {
System.out.println("---async call, creating task----");
result = imageGeneration.asyncCall(param);
} catch (ApiException | NoApiKeyException | UploadFileException e) {
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
// Wait for the task to complete
waitTask(taskId);
}
public static void waitTask(String taskId) throws ApiException, NoApiKeyException {
ImageGeneration imageGeneration = new ImageGeneration();
ImageGenerationResult result = imageGeneration.wait(taskId, apiKey);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
asyncCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
}
}Response examples
Example response for creating a task
HELPCODEESCAPE-json { "status_code": 200, "request_id": "9cd85950-2e26-4b2c-b562-1694cf9288e5", "code": "", "message": "", "output": { "task_id": "4c861fbe-af89-4a2f-8fc5-4bb15c3139ba", "task_status": "PENDING" }, "usage": null }Example response for querying the task result
The URL is valid for 24 hours. You must download the image promptly.
HELPCODEESCAPE-json { "status_code": 200, "request_id": "cbdf1424-306e-4a52-82f3-8bf5d8a99103", "code": "", "message": "", "output": { "choices": [ { "finish_reason": "stop", "message": { "role": "assistant", "content": [ { "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx", "type": "image" } ] } } ], "task_id": "4c861fbe-af89-4a2f-8fc5-4bb15c3139ba", "task_status": "SUCCEEDED", "submit_time": "2026-01-16 16:36:06.556", "scheduled_time": "2026-01-16 16:36:06.591", "end_time": "2026-01-16 16:36:25.190", "finished": true }, "usage": { "input_tokens": 0, "output_tokens": 0, "size": "1280*1280", "total_tokens": 0, "image_count": 1 } }
wan2.5 and earlier models
Important
The following code applies only to wan2.5 and earlier models.
Make sure that your DashScope Java SDK version is 2.22.2 or later before you run the following code.
If your version is too old, errors such as "url error, please check url!" may occur. See Install the SDK to update.
The base_url and API key are specific to each region and cannot be used interchangeably. The following examples show how to make a call in the Singapore region:
Singapore
https://dashscope-intl.aliyuncs.com/api/v1
Beijing
https://dashscope.aliyuncs.com/api/v1
Synchronous call
Request example
HELPCODEESCAPE-java
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;
public class Main {
static {
// This is the URL for the Singapore region. If you use a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey="sk-xxx"
// The API keys for the Singapore and Beijing regions are different. To get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void basicCall() throws ApiException, NoApiKeyException {
// Set the parameters
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("seed", 12345);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.5-t2i-preview")
.prompt("A flower shop with exquisite windows, a beautiful wooden door, and flowers on display")
.n(1)
.size("1280*1280")
.negativePrompt("")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
System.out.println("---sync call, please wait a moment----");
result = imageSynthesis.call(param);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
}
public static void listTask() throws ApiException, NoApiKeyException {
ImageSynthesis is = new ImageSynthesis();
AsyncTaskListParam param = AsyncTaskListParam.builder().build();
param.setApiKey(apiKey);
ImageSynthesisListResult result = is.list(param);
System.out.println(result);
}
public static void fetchTask(String taskId) throws ApiException, NoApiKeyException {
ImageSynthesis is = new ImageSynthesis();
// If the DASHSCOPE_API_KEY environment variable is set, you can set apiKey to null.
ImageSynthesisResult result = is.fetch(taskId, apiKey);
System.out.println(result.getOutput());
System.out.println(result.getUsage());
}
public static void main(String[] args){
try{
basicCall();
//listTask();
}catch(ApiException|NoApiKeyException e){
System.out.println(e.getMessage());
}
}
}Response example
The URL is valid for 24 hours. You must download the image promptly.
HELPCODEESCAPE-json
{
"request_id": "22f9c744-206c-9a78-899a-xxxxxx",
"output": {
"task_id": "4a0f8fc6-03fb-4c44-a13a-xxxxxx",
"task_status": "SUCCEEDED",
"results": [{
"orig_prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display",
"actual_prompt": "A flower shop with exquisitely carved windows and a beautiful dark wooden door slightly ajar. A variety of fresh flowers, including roses, lilies, and sunflowers, are on display inside, vibrant in color and fragrant. The background is a cozy indoor scene with soft light streaming through the windows onto the flowers. High-definition realistic photography, medium shot composition.",
"url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png"
}],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
}
},
"usage": {
"image_count": 1
}
}Asynchronous call
Request example
HELPCODEESCAPE-java
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;
public class Main {
static {
// This is the URL for the Singapore region. If you use a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
}
// If you have not configured the environment variable, replace the following line with your Model Studio API key: apiKey="sk-xxx"
// The API keys for the Singapore and Beijing regions are different. To get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public void asyncCall() {
System.out.println("---create task----");
String taskId = this.createAsyncTask();
System.out.println("---wait task done then return image url----");
this.waitAsyncTask(taskId);
}
/**
* Create an asynchronous task
* @return taskId
*/
public String createAsyncTask() {
// Set the parameters
Map<String, Object> parameters = new HashMap<>();
parameters.put("prompt_extend", true);
parameters.put("watermark", false);
parameters.put("seed", 12345);
ImageSynthesisParam param =
ImageSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.5-t2i-preview")
.prompt("A flower shop with exquisite windows, a beautiful wooden door, and flowers on display")
.n(1)
.size("1280*1280)
.negativePrompt("")
.parameters(parameters)
.build();
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
result = imageSynthesis.asyncCall(param);
} catch (Exception e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
String taskId = result.getOutput().getTaskId();
System.out.println("taskId=" + taskId);
return taskId;
}
/**
* Wait for the asynchronous task to finish
* @param taskId The task ID
* */
public void waitAsyncTask(String taskId) {
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
// After configuring the environment variable, you can set apiKey to null here
result = imageSynthesis.wait(taskId, apiKey);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result));
System.out.println(JsonUtils.toJson(result.getOutput()));
}
public static void main(String[] args){
Main main = new Main();
main.asyncCall();
}
}Response examples
Example response for creating a task
HELPCODEESCAPE-json { "request_id": "5dbf9dc5-4f4c-9605-85ea-542f97709ba8", "output": { "task_id": "7277e20e-aa01-4709-xxxxxxxx", "task_status": "PENDING" } }Example response for querying the task result
HELPCODEESCAPE-json { "request_id": "22f9c744-206c-9a78-899a-xxxxxx", "output": { "task_id": "4a0f8fc6-03fb-4c44-a13a-xxxxxx", "task_status": "SUCCEEDED", "results": [{ "orig_prompt": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display", "actual_prompt": "A flower shop with exquisitely carved windows and a beautiful dark wooden door slightly ajar. A variety of fresh flowers, including roses, lilies, and sunflowers, are on display inside, vibrant in color and fragrant. The background is a cozy indoor scene with soft light streaming through the windows onto the flowers. High-definition realistic photography, medium shot composition.", "url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/1.png" }], "task_metrics": { "TOTAL": 1, "SUCCEEDED": 1, "FAILED": 0 } }, "usage": { "image_count": 1 } }
Limitations
Data validity : The task
task_idand imageurlare retained for only 24 hours. After this period, they cannot be queried or downloaded.Content moderation : Both the input
promptand output image undergo content moderation. Non-compliant content returns anIPInfringementSuspectorDataInspectionFailederror. See Error messages.
Billing and rate limiting
Check free quotas and pricing in the console.
For model rate limiting, see Wan series.
Billing is based on the number of images successfully generated. Failed calls do not incur fees and do not consume the new user free quota.
Error codes
If the model call fails and returns an error message, see Error messages for resolution.
FAQ
Q: How do I view a model's inference costs and call volume?
A: See Bill inquiry and cost management.