Wan2.7 - image generation and editing API reference - Alibaba Cloud Model Studio

The Wan 2.7 image generation and editing model supports text-to-image, text-to-image-set, image-to-image-set, image editing, and generation from multiple reference images to meet diverse generation and integration requirements.

Model overview

Model

Description

Output image specifications

wan2.7-image-pro

Wan2.7 image Professional Edition. Supports 4K high-definition output.

Image format: PNG.

For image resolution and dimensions, see the size parameter.

wan2.7-image

Wan2.7 image. Faster generation speed.

Note

Before making a call, check the Model list and pricing supported in each region.

Prerequisites

Get an API Key and export the API key as an environment variable.

Important

The Beijing and Singapore regions have separate API keys and request endpoints. Do not use them interchangeably. Cross-region calls result in authentication failures or service errors.

HTTP synchronous call

Retrieve results in a single request. This approach is simple and recommended for most scenarios.

Singapore

POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Beijing

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Request parameters	Text-to-image `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.7-image-pro", "input": { "messages": [ { "role": "user", "content": [ {"text": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"} ] } ] }, "parameters": { "size": "2K", "n": 1, "watermark": false, "thinking_mode": true } }'` Image editing 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.7-image-pro", "input": { "messages": [ { "role": "user", "content": [ {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"}, {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"}, {"text": "Spray the graffiti from image 2 onto the car in image 1"} ] } ] }, "parameters": { "size": "2K", "n": 1, "watermark": false, "thinking_mode": true } }' Interactive editing 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.7-image-pro", "input": { "messages": [ { "role": "user", "content": [ {"image": "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp"}, {"image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"}, {"text": "Place the alarm clock from image 1 in the selected area of image 2, ensuring the scene and lighting blend naturally"} ] } ] }, "parameters": { "bbox_list": [[],[[989, 515, 1138, 681]]], "size": "2K", "n": 1, "watermark": false, "thinking_mode": true } }' Image set generation 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.7-image-pro", "input": { "messages": [ { "role": "user", "content": [ {"text": "A cinematic image set documenting the same stray orange cat, with consistent features throughout. First image: Spring, the orange cat weaves through blooming cherry blossom trees. Second image: Summer, the orange cat cools off in the shade of a tree on an old street. Third image: Autumn, the orange cat walks on a carpet of golden fallen leaves. Fourth image: Winter, the orange cat leaves footprints in the snow."} ] } ] }, "parameters": { "enable_sequential": true, "n": 4, "size": "2K" } }'
Headers
Content-Type `string` (Required) The content type of the request. Must be `application/json`.
Authorization `string` (Required) The authentication credentials using a Model Studio API key. Example: `Bearer sk-xxxx`
Request body
model `string` (Required) The model name. Valid values: `wan2.7-image-pro`, `wan2.7-image`.
input `object` (Required) The basic input information. Properties messages `array` (Required) An array of request content. Currently, only single-turn conversations are supported. This means you can pass only one set of role and content parameters. Multi-turn conversations are not supported. Properties role `string` (Required) The role of the message. This parameter must be set to `user`. content `array` (Required) An array of message content. Properties text `string` The user-entered prompt. Supports Chinese and English. The length cannot exceed 5,000 characters. Each Chinese character, letter, number, or symbol counts as one character. Any excess is automatically truncated. image `string` The URL or Base64-encoded string of the input image. Image limits: Image format: JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP. Image resolution: The width and height must both be in the range of [240, 8000] pixels. The aspect ratio must be in the range of [1:8, 8:1]. File size: No more than 20 MB. Image quantity limits: Input 0 to 9 images. When inputting multiple images, pass multiple `image` objects in the `content` array. The order of the images is defined by their order in the array. Supported input formats: Use a publicly accessible URL Supports HTTP or HTTPS protocols. Example: `http://wanx.alicdn.com/material/xxx.jpeg`. Pass a Base64-encoded image string Format: data:{MIME_type};base64,{base64_data} Example: data:image/jpeg;base64,GDU7MtCZzEbTbmRZ... (This is an example. You must pass the complete string.) For Base64 encoding specifications, see Image input methods.
parameters `object` (Optional) Model parameter settings. Properties bbox_list `List[List[List[int]]]` (Optional) The selected area for interactive editing. Correspondence: The length of the list must match the number of input images. If an image does not require editing, pass an empty list `[]` at the corresponding position. Coordinate format: `[x1, y1, x2, y2]` (top-left x, top-left y, bottom-right x, bottom-right y). Use absolute pixel coordinates of the original image. The top-left coordinate is (0, 0). Condition: A single image supports a maximum of 2 bounding boxes. Example: Input 3 images. The second image has no bounding box, and the first image has two bounding boxes: `[ [[0, 0, 12, 12], [25, 25, 100, 100]], # Image 1 (2 boxes) [], # Image 2 (no box) [[10, 10, 50, 50]] # Image 3 (1 box) ]` enable_sequential `boolean` (Optional) Controls the image generation mode: false: Default value. true: Enables image set output mode. size `string` (Optional) The output image resolution parameter supports the following two methods. They cannot be used together: Model: wan2.7-image-pro Method 1: Specify the output image resolution (Recommended) Supports 1K, 2K (default), and 4K specifications. Scope of application: Text-to-image (no image input, not generating an image set): Supports 1K, 2K, and 4K. Other scenarios: Supports 1K and 2K. Total pixels for each specification: 1K: 1024×1024, 2K: 2048×2048, 4K: 4096×4096 Image aspect ratio: With image input: The output aspect ratio matches the input image (the last one if multiple images are input) and is scaled to the selected resolution. Without image input: The output is a square. Method 2: Specify the width and height pixel values of the generated image Text-to-image: Total pixels between [768×768, 4096×4096]. Aspect ratio range is [1:8, 8:1]. Other scenarios: Total pixels between [768×768, 2048×2048]. Aspect ratio range is [1:8, 8:1]. Model: wan2.7-image Method 1: Specify the output image resolution (Recommended) Supports 1K and 2K (default) specifications. 4K is not supported. Method 2: Specify the width and height pixel values of the generated image In all scenarios, the total pixels are between [768×768, 2048×2048], and the aspect ratio range is [1:8, 8:1]. The pixel value of the output image may differ slightly from the specified pixel value. n `int` (Optional) Important The value of n directly affects the cost. Cost = Unit Price × Number of successfully generated images. Before making a call, confirm the model pricing. When image set mode is disabled, this value represents the number of images to generate. The value range is 1–4. The default is 4. When image set mode is enabled, this value represents the maximum number of images to generate. The value range is 1–12. The default is 12. The actual number is determined by the model and will not exceed n. thinking_mode `boolean` (Optional) Specifies whether to enable thinking mode. The default is `true` (enabled). This parameter is effective only when image set mode is disabled and there is no image input. When enabled, the model enhances its inference capabilities to improve image quality, but this increases generation time. color_palette `array` (Optional) A custom color theme. An array of objects containing color (hex) and proportion (ratio). It must include 3 to 10 colors. We recommend setting it to 8. Available only when image set mode is disabled (`enable_sequential=false`). Properties hex `string` (Required) The color value in hexadecimal (HEX) format. ratio `string` (Required) The percentage of the color. It must be accurate to two decimal places (for example, `"25.00%"`). The sum of all `ratio` values must be 100.00%. Click to view an input example `"color_palette": [ { "hex": "#C2D1E6", "ratio": "23.51%" }, { "hex": "#CDD8E9", "ratio": "20.13%" }, { "hex": "#B5C8DB", "ratio": "15.88%" }, { "hex": "#C0B5B4", "ratio": "13.27%" }, { "hex": "#DAE0EC", "ratio": "10.11%" }, { "hex": "#636574", "ratio": "8.93%" }, { "hex": "#CACAD2", "ratio": "5.55%" }, { "hex": "#CBD4E4", "ratio": "2.62%" } ]` watermark `bool` (Optional) Adds a watermark label in the bottom-right corner of the image with fixed text "AI Generated". 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	Task executed successfully 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-xxx.oss-xxx.aliyuncs.com/xxx.png?Expires=xxx", "type": "image" } ], "role": "assistant" } } ], "finished": true }, "usage": { "image_count": 1, "input_tokens": 10867, "output_tokens": 2, "size": "1488*704", "total_tokens": 10869 }, "request_id": "71dfc3c6-f796-9972-97e4-bc4efc4faxxx" }` Task execution abnormal If the task fails for any reason, relevant information is returned. The code and message fields indicate the cause of the error. For more information, see Error messages to resolve the issue. `{ "request_id": "a4d78a5f-655f-9639-8437-xxxxxx", "code": "InvalidParameter", "message": "num_images_per_prompt must be 1" }`
output `object` Task output information. Properties choices `array` The output content generated by the model. Properties finish_reason `string` The reason the task stopped. A natural stop is indicated by `stop`. message `object` The message returned by the model. Properties role `string` The role of the message, fixed as `assistant`. content `array` Properties type `string` The output type, fixed as image. image `string` The URL of the generated image. The image format is PNG. The link is valid for 24 hours. Download and save the image promptly. finished `boolean` Indicates whether the task is finished. true false
usage `object` Statistics on the output information. Only successful results are counted. Properties image_count `integer` The number of generated images. size `string` The resolution of the generated image. Example: 1376×768. input_tokens `integer` The number of input tokens (not billed). Billing is based on the number of images. output_tokens `integer` The number of output tokens (not billed). Billing is based on the number of images. total_tokens `integer` The total number of tokens (not billed). Billing is based on the number of images.
request_id `string` Unique identifier for the request. Use for tracing and troubleshooting issues.
code `string` The error code. Returned only when the request fails. See error codes for details.
message `string` Detailed error message. Returned only when the request fails. See error codes for details.

HTTP asynchronous call

Suitable for long-running tasks. Supports querying task status and results.

Step 1: Create a task and get the task ID

Singapore

POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image-generation/generation

Beijing

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image-generation/generation

Request parameters	Text-to-image 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.7-image-pro", "input": { "messages": [ { "role": "user", "content": [ {"text": "A flower shop with exquisite windows, a beautiful wooden door, and flowers on display"} ] } ] }, "parameters": { "size": "2K", "n": 1, "watermark": false, "thinking_mode": true } }' Image editing 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.7-image-pro", "input": { "messages": [ { "role": "user", "content": [ {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"}, {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"}, {"text": "Spray the graffiti from image 2 onto the car in image 1"} ] } ] }, "parameters": { "size": "2K", "n": 1, "watermark": false, "thinking_mode": true } }' Interactive editing 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.7-image-pro", "input": { "messages": [ { "role": "user", "content": [ {"image": "https://img.alicdn.com/imgextra/i3/O1CN0157XGE51l6iL9441yX_!!6000000004770-49-tps-1104-1472.webp"}, {"image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"}, {"text": "Place the alarm clock from image 1 in the selected area of image 2, ensuring the scene and lighting blend naturally"} ] } ] }, "parameters": { "bbox_list": [[],[[989, 515, 1138, 681]]], "size": "2K", "n": 1, "watermark": false, "thinking_mode": true } }' Image set generation 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.7-image-pro", "input": { "messages": [ { "role": "user", "content": [ {"text": "A cinematic image set documenting the same stray orange cat, with consistent features throughout. First image: Spring, the orange cat weaves through blooming cherry blossom trees. Second image: Summer, the orange cat cools off in the shade of a tree on an old street. Third image: Autumn, the orange cat walks on a carpet of golden fallen leaves. Fourth image: Winter, the orange cat leaves footprints in the snow."} ] } ] }, "parameters": { "enable_sequential": true, "n": 4, "size": "2K" } }'
Headers
Content-Type `string` (Required) The content type of the request. Must be `application/json`.
Authorization `string` (Required) The authentication credentials using a Model Studio API key. Example: `Bearer sk-xxxx`
X-DashScope-Async `string` (Required) Enables asynchronous processing. Must be `enable` as HTTP requests support only asynchronous processing. Important Returns "current user api does not support synchronous calls" error if not included.
Request body
model `string` (Required) The model name. Valid values: `wan2.7-image-pro`, `wan2.7-image`.
input `object` (Required) The basic input information. Properties messages `array` (Required) An array of request content. Currently, only single-turn conversations are supported. This means you can pass only one set of role and content parameters. Multi-turn conversations are not supported. Properties role `string` (Required) The role of the message. This parameter must be set to `user`. content `array` (Required) An array of message content. Properties text `string` The user-entered prompt. Supports Chinese and English. The length cannot exceed 5,000 characters. Each Chinese character, letter, number, or symbol counts as one character. Any excess is automatically truncated. image `string` The URL or Base64-encoded string of the input image. Image limits: Image format: JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP. Image resolution: The width and height must both be in the range of [240, 8000] pixels. The aspect ratio must be in the range of [1:8, 8:1]. File size: No more than 20 MB. Image quantity limits: Input 0 to 9 images. When inputting multiple images, pass multiple `image` objects in the `content` array. The order of the images is defined by their order in the array. Supported input formats: Use a publicly accessible URL Supports HTTP or HTTPS protocols. Example: `http://wanx.alicdn.com/material/xxx.jpeg`. Pass a Base64-encoded image string Format: data:{MIME_type};base64,{base64_data} Example: data:image/jpeg;base64,GDU7MtCZzEbTbmRZ... (This is an example. You must pass the complete string.) For Base64 encoding specifications, see Image input methods.
parameters `object` (Optional) Model parameter settings. Properties bbox_list `List[List[List[int]]]` (Optional) The selected area for interactive editing. Correspondence: The length of the list must match the number of input images. If an image does not require editing, pass an empty list `[]` at the corresponding position. Coordinate format: `[x1, y1, x2, y2]` (top-left x, top-left y, bottom-right x, bottom-right y). Use absolute pixel coordinates of the original image. The top-left coordinate is (0, 0). Condition: A single image supports a maximum of 2 bounding boxes. Example: Input 3 images. The second image has no bounding box, and the first image has two bounding boxes: `[ [[0, 0, 12, 12], [25, 25, 100, 100]], # Image 1 (2 boxes) [], # Image 2 (no box) [[10, 10, 50, 50]] # Image 3 (1 box) ]` enable_sequential `boolean` (Optional) Controls the image generation mode: false: Default value. true: Enables image set output mode. size `string` (Optional) The output image resolution parameter supports the following two methods. They cannot be used together: Model: wan2.7-image-pro Method 1: Specify the output image resolution (Recommended) Supports 1K, 2K (default), and 4K specifications. Scope of application: Text-to-image (no image input, not generating an image set): Supports 1K, 2K, and 4K. Other scenarios: Supports 1K and 2K. Total pixels for each specification: 1K: 1024×1024, 2K: 2048×2048, 4K: 4096×4096 Image aspect ratio: With image input: The output aspect ratio matches the input image (the last one if multiple images are input) and is scaled to the selected resolution. Without image input: The output is a square. Method 2: Specify the width and height pixel values of the generated image Text-to-image: Total pixels between [768×768, 4096×4096]. Aspect ratio range is [1:8, 8:1]. Other scenarios: Total pixels between [768×768, 2048×2048]. Aspect ratio range is [1:8, 8:1]. Model: wan2.7-image Method 1: Specify the output image resolution (Recommended) Supports 1K and 2K (default) specifications. 4K is not supported. Method 2: Specify the width and height pixel values of the generated image In all scenarios, the total pixels are between [768×768, 2048×2048], and the aspect ratio range is [1:8, 8:1]. The pixel value of the output image may differ slightly from the specified pixel value. n `int` (Optional) Important The value of n directly affects the cost. Cost = Unit Price × Number of successfully generated images. Before making a call, confirm the model pricing. When image set mode is disabled, this value represents the number of images to generate. The value range is 1–4. The default is 4. When image set mode is enabled, this value represents the maximum number of images to generate. The value range is 1–12. The default is 12. The actual number is determined by the model and will not exceed n. thinking_mode `boolean` (Optional) Specifies whether to enable thinking mode. The default is `true` (enabled). This parameter is effective only when image set mode is disabled and there is no image input. When enabled, the model enhances its inference capabilities to improve image quality, but this increases generation time. color_palette `array` (Optional) A custom color theme. An array of objects containing color (hex) and proportion (ratio). It must include 3 to 10 colors. We recommend setting it to 8. Available only when image set mode is disabled (`enable_sequential=false`). Properties hex `string` (Required) The color value in hexadecimal (HEX) format. ratio `string` (Required) The percentage of the color. It must be accurate to two decimal places (for example, `"25.00%"`). The sum of all `ratio` values must be 100.00%. Click to view an input example `"color_palette": [ { "hex": "#C2D1E6", "ratio": "23.51%" }, { "hex": "#CDD8E9", "ratio": "20.13%" }, { "hex": "#B5C8DB", "ratio": "15.88%" }, { "hex": "#C0B5B4", "ratio": "13.27%" }, { "hex": "#DAE0EC", "ratio": "10.11%" }, { "hex": "#636574", "ratio": "8.93%" }, { "hex": "#CACAD2", "ratio": "5.55%" }, { "hex": "#CBD4E4", "ratio": "2.62%" } ]` watermark `bool` (Optional) Adds a watermark label in the bottom-right corner of the image with fixed text "AI Generated". 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. `{ "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 codes to resolve the issue. `{ "code": "InvalidApiKey", "message": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` Task output information. Properties task_id `string` The ID of the task. Can be used to query the task for up to 24 hours. task_status `string` The status of the task. Enumeration PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Task does not exist or status is unknown
request_id `string` Unique identifier for the request. Use for tracing and troubleshooting issues.
code `string` The error code. Returned only when the request fails. See error codes for details.
message `string` Detailed error message. Returned only when the request fails. See error codes for details.

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}

Request parameters	Query task result Replace `{task_id}` with the `task_id` value returned by the previous API call. `task_id` is valid for queries within 24 hours. `curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
Headers
Authorization `string` (Required) The authentication credentials using a Model Studio API key. Example: `Bearer sk-xxxx`
URL path parameters
task_id `string` (Required) The ID of the task to query.

Response parameters	Task executed successfully Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. { "request_id": "810fa5f5-334c-91f3-aaa4-ed89cf0caxxx", "output": { "task_id": "a81ee7cb-014c-473d-b842-76e98311cxxx", "task_status": "SUCCEEDED", "submit_time": "2026-03-26 17:16:01.663", "scheduled_time": "2026-03-26 17:16:01.716", "end_time": "2026-03-26 17:16:22.961", "finished": true, "choices": [ { "finish_reason": "stop", "message": { "role": "assistant", "content": [ { "image": "https://dashscope-xxx.oss-xxx.aliyuncs.com/xxx.png?Expires=xxx", "type": "image" } ] } } ] }, "usage": { "size": "2976*1408", "total_tokens": 11017, "image_count": 1, "output_tokens": 2, "input_tokens": 11015 } } Task execution abnormal If the task fails for any reason, relevant information is returned. The code and message fields indicate the cause of the error. For more information, see Error messages to resolve the issue. `{ "request_id": "a4d78a5f-655f-9639-8437-xxxxxx", "code": "InvalidParameter", "message": "num_images_per_prompt must be 1" }`
output `object` Task output information. Properties task_id `string` The ID of the task. Can be used to query the task for up to 24 hours. task_status `string` The status of the task. Enumeration PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Task does not exist or status is unknown Status transitions during polling: PENDING → RUNNING → SUCCEEDED or FAILED First query typically returns PENDING or RUNNING SUCCEEDED status includes the generated image URL in the response FAILED status requires checking the error message and retrying submit_time `string` The time when the task was submitted. Time is in UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`. scheduled_time `string` The time when the task started running. Time is in UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`. end_time `string` The time when the task was completed. Time is in UTC+8. Format: `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. A natural stop is indicated by `stop`. message `object` The message returned by the model. Properties role `string` The role of the message, fixed as `assistant`. content `array` Properties type `string` The output type. Enumeration values are text and image. text `string` The generated text. image `string` The URL of the generated image. The image format is PNG. The link is valid for 24 hours. Download and save the image promptly.
usage `object` Statistics on the output information. Only successful results are counted. Properties image_count `integer` The number of generated images. size `string` The resolution of the generated image. Example: 1376×768. input_tokens `integer` The number of input tokens (not billed). Billing is based on the number of images. output_tokens `integer` The number of output tokens (not billed). Billing is based on the number of images. total_tokens `integer` The total number of tokens (not billed). Billing is based on the number of images.
request_id `string` Unique identifier for the request. Use for tracing and troubleshooting issues.
code `string` The error code. Returned only when the request fails. See error codes for details.
message `string` Detailed error message. Returned only when the request fails. See error codes for details.

Python SDK

The parameter naming in the SDK is mostly consistent with the HTTP interface. The parameter structure is encapsulated based on the language features.

Because tasks can be time-consuming, the SDK encapsulates the HTTP asynchronous call process at the underlying layer, supporting both synchronous and asynchronous call methods.

The specific time required depends on the number of tasks in the queue and the service execution status. Please be patient while waiting for the results.

Important

Ensure the DashScope Python SDK version is at least 1.25.15 before running the following code. For updates, see Install SDK.

The base_url and API key for each region are not interchangeable. The following examples show calls for the Singapore region:

Singapore: https://dashscope-intl.aliyuncs.com/api/v1

Beijing: https://dashscope.aliyuncs.com/api/v1

Image editing

Synchronous call

Request example

import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message

# The following is the base_url for the Singapore region. The base_url is different for each region.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key is different for each region. Get 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",
    # Supports local files, for example, "image": "file://car.png"
    content=[
        {
            "text": "Spray the graffiti from image 2 onto the car in image 1"
        },
        {
            "image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"
        },
        {
            "image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp"
        }
    ]
)
print("----sync call, please wait a moment----")
rsp = ImageGeneration.call(
        model='wan2.7-image-pro',
        api_key=api_key,
        messages=[message],
        watermark=False,
        n=1,
        size="2K"
    )

print(rsp)

Response example

The URL is valid for 24 hours. Download the image promptly.

{
    "status_code": 200,
    "request_id": "81d868c6-6ce1-92d8-a90d-d2ee71xxxxxx",
    "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": 18790,
        "output_tokens": 2,
        "characters": 0,
        "image_count": 1,
        "size": "2985*1405",
        "total_tokens": 18792
    }
}

Asynchronous call

Request example

import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message
from http import HTTPStatus

# The following is the base_url for the Singapore region. The base_url is different for each region.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key is different for each region. Get 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': 'Spray the graffiti from image 2 onto the car in image 1'},
            {'image': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp'},
            {'image': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp'}
        ]
    )
    response = ImageGeneration.async_call(
        model="wan2.7-image-pro",
        api_key=api_key,
        messages=[message],
        watermark=False,
        n=1,
        size="2K"
    )
    
    if response.status_code == 200:
        print("Task created successfully:", response)
        return response  # Return the task ID
    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}")

# Get 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

1. Response example for creating a task

{
    "status_code": 200,
    "request_id": "4fb3050f-de57-4a24-84ff-e37ee5xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": null,
        "audio": null,
        "task_id": "127ec645-118f-4884-955d-0eba8dxxxxxx",
        "task_status": "PENDING"
    },
    "usage": {
        "input_tokens": 0,
        "output_tokens": 0,
        "characters": 0
    }
}

2. Response example for querying a task result

The URL is valid for 24 hours. Download the image promptly.

{
    "status_code": 200,
    "request_id": "3b99aae5-d26f-9059-8dd0-ee9ca4804xxx",
    "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": "127ec645-118f-4884-955d-0eba8dxxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-31 22:58:47.646",
        "scheduled_time": "2026-03-31 22:58:47.683",
        "end_time": "2026-03-31 22:58:59.642",
        "finished": true
    },
    "usage": {
        "input_tokens": 18711,
        "output_tokens": 2,
        "characters": 0,
        "size": "2985*1405",
        "total_tokens": 18713,
        "image_count": 1
    }
}

Image set generation

Synchronous call

Request example

import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message

# The following is the base_url for the Singapore region. The base_url is different for each region.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key is different for each region. Get 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 cinematic image set documenting the same stray orange cat, with consistent features throughout. First image: Spring, the orange cat weaves through blooming cherry blossom trees. Second image: Summer, the orange cat cools off in the shade of a tree on an old street. Third image: Autumn, the orange cat walks on a carpet of golden fallen leaves. Fourth image: Winter, the orange cat leaves footprints in the snow."
        }
    ]
)

print("----sync call, please wait a moment----")
rsp = ImageGeneration.call(
        model='wan2.7-image-pro',
        api_key=api_key,
        messages=[message],
        enable_sequential=True,
        n=4,
        size="2K"
    )

print(rsp)

Response example

The URL is valid for 24 hours. Download the image promptly.

{
    "status_code": 200,
    "request_id": "56e318fd-ed60-99e8-8ca1-cdef25ca4xxx",
    "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"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ],
        "audio": null,
        "finished": true
    },
    "usage": {
        "input_tokens": 720,
        "output_tokens": 11,
        "characters": 0,
        "image_count": 4,
        "size": "2048*2048",
        "total_tokens": 731
    }
}

Asynchronous call

Request example

import os
import dashscope
from dashscope.aigc.image_generation import ImageGeneration
from dashscope.api_entities.dashscope_response import Message

# The following is the base_url for the Singapore region. The base_url is different for each region.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# If you have not configured environment variables, replace the following line with your Model Studio API key: api_key="sk-xxx"
# The API key is different for each region. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")


def main():
    message = Message(
        role="user",
        content=[
            {"text": "A cinematic image set documenting the same stray orange cat, with consistent features throughout. First image: Spring, the orange cat weaves through blooming cherry blossom trees. Second image: Summer, the orange cat cools off in the shade of a tree on an old street. Third image: Autumn, the orange cat walks on a carpet of golden fallen leaves. Fourth image: Winter, the orange cat leaves footprints in the snow."}
        ]
    )
    
    # Submit an asynchronous task
    print("Submitting asynchronous task...")
    response = ImageGeneration.async_call(
        model="wan2.7-image-pro",
        api_key=api_key,
        messages=[message],
        enable_sequential=True,
        n=4,
        size="2K"
    )
    
    if response.status_code == 200:
        print(f"Task submitted successfully, Task ID: {response.output.task_id}")
        
        # Wait for the task to complete
        status = ImageGeneration.wait(task=response, api_key=api_key)
        
        if status.output.task_status == "SUCCEEDED":
            print("Task completed!")
            print(f"Result:")
            print(status)
        else:
            print(f"Task failed, status: {status.output.task_status}")
    else:
        print(f"Task creation failed: {response.code} - {response.message}")


if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"Error: {e}")

Response example

1. Response example for creating a task

{
    "status_code": 200,
    "request_id": "4fb3050f-de57-4a24-84ff-e37ee5xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": null,
        "audio": null,
        "task_id": "77093787-a217-4c29-9cd4-ca7b5ac86xxx",
        "task_status": "PENDING"
    },
    "usage": {
        "input_tokens": 0,
        "output_tokens": 0,
        "characters": 0
    }
}

2. Response example for querying a task result

The URL is valid for 24 hours. Download the image promptly.

{
    "status_code": 200,
    "request_id": "56e318fd-ed60-99e8-8ca1-cdef25ca4xxx",
    "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"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ],
        "audio": null,
        "task_id": "77093787-a217-4c29-9cd4-ca7b5ac86xxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-31 23:04:46.166",
        "scheduled_time": "2026-03-31 23:04:46.208",
        "end_time": "2026-03-31 23:05:11.664",
        "finished": true
    },
    "usage": {
        "input_tokens": 720,
        "output_tokens": 11,
        "characters": 0,
        "size": "2048*2048",
        "total_tokens": 731,
        "image_count": 4
    }
}

Java SDK

SDK parameter naming aligns with HTTP API naming. Parameter structures are encapsulated based on language features.

Because tasks take a long time, the SDK encapsulates the HTTP asynchronous invocation process at the underlying layer. It supports both synchronous and asynchronous invocation methods.

Important

Ensure the DashScope Java SDK version is not earlier than 2.22.13; otherwise, some parameters used in this topic might not be supported.

Singapore: https://dashscope-intl.aliyuncs.com/api/v1

Beijing: https://dashscope.aliyuncs.com/api/v1

Image editing

Synchronous call

Request example

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.Arrays;
import java.util.Collections;

/**
 * wan2.7-image-pro Image Editing - Synchronous Call Example
 */
public class Main {

    static {
        // This is the URL for the Singapore region. The base_url differs for each 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 differs for each region. Get your API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void basicCall() throws ApiException, NoApiKeyException, UploadFileException {
        // Build multi-image input message
        ImageGenerationMessage message = ImageGenerationMessage.builder()
                .role("user")
                .content(Arrays.asList(
                        // Supports multi-image input; provide multiple reference images.
                        Collections.singletonMap("text", "Spray the graffiti from image 2 onto the car in image 1"),
                        Collections.singletonMap("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"),
                        Collections.singletonMap("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp")
                )).build();

        ImageGenerationParam param = ImageGenerationParam.builder()
                .apiKey(apiKey)
                .model("wan2.7-image-pro")
                .messages(Collections.singletonList(message))
                .n(1)
                .size("2K")
                .build();

        ImageGeneration imageGeneration = new ImageGeneration();
        ImageGenerationResult result = null;
        try {
            System.out.println("---synchronous call for image editing, 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. Save it promptly.

{
    "requestId": "1bf6173a-e8de-9f75-94d3-5e618f875xxx",
    "usage": {
        "input_tokens": 18790,
        "output_tokens": 2,
        "total_tokens": 18792,
        "image_count": 1,
        "size": "2985*1405"
    },
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ],
        "finished": true
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Asynchronous call

Request example

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.Arrays;
import java.util.Collections;

/**
 * wan2.7-image-pro Image Editing - Asynchronous Call Example
 */
public class Main {

    static {
        // This is the URL for the Singapore region. The base_url differs for each 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 differs for each region. Get your API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException {
        // Build multi-image input message
        ImageGenerationMessage message = ImageGenerationMessage.builder()
                .role("user")
                .content(Arrays.asList(
                        // Supports multi-image input; provide multiple reference images.
                        Collections.singletonMap("text", "Spray the graffiti from image 2 onto the car in image 1"),
                        Collections.singletonMap("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/pjeqdf/car.webp"),
                        Collections.singletonMap("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251229/xsunlm/paint.webp")
                )).build();

        ImageGenerationParam param = ImageGenerationParam.builder()
                .apiKey(apiKey)
                .model("wan2.7-image-pro")
                .n(1)
                .size("2K")
                .messages(Arrays.asList(message))
                .build();

        ImageGeneration imageGeneration = new ImageGeneration();
        ImageGenerationResult result = null;
        try {
            System.out.println("---asynchronous call for image editing, creating task----");
            result = imageGeneration.asyncCall(param);
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            throw new RuntimeException(e.getMessage());
        }
        System.out.println("Task creation result:");
        System.out.println(JsonUtils.toJson(result));

        String taskId = result.getOutput().getTaskId();
        // Wait for task completion
        waitTask(taskId);
    }

    public static void waitTask(String taskId) throws ApiException, NoApiKeyException {
        ImageGeneration imageGeneration = new ImageGeneration();
        System.out.println("\n---waiting for task completion----");
        ImageGenerationResult result = imageGeneration.wait(taskId, apiKey);
        System.out.println("Task completion result:");
        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 example

1. Response example for task creation

{
    "requestId": "ccf4b2f4-bf30-9e13-9461-3a28c6a7bxxx",
    "output": {
        "task_id": "8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx",
        "task_status": "PENDING"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

2. Response example for querying task result

The URL is valid for 24 hours. Save it promptly.

{
    "requestId": "60a08540-f1c1-9e76-8cd3-d5949db8cxxx",
    "usage": {
        "input_tokens": 18711,
        "output_tokens": 2,
        "total_tokens": 18713,
        "image_count": 1,
        "size": "2985*1405"
    },
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ],
        "task_id": "8811b4a4-00ac-4aa2-a2fd-017d3b90cxxx",
        "task_status": "SUCCEEDED",
        "finished": true,
        "submit_time": "2026-03-31 19:57:58.840",
        "scheduled_time": "2026-03-31 19:57:58.877",
        "end_time": "2026-03-31 19:58:11.563"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Image group generation

Synchronous call

Request example

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;

/**
 * wan2.7-image-pro Image Group Generation - Synchronous Call Example (Singapore region)
 */
public class Main {

    static {
        // The following is the Singapore region URL. 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 varies by region. Get API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void basicCall() throws ApiException, NoApiKeyException, UploadFileException {
        // Build text input message (supports text-to-image group generation and image-to-image group generation; this example uses text-to-image group generation)
        ImageGenerationMessage message = ImageGenerationMessage.builder()
                .role("user")
                .content(Collections.singletonList(
                        Collections.singletonMap("text", "Cinematic image group, documenting the same stray orange cat, features must be consistent throughout. First image: Spring, an orange cat walks under blooming cherry trees; Second image: Summer, an orange cat rests in the shade of an old street to escape the heat; Third image: Autumn, an orange cat walks on golden fallen leaves; Fourth image: Winter, an orange cat walks on snow, leaving paw prints.")
                )).build();

        ImageGenerationParam param = ImageGenerationParam.builder()
                .apiKey(apiKey)
                .model("wan2.7-image-pro")
                .messages(Collections.singletonList(message))
                .enableSequential(true)
                .n(4)
                .size("2K")
                .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. Save it promptly.

{
    "requestId": "4678c314-b37a-91c9-a2ae-2d3cd54bbxxx",
    "usage": {
        "input_tokens": 720,
        "output_tokens": 11,
        "total_tokens": 731,
        "image_count": 4,
        "size": "2048*2048"
    },
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ],
        "finished": true
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Asynchronous call

Request example

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;

/**
 * wan2.7-image-pro Image Group Generation - Asynchronous Invocation Example (Singapore region)
 */
public class Main {

    static {
        // The following is the Singapore region URL. 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 varies by region. Get API key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static ImageGenerationResult waitTask(String taskId)
            throws ApiException, NoApiKeyException {
        ImageGeneration imageGeneration = new ImageGeneration();
        return imageGeneration.wait(taskId, apiKey);
    }

    public static void asyncCall() throws ApiException, NoApiKeyException, UploadFileException {
        // Build text input message (supports text-to-image group generation and image-to-image group generation; this example uses text-to-image group generation)
        ImageGenerationMessage message = ImageGenerationMessage.builder()
                .role("user")
                .content(Collections.singletonList(
                        Collections.singletonMap("text", "Cinematic image group, documenting the same stray orange cat, features must be consistent throughout. First image: Spring, an orange cat walks under blooming cherry trees; Second image: Summer, an orange cat rests in the shade of an old street to escape the heat; Third image: Autumn, an orange cat walks on golden fallen leaves; Fourth image: Winter, an orange cat walks on snow, leaving paw prints.")
                )).build();

        ImageGenerationParam param = ImageGenerationParam.builder()
                .apiKey(apiKey)
                .model("wan2.7-image-pro")
                .messages(Collections.singletonList(message))
                .enableSequential(true)
                .n(4)
                .size("2K")
                .build();

        ImageGeneration imageGeneration = new ImageGeneration();
        ImageGenerationResult taskResult = null;
        try {
            System.out.println("----async call, creating task----");
            taskResult = imageGeneration.asyncCall(param);
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            throw new RuntimeException(e.getMessage());
        }
        System.out.println("Task created: " + JsonUtils.toJson(taskResult));

        // Wait for the task to complete
        String taskId = taskResult.getOutput().getTaskId();
        ImageGenerationResult result = waitTask(taskId);
        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 example

1. Response example for creating a task

{
    "requestId": "7d026dc1-e8c9-9caa-84ac-e82e2da97xxx",
    "output": {
        "task_id": "2de18c56-c151-4b80-8105-1d164733exxx",
        "task_status": "PENDING"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

2. Response example for querying task result

The URL is valid for 24 hours. Save it promptly.

{
    "requestId": "daea7295-4ce0-928a-9a11-4d2bea058xxx",
    "usage": {
        "input_tokens": 720,
        "output_tokens": 11,
        "total_tokens": 731,
        "image_count": 4,
        "size": "2048*2048"
    },
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        },
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxxx.png?Expires=xxxxxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ],
        "task_id": "2de18c56-c151-4b80-8105-1d164733exxx",
        "task_status": "SUCCEEDED",
        "finished": true,
        "submit_time": "2026-03-31 19:49:53.124",
        "scheduled_time": "2026-03-31 19:49:53.175",
        "end_time": "2026-03-31 19:50:53.160"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Billing and rate limiting

For free quota and unit prices, see Model pricing.
For rate limits, see Wan series.
Billing details: You are billed per successfully generated image. Failed model calls or processing faults incur no charges and do not consume your Free quota for new users.

Error codes

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

Model overview

Prerequisites

HTTP synchronous call

Singapore

Beijing

Request parameters

Text-to-image

Image editing

Interactive editing

Image set generation

Headers

Request body

Response parameters

Task executed successfully

Task execution abnormal

HTTP asynchronous call

Step 1: Create a task and get the task ID

Singapore

Beijing

Request parameters

Text-to-image

Image editing

Interactive editing

Image set generation

Headers

Request body

Response parameters

Successful response

Error response

Step 2: Query the result by task ID

Singapore

Beijing

Request parameters

Query task result

Headers

URL path parameters

Response parameters

Task executed successfully

Task execution abnormal

Python SDK

Image editing

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Image set generation

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Java SDK

Image editing

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Image group generation

Synchronous call

Request example

Response example

Asynchronous call

Request example

Response example

Billing and rate limiting

Error codes