DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio Model API Image Generation Wan Wan2.6 - image generation and editing

Wan2.6 - image generation and editing

Updated at:
Copy as MD
Product
My Favorites

Wan2.6 supports multi-image input, image editing, and interleaved text-image output.

Model overview

Model name

Description

Output image specifications

wan2.6-image

Wan2.6 image

Supports image editing and interleaved text-image output.

For pure text-to-image generation, we recommend using the wan2.6-t2i model (Tongyi Wan - Text-to-Image V2).

Image format: PNG.

For image resolution and dimensions, see the size parameter.

NoteBefore calling the API, check the model list and pricing supported in each region.

Prerequisites

Obtain and configure an API key and export the API key as an environment variable.

ImportantThe China (Beijing), Singapore, and US (Virginia) 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, service deployment scope, and endpoint.

ImportantAlibaba Cloud Model Studio has launched workspace-dedicated domains for the China (Beijing) and Singapore regions, which deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

  • China (Beijing) region: migrate from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore region: migrate from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} is your workspace ID, which you can view on the Workspace details page in the Model Studio console. The existing domains remain available.

HTTP synchronous calls

Returns results in a single request with a simple process. Recommended for most scenarios.

China (Beijing)

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

When calling, replace {WorkspaceId} with your actual Workspace ID.

Singapore

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

When calling, replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

The global deployment scope (Frankfurt region) only supports asynchronous calls.

Request parameters

Request headers

Content-Typestring(Required)

The content type of the request. This parameter must be set to application/json.

Authorizationstring(Required)

Request authentication. The API uses an Alibaba Cloud Model Studio API key for authentication. Example: Bearer sk-xxxx.

X-DashScope-Ssestring(Optional)

Used to enable streaming output.

  • Only when parameters.enable_interleave=true is this field required to be set to enable.
  • In other cases, it can be omitted or ignored.
Request body

model string (Required)

Model name. Set to wan2.6-image.

input object (Required)

Basic input information.

Properties

messages array (Required)

Array of request content. Only single-turn conversations are supported, that is, one set of role and content parameters is passed in. Multi-turn conversations are not supported.

Properties

rolestring (Required)

The role of the message. This parameter is fixed to user.

contentarray (Required)

Array of message content.

Properties

textstring(Required)

A positive prompt describing the image content, style, and composition you want to generate.

Supports Chinese and English, up to 2,000 characters. Each Chinese character, letter, digit, or symbol counts as one character, and the excess is automatically truncated.

Example: Generate tomato and egg stir-fry in the style of this image.

Note: The content array must contain one and only one object with a text field.

imagestring(Optional)

URL or Base64-encoded string of the input image.

Image constraints:

  • Image formats: JPEG, JPG, PNG (alpha channel not supported), BMP, WebP.
  • Image resolution: The width and height of the image must each be within [240, 8000] pixels.
  • File size: Must not exceed 10 MB.

Image quantity limits:

  • The number of input images depends on the parameters.enable_interleave parameter.

    • When enable_interleave=true (interleaved text-image output), you can input 0 to 1 images.
    • When enable_interleave=false (image editing), you must input 1 to 4 images.

  • When you input multiple images, pass multiple image objects in the content array, with the image order defined by the array sequence.

Supported input formats:

  1. Use a publicly accessible URL

    • Supports HTTP or HTTPS protocols.
    • Example: http://wanx.alicdn.com/material/xxx.jpeg.

  2. Pass a Base64-encoded image string

    • Format: data:{MIME_type};base64,{base64_data}
    • Example: data:image/jpeg;base64,GDU7MtCZzEbTbmRZ... (for illustration only; pass the complete string in practice)
    • For Base64 encoding guidelines, see Image input methods.

parameters object (Optional)

Image processing parameters.

Properties

negative_prompt string (Optional)

A negative prompt describing content you do not want in the image, used to constrain the image.

Supports Chinese and English, up to 500 characters. The excess is automatically truncated.

Example: Low resolution, low quality, distorted limbs, malformed fingers, oversaturated image, wax-like appearance, no facial details, overly smooth, AI-generated look. Chaotic composition. Blurry or distorted text.

size string (Optional)

Output image resolution parameter. Supports two methods: referencing the input image aspect ratio or directly specifying dimensions.

When enable_interleave=false (image editing mode):

  • Method 1: Reference the input image aspect ratio (recommended)

    Available output resolution options: 1K (default), 2K.

    • 1K: Output total pixels close to 1280*1280, with the aspect ratio consistent with the last input image.
    • 2K: Output total pixels close to 2048*2048, with the aspect ratio consistent with the last input image.

  • Method 2: Specify the width and height in pixels of the generated image

    Total pixels between [768768, 20482048], with an aspect ratio range of [1:4, 4:1].

    Actual output pixel values are multiples of 16 close to the specified value.

When enable_interleave=true (interleaved text-image output mode):

  • Method 1: Reference the input image aspect ratio (default method)

    • If the total input image pixels ≤ 1280*1280, the output total pixels and aspect ratio are consistent with the input image.
    • If the total input image pixels > 12801280, the output total pixels are close to 12801280, with the aspect ratio consistent with the input image.
    • If there is no input image, the output is 1280*1280.

  • Method 2: Specify the width and height in pixels of the generated image

    Total pixels between [768768, 12801280], with an aspect ratio range of [1:4, 4:1].

    Actual output pixel values are multiples of 16 close to the specified value.

enable_interleave bool (Optional)

Controls the image generation mode:

  • false: Default value, indicating image editing mode (supports multi-image input and subject consistency generation).

    • Use case: Edit, apply style transfer, or generate subject-consistent images based on 1 to 4 input images.
    • Input: At least one reference image must be provided.
    • Output: Can generate 1 to 4 result images.

  • true: Indicates enabling interleaved text-image output mode (only supports inputting one image or no image).

    • Use case: Generate content combining text and images based on a text description, or perform pure text-to-image generation.

      For pure text-to-image scenarios, we recommend using the wan2.6-t2i model (Tongyi Wan - Text-to-Image V2) first.

    • Input: No image can be provided (text-to-image), or at most one reference image.

    • Output: Generates mixed content containing text and images.

n integer (Optional)

Importantn directly affects cost. Cost = unit price × number of successfully generated images. Confirm model pricing before calling.

Specifies the number of images to generate. The value range and meaning of this parameter depend on the state of enable_interleave (mode switch):

  • When enable_interleave=false (image editing mode):

    • Purpose: Directly controls the number of generated images.
    • Value range: 1 to 4. Default value is 4.
    • We recommend setting this value to 1 during the testing phase for low-cost validation.

  • When enable_interleave=true (interleaved text-image mode):

    • Limit: This parameter defaults to 1 and must be fixed to 1. Setting it to any other value causes an API error.
    • Note: In this mode, use the max_images parameter to control the upper limit of the number of generated images.

max_images integer (Optional)

Importantmax_images affects cost. Cost = unit price × number of successfully generated images. Confirm model pricing before calling.

Only effective in interleaved text-image mode (that is, enable_interleave=true).

  • Purpose: Specifies the maximum number of images the model generates in a single response.
  • Value range: 1 to 5. Default value is 5.
  • Note: This parameter only represents an "upper limit". The actual number of generated images is determined by model inference and may be fewer than the set value (for example, if set to 5, the model may generate only 3 images based on the content).

prompt_extend bool (Optional)

Only effective in image editing mode (that is, enable_interleave = false).

Whether to enable intelligent Prompt rewriting. This feature only optimizes and polishes the positive prompt and does not change the negative prompt.

  • true: Default value, enables intelligent rewriting.
  • false: Disables intelligent rewriting and uses the original prompt.

stream bool (Optional)

Controls whether the result is returned as a stream. In interleaved text-image mode (that is, enable_interleave = true), this must be set to true.

  • false: Default value, non-streaming output.
  • true: Streaming output.

watermark bool (Optional)

Whether to add a watermark label. The watermark is located in the bottom-right corner of the image, with the fixed text "AI Generated".

  • false: Default value, no watermark.
  • true: Add watermark.

seed integer (Optional)

Random number seed. Value range: [0,2147483647].

Using the same seed parameter value keeps the generated content relatively stable. If not provided, the algorithm automatically uses a random seed.

Note: The model generation process is probabilistic. Even with the same seed, identical results cannot be guaranteed each time.

Image editing

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "wan2.6-image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "参考图1的风格和图2的背景，生成番茄炒蛋"
                    },
                    {
                        "image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
                    },
                    {
                        "image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true,
        "watermark": false,
        "n": 1,
        "enable_interleave": false,
        "size": "1K"
    }
}'

Interleaved text-image output (streaming only)

When the synchronous interface enables interleaved text-image output (that is, parameters.enable_interleave = true), only streaming output is supported, and both of the following configurations must be met:

  • Set X-DashScope-Sse to enable.
  • Set parameters.stream to true.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Sse: enable' \
--data '{
    "model": "wan2.6-image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "给我一个3张图辣椒炒肉教程"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "max_images": 3,
        "size": "1280*1280",
        "stream": true,
        "enable_interleave":true
    }
}'

dashscope CLI

export DASHSCOPE_API_KEY="your-api-key"
# 将 {WorkspaceId} 替换为业务空间ID，cn-beijing 替换为对应地域（新加坡: ap-southeast-1, 美东: us-east-1）
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
dashscope image-generation create -m wan2.6-t2i -t "一只可爱的猫"

ImportantThe SDK Expert interactive assistant can accomplish the same development and troubleshooting in natural language. See

DashScope SDK Expert.

For the complete region table, see Base URL overview.

Response parameters

output object

Task output information.

Properties

choices array of object

Output content generated by the model.

Properties

finish_reason string

Reason for task termination.

Non-streaming output scenario: stop when the task stops naturally.

Streaming output scenario: When streaming output is enabled, this parameter indicates whether the data stream has finished transmitting.

  • During transmission: Previous data packets continuously return "finish_reason": "null", indicating that content is still being generated. Continue receiving.
  • At the end of transmission: Only the last JSON structure returns "finish_reason":"stop", indicating that the streaming request has fully completed. Stop receiving.

message object

Message returned by the model.

Properties

rolestring

The role of the message, fixed to assistant.

contentarray

Properties

type string

The output type. Enumerated values: text, image.

text string

Generated text.

image string

URL of the generated image. The image format is PNG.

The link is valid for 24 hours. Download and save the image promptly.

finished bool

Request completion flag.

  • true: Indicates the request is complete.
  • false: Indicates the request is not complete.

usage object

Output statistics. Only successful results are counted.

Properties

image_count integer

Number of generated images.

size string

Resolution of the generated image. Example: 1376*768.

input_tokens integer

Billed by the number of images.

  • In image editing mode, fixed to 0.
  • In interleaved text-image mode, this field counts the number of input text tokens (not billed).

output_tokens integer

Billed by the number of images.

  • In image editing mode, fixed to 0.
  • In interleaved text-image mode, this field counts the number of output text tokens (not billed).

total_tokensinteger

Billed by the number of images.

  • In image editing mode, fixed to 0.
  • In interleaved text-image mode, this field counts the total number of tokens (not billed).

request_idstring

Unique request identifier. Can be used for request tracing and troubleshooting.

codestring

Error code of the failed request. This parameter is not returned when the request succeeds. For more information, see Error codes.

messagestring

Detailed information of the failed request. This parameter is not returned when the request succeeds. For more information, see Error codes.

Successful task execution

Task data (such as task status and image URLs) is retained for only 24 hours and automatically cleared after expiration. Be sure to save the generated images promptly.

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ],
                    "role": "assistant"
                }
            }
        ],
        "finished": true
    },
    "usage": {
        "image_count": 1,
        "input_tokens": 0,
        "output_tokens": 0,
        "size": "1376*768",
        "total_tokens": 0
    },
    "request_id": "a3f4befe-cacd-49c9-8298-xxxxxx"
}

Successful task execution (streaming output)

Task data (such as task status and image URLs) is retained for only 24 hours and automatically cleared after expiration. Be sure to save the generated images promptly.

{"output":{"choices":[{"message":{"content":[{"type":"text","text":"肉"}],"role":"assistant"},"finish_reason":"null"}],"finished":true},"usage":{"total_tokens":571,"image_count":3,"output_tokens":543,"size":"1280*1280","input_tokens":28},"request_id":"d2dcb952-bf91-4a6a-aad5-xxxxxx"}
{"output":{"choices":[{"message":{"content":[{"type":"text","text":"香"}],"role":"assistant"},"finish_reason":"null"}],"finished":true},"usage":{"total_tokens":572,"image_count":3,"output_tokens":544,"size":"1280*1280","input_tokens":28},"request_id":"d2dcb952-bf91-4a6a-aad5-xxxxxx"}
{"output":{"choices":[{"message":{"content":[{"type":"text","text":"交织"}],"role":"assistant"},"finish_reason":"null"}],"finished":true},"usage":{"total_tokens":573,"image_count":3,"output_tokens":545,"size":"1280*1280","input_tokens":28},"request_id":"d2dcb952-bf91-4a6a-aad5-xxxxxx"}
......
{"output":{"choices":[{"message":{"content":[{"type":"image","image":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxxx"}],"role":"assistant"},"finish_reason":"null"}],"finished":true},"usage":{"total_tokens":557,"image_count":3,"output_tokens":529,"size":"1280*1280","input_tokens":28},"request_id":"d2dcb952-bf91-4a6a-aad5-xxxxxx"}
{"output":{"choices":[{"message":{"content":[{"type":"text","text":"趁"}],"role":"assistant"},"finish_reason":"null"}],"finished":true},"usage":{"total_tokens":558,"image_count":3,"output_tokens":530,"size":"1280*1280","input_tokens":28},"request_id":"d2dcb952-bf91-4a6a-aad5-xxxxxx"}
{"output":{"choices":[{"message":{"content":[{"type":"text","text":"热"}],"role":"assistant"},"finish_reason":"null"}],"finished":true},"usage":{"total_tokens":559,"image_count":3,"output_tokens":531,"size":"1280*1280","input_tokens":28},"request_id":"d2dcb952-bf91-4a6a-aad5-xxxxxx"}
{"output":{"choices":[{"message":{"content":[{"type":"text","text":"夹"}],"role":"assistant"},"finish_reason":"null"}],"finished":true},"usage":{"total_tokens":560,"image_count":3,"output_tokens":532,"size":"1280*1280","input_tokens":28},"request_id":"d2dcb952-bf91-4a6a-aad5-xxxxxx"}
{"output":{"choices":[{"message":{"content":[{"type":"text","text":"起"}],"role":"assistant"},"finish_reason":"null"}],"finished":true},"usage":{"total_tokens":561,"image_count":3,"output_tokens":533,"size":"1280*1280","input_tokens":28},"request_id":"d2dcb952-bf91-4a6a-aad5-xxxxxx"}
{"output":{"choices":[{"message":{"content":[{"type":"text","text":"一块"}],"role":"assistant"},"finish_reason":"null"}],"finished":true},"usage":{"total_tokens":562,"image_count":3,"output_tokens":534,"size":"1280*1280","input_tokens":28},"request_id":"d2dcb952-bf91-4a6a-aad5-xxxxxx"}
{"output":{"choices":[{"message":{"content":[{"type":"text","text":"肉"}],"role":"assistant"},"finish_reason":"stop"}],"finished":true},"usage":{"total_tokens":563,"image_count":3,"output_tokens":535,"size":"1280*1280","input_tokens":28},"request_id":"d2dcb952-bf91-4a6a-aad5-xxxxxx"}

Task execution failure

If the task fails for some reason, relevant information is returned, and the code and message fields clearly indicate the cause of the error. See Error codes for troubleshooting.

{
    "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
    "code": "InvalidParameter",
    "message": "num_images_per_prompt must be 1"
}

HTTP asynchronous calls

The process consists of two core steps: "Create task -> Poll for results", as follows:

Step 1: Create a task and obtain the task ID

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

When calling, replace {WorkspaceId} with your actual Workspace ID.

Singapore

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

When calling, replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

Germany (Frankfurt)

POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

When calling, replace {WorkspaceId} with your actual Workspace ID.

Note

  • After the task is created successfully, use the task_id returned by the API to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Use polling to obtain the result.
  • For beginner guidance, see Postman.

Request parameters

Request headers

Content-Typestring(Required)

The content type of the request. This parameter must be set to application/json.

Authorizationstring(Required)

Request authentication. The API uses an Alibaba Cloud Model Studio API key for authentication. Example: Bearer sk-xxxx.

X-DashScope-Asyncstring(Required)

Asynchronous processing configuration parameter. Must be set to enable.

ImportantOmitting this header returns the error: "current user api does not support synchronous calls".

Request body

model string (Required)

Model name.

Example: wan2.6-image

input object (Required)

Basic input information.

Properties

messages array (Required)

Array of request content. Only single-turn conversations are supported, that is, one set of role and content parameters is passed in. Multi-turn conversations are not supported.

Properties

rolestring (Required)

The role of the message. This parameter is fixed to user.

contentarray (Required)

Array of message content.

Properties

textstring(Required)

A positive prompt describing the image content, style, and composition you want to generate.

Supports Chinese and English, up to 2,000 characters. Each Chinese character, letter, digit, or symbol counts as one character, and the excess is automatically truncated.

Example: Generate tomato and egg stir-fry in the style of this image.

Note: The content array must contain one and only one object with a text field.

imagestring(Optional)

URL or Base64-encoded string of the input image.

Image constraints:

  • Image formats: JPEG, JPG, PNG (alpha channel not supported), BMP, WebP.
  • Image resolution: The width and height of the image must each be within [240, 8000] pixels.
  • File size: Must not exceed 10 MB.

Image quantity limits:

  • The number of input images depends on the parameters.enable_interleave parameter.

    • When enable_interleave=true (interleaved text-image output), you can input 0 to 1 images.
    • When enable_interleave=false (image editing), you must input 1 to 4 images.

  • When you input multiple images, pass multiple image objects in the content array, with the image order defined by the array sequence.

Supported input formats:

  1. Use a publicly accessible URL

    • Supports HTTP or HTTPS protocols.
    • Example: http://wanx.alicdn.com/material/xxx.jpeg.

  2. Pass a Base64-encoded image string

    • Format: data:{MIME_type};base64,{base64_data}
    • Example: data:image/jpeg;base64,GDU7MtCZzEbTbmRZ... (for illustration only; pass the complete string in practice)
    • For Base64 encoding guidelines, see Image input methods.

parameters object (Optional)

Image processing parameters.

Properties

negative_prompt string (Optional)

A negative prompt describing content you do not want in the image, used to constrain the image.

Supports Chinese and English, up to 500 characters. The excess is automatically truncated.

Example: Low resolution, low quality, distorted limbs, malformed fingers, oversaturated image, wax-like appearance, no facial details, overly smooth, AI-generated look. Chaotic composition. Blurry or distorted text.

size string (Optional)

Output image resolution parameter. Supports two methods: referencing the input image aspect ratio or directly specifying dimensions.

When enable_interleave=false (image editing mode):

  • Method 1: Reference the input image aspect ratio (recommended)

    Available output resolution options: 1K (default), 2K.

    • 1K: Output total pixels close to 1280*1280, with the aspect ratio consistent with the last input image.
    • 2K: Output total pixels close to 2048*2048, with the aspect ratio consistent with the last input image.

  • Method 2: Specify the width and height in pixels of the generated image

    Total pixels between [768768, 20482048], with an aspect ratio range of [1:4, 4:1].

    Actual output pixel values are multiples of 16 close to the specified value.

When enable_interleave=true (interleaved text-image output mode):

  • Method 1: Reference the input image aspect ratio (default method)

    • If the total input image pixels ≤ 1280*1280, the output total pixels and aspect ratio are consistent with the input image.
    • If the total input image pixels > 12801280, the output total pixels are close to 12801280, with the aspect ratio consistent with the input image.
    • If there is no input image, the output is 1280*1280.

  • Method 2: Specify the width and height in pixels of the generated image

    Total pixels between [768768, 12801280], with an aspect ratio range of [1:4, 4:1].

    Actual output pixel values are multiples of 16 close to the specified value.

enable_interleave bool (Optional)

Controls the image generation mode:

  • false: Default value, indicating image editing mode (supports multi-image input and subject consistency generation).

    • Use case: Edit, apply style transfer, or generate subject-consistent images based on 1 to 4 input images.
    • Input: At least one reference image must be provided.
    • Output: Can generate 1 to 4 result images.

  • true: Indicates enabling interleaved text-image output mode (only supports inputting one image or no image).

    • Use case: Generate content combining text and images based on a text description, or perform pure text-to-image generation.

      For pure text-to-image scenarios, we recommend using the wan2.6-t2i model (Tongyi Wan - Text-to-Image V2) first.

    • Input: No image can be provided (text-to-image), or at most one reference image.

    • Output: Generates mixed content containing text and images.

n integer (Optional)

Importantn directly affects cost. Cost = unit price × number of successfully generated images. Confirm model pricing before calling.

Specifies the number of images to generate. The value range and meaning of this parameter depend on the state of enable_interleave (mode switch):

  • When enable_interleave=false (image editing mode):

    • Purpose: Directly controls the number of generated images.
    • Value range: 1 to 4. Default value is 4.
    • We recommend setting this value to 1 during the testing phase for low-cost validation.

  • When enable_interleave=true (interleaved text-image mode):

    • Limit: This parameter defaults to 1 and must be fixed to 1. Setting it to any other value causes an API error.
    • Note: In this mode, use the max_images parameter to control the upper limit of the number of generated images.

max_images integer (Optional)

Importantmax_images affects cost. Cost = unit price × number of successfully generated images. Confirm model pricing before calling.

Only effective in interleaved text-image mode (that is, enable_interleave=true).

  • Purpose: Specifies the maximum number of images the model generates in a single response.
  • Value range: 1 to 5. Default value is 5.
  • Note: This parameter only represents an "upper limit". The actual number of generated images is determined by model inference and may be fewer than the set value (for example, if set to 5, the model may generate only 3 images based on the content).

prompt_extend bool (Optional)

Only effective in image editing mode (that is, enable_interleave = false).

Whether to enable intelligent Prompt rewriting. This feature only optimizes and polishes the positive prompt and does not change the negative prompt.

  • true: Default value, enables intelligent rewriting.
  • false: Disables intelligent rewriting and uses the original prompt.

watermark bool (Optional)

Whether to add a watermark label. The watermark is located in the bottom-right corner of the image, with the fixed text "AI Generated".

  • false: Default value, no watermark.
  • true: Add watermark.

seed integer (Optional)

Random number seed. Value range: [0,2147483647].

Using the same seed parameter value keeps the generated content relatively stable. If not provided, the algorithm automatically uses a random seed.

Note: The model generation process is probabilistic. Even with the same seed, identical results cannot be guaranteed each time.

curl --location 'https://{WorkspaceId}.cn-beijing.maas.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-image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "参考图1的风格和图2的背景，生成番茄炒蛋"
                    },
                    {
                        "image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
                    },
                    {
                        "image": "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true,
        "watermark": false,
        "n": 1,
        "enable_interleave": false,
        "size": "1K"
    }
}'

curl --location 'https://{WorkspaceId}.cn-beijing.maas.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-image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "给我一个3张图辣椒炒肉教程"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "max_images": 3,
        "size": "1280*1280",
        "enable_interleave":true
    }
}'

Response parameters

output object

Task output information.

Properties

task_id string

Task ID. Valid for queries within 24 hours.

task_status string

Task status.

Enumerated values

  • PENDING: Task is queuing
  • RUNNING: Task is being processed
  • SUCCEEDED: Task executed successfully
  • FAILED: Task failed
  • CANCELED: Task has been canceled
  • UNKNOWN: Task does not exist or the status is unknown

request_idstring

Unique request identifier. Can be used for request tracing and troubleshooting.

codestring

Error code of the failed request. This parameter is not returned when the request succeeds. For more information, see Error codes.

messagestring

Detailed information of the failed request. This parameter is not returned when the request succeeds. For more information, see Error codes.

Successful response

Save the task_id, which is used to query the task status and results.

{
    "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 for troubleshooting.

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Step 2: Query the result by task ID

China (Beijing)

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

When calling, replace {WorkspaceId} with your actual Workspace ID.

Singapore

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

When calling, replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Germany (Frankfurt)

GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

When calling, replace {WorkspaceId} with your actual Workspace ID.

Note

  • Polling recommendation: Image generation takes a long time. We recommend using a polling mechanism with a reasonable query interval (such as 10 seconds) to obtain the result.
  • Task status flow: PENDING (queuing) → RUNNING (processing) → SUCCEEDED (success)/ FAILED (failure).
  • Result link: After the task succeeds, an image link is returned, valid for 24 hours. We recommend downloading it immediately and transferring it to permanent storage (such as Alibaba Cloud OSS).
  • RPS limit: The query API defaults to 20 RPS. For higher-frequency queries or event notifications, we recommend configuring asynchronous task callbacks.
  • More operations: For batch queries, task cancellation, and other operations, see Manage asynchronous tasks.

Request parameters

Request headers

Authorizationstring(Required)

Request authentication. The API uses an Alibaba Cloud Model Studio API key for authentication. Example: Bearer sk-xxxx.

URL path parameters

task_id string(Required)

Task ID.

Query task result

Fully replace {task_id} with the task_id value returned by the API in the previous step. The task_id is valid for queries within 24 hours. Also replace {WorkspaceId} with your actual workspace ID.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

output object

Task output information.

Properties

task_id string

Task ID. Valid for queries within 24 hours.

task_status string

Task status.

Enumerated values

  • PENDING: Task is queuing
  • RUNNING: Task is being processed
  • SUCCEEDED: Task executed successfully
  • FAILED: Task failed
  • CANCELED: Task has been canceled
  • UNKNOWN: Task does not exist or the status is unknown
Status flow during polling:
  • PENDING (queuing) → RUNNING (processing) → SUCCEEDED (success)/ FAILED (failure).
  • The status of the first query is usually PENDING (queuing) or RUNNING (processing).
  • When the status changes to SUCCEEDED, the response contains the URL of the generated image.
  • If the status is FAILED, check the error information and retry.

submit_time string

Task submission time. Format: YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

Task execution time. Format: YYYY-MM-DD HH:mm:ss.SSS.

end_time string

Task completion time. Format: YYYY-MM-DD HH:mm:ss.SSS.

finished bool

Request completion flag.

  • true: Indicates the request is complete.
  • false: Indicates the request is not complete.

choices array of object

Output content generated by the model.

Properties

finish_reason string

Reason for task termination. stop when the task stops naturally.

message object

Message returned by the model.

Properties

rolestring

The role of the message, fixed to assistant.

contentarray

Properties

type string

The output type. Enumerated values: text, image.

text string

Generated text.

image string

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

Output statistics. Only successful results are counted.

Properties

image_count integer

Number of generated images.

size string

Resolution of the generated image. Example: 1376*768.

input_tokens integer

Number of input tokens. Billed by the number of images, currently fixed to 0.

output_tokens integer

Number of output tokens. Billed by the number of images, currently fixed to 0.

total_tokensinteger

Total number of tokens. Billed by the number of images, currently fixed to 0.

request_idstring

Unique request identifier. Can be used for request tracing and troubleshooting.

codestring

Error code of the failed request. This parameter is not returned when the request succeeds. For more information, see Error codes.

messagestring

Detailed information of the failed request. This parameter is not returned when the request succeeds. For more information, see Error codes.

Successful task execution

Task data (such as task status and image URLs) is retained for only 24 hours and automatically cleared after expiration. Be sure to save the generated images promptly.

{
    "request_id": "43d9e959-25bc-4dc7-9888-xxxxxx",
    "output": {
        "task_id": "858cad55-4bdc-4ba3-ae6c-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-12-16 04:21:02.275",
        "scheduled_time": "2025-12-16 04:21:02.304",
        "end_time": "2025-12-16 04:24:46.658",
        "finished": true,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/1xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ]
                }
            },
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/1xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "size": "1376*768",
        "total_tokens": 0,
        "image_count": 2,
        "output_tokens": 0,
        "input_tokens": 0
    }
}

Task execution failure

If the task fails for some reason, relevant information is returned, and the code and message fields clearly indicate the cause of the error. See Error codes for troubleshooting.

{
    "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
    "code": "InvalidParameter",
    "message": "num_images_per_prompt must be 1"
}

DashScope Python SDK

The SDK parameter naming is basically the same as the HTTP API, with the parameter structure encapsulated according to language features.

Since tasks take a long time, the SDK encapsulates the HTTP asynchronous call process at the underlying layer and supports both synchronous and asynchronous calling methods.

The specific duration depends on the number of queuing tasks and service execution conditions. Please wait patiently when obtaining the result.

ImportantMake sure the DashScope Python SDK version is 2.0.1 or later before running the following code. For updates, see Install the SDK.

The region values and API keys of each region are not interchangeable. The following examples use the Beijing region:

China (Beijing)

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1

When calling, replace {WorkspaceId} with your actual Workspace ID.

Singapore

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

When calling, replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1

Germany (Frankfurt)

https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1

When calling, replace {WorkspaceId} with your actual Workspace ID.

The global deployment scope (Frankfurt region) only supports asynchronous calls.

Image editing

Synchronous call

Request example 
import os
import dashscope

# 以下为华北2（北京）地域的配置，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的region取值不同。
client = dashscope.Client(
    # 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx"
    # 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

print("----sync call, please wait a moment----")
job = client.images.generate(
    model='wan2.6-image',
    prompt="参考图1的风格和图2的背景，生成番茄炒蛋",
    # 参考图列表，支持本地文件 如 "file://umbrella1.png"
    image_urls=[
        "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png",
        "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp"
    ],
    negative_prompt="",
    prompt_extend=True,
    watermark=False,
    n=1,
    parameters={"enable_interleave": False},
    size="1K"
)

print(job)
Response example

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

{
    "request_id": "b6a4c68d-3a91-4018-ae96-3cf373xxxxxx",
    "task_id": "127ec645-118f-4884-955d-0eba8dxxxxxx",
    "status": "SUCCEEDED",
    "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_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 1,
        "FAILED": 0
    },
    "usage": {
        "input_tokens": 0,
        "output_tokens": 0,
        "image_count": 1,
        "size": "1376*768",
        "total_tokens": 0
    }
}

Asynchronous call

Request example 
import os
import dashscope
from dashscope.v2 import DashScopeError

# 以下为华北2（北京）地域的配置，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的region取值不同。
client = dashscope.Client(
    # 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx"
    # 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# 创建异步任务
def create_async_task():
    print("Creating async task...")
    job = client.images.jobs.create(
        model="wan2.6-image",
        prompt='参考图1的风格和图2的背景，生成番茄炒蛋',
        # 参考图列表，支持本地文件 如 "file://umbrella1.png"
        image_urls=[
            'https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png',
            'https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp'
        ],
        negative_prompt="",
        prompt_extend=True,
        watermark=False,
        n=1,
        parameters={"enable_interleave": False},
        size="1K"
    )

    print("Task created successfully:", job)
    return job  # 返回任务

# 等待任务完成
def wait_for_completion(task_response):
    print("Waiting for task completion...")
    done = client.images.jobs.wait(task_response)

    if done.succeeded:
        print("Task succeeded!")
        print("Response:", done)
    else:
        raise Exception(f"Task failed with status: {done.status}")

# 获取异步任务信息
def fetch_task_status(task_id):
    print("Fetching task status...")
    snapshot = client.images.jobs.fetch(task_id)

    print("Task status:", snapshot.status)
    print("Response details:", snapshot)

# 取消异步任务
def cancel_task(task_id):
    print("Canceling task...")
    response = client.images.jobs.cancel(task_id)
    print("Task canceled successfully:", response.status)

# 主执行流程
if __name__ == "__main__":
    try:
        task = create_async_task()
        wait_for_completion(task)
    except DashScopeError as e:
        print(f"HTTP返回码：{e.status_code}")
        print(f"错误码：{e.code}")
        print(f"错误信息：{e.message}")
        print("请参考文档：https://help.aliyun.com/zh/model-studio/developer-reference/error-code")
Response example
  1. Response example for creating a task
{
    "request_id": "4fb3050f-de57-4a24-84ff-e37ee5xxxxxx",
    "task_id": "127ec645-118f-4884-955d-0eba8dxxxxxx",
    "status": "PENDING"
}
  1. Response example for querying the task result

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

{
    "request_id": "b2a7fab4-5e00-4b0a-86fe-8b9964xxxxxx",
    "task_id": "127ec645-118f-4884-955d-0eba8xxxxxx",
    "status": "SUCCEEDED",
    "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_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 1,
        "FAILED": 0
    },
    "usage": {
        "input_tokens": 0,
        "output_tokens": 0,
        "image_count": 1,
        "size": "1376*768",
        "total_tokens": 0
    }
}

Interleaved text-image output

Synchronous call (streaming only)

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

# 以下为华北2（北京）地域的URL。请将{WorkspaceId}替换为您的百炼业务空间ID，各地域的URL不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

# 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx"
# 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sync_call_with_stream():
    print("\n========== 同步调用 - 流式图文输出 ==========")

    image_message = Message(
        role="user",
        content=[
            {
                "text": "给我一个3张图辣椒炒肉教程"
            }
        ]
    )

    image_stream_res = ImageGeneration.call(
        model="wan2.6-image",
        api_key=api_key,
        messages=[image_message],
        stream=True,  # 仅支持流式调用
        negative_prompt="",
        enable_interleave=True,
        max_images=3,
        size="1280*1280"
    )

    print("流式输出结果:")
    for stream_res in image_stream_res:
        print(stream_res)

if __name__ == "__main__":
    sync_call_with_stream()
Response example (returned by the HTTP API)

The url is valid for 24 hours. Download the image promptly. The above is the streaming data chunk returned by the HTTP API (the current example code uses the 1.x calling method, whose printed results additionally contain fields such as status_code/code/message).

{"request_id": "5b98e8f3-aeff-4c20-a26c-499a7525axxx", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": [{"type": "text", "text": "辣椒"}]}}], "audio": null, "finished": false}, "usage": {"input_tokens": 28, "output_tokens": 0, "characters": 0, "total_tokens": 28, "image_count": 0, "size": "0*0"}}
{"request_id": "5b98e8f3-aeff-4c20-a26c-499a7525axxx", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": [{"type": "text", "text": "炒"}]}}], "audio": null, "finished": false}, "usage": {"input_tokens": 28, "output_tokens": 1, "characters": 0, "total_tokens": 29, "image_count": 0, "size": "0*0"}}
{"request_id": "5b98e8f3-aeff-4c20-a26c-499a7525axxx", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": [{"type": "text", "text": "肉"}]}}], "audio": null, "finished": false}, "usage": {"input_tokens": 28, "output_tokens": 2, "characters": 0, "total_tokens": 30, "image_count": 0, "size": "0*0"}}

......

{"request_id": "5b98e8f3-aeff-4c20-a26c-499a7525axxx", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "null", "message": {"role": "assistant", "content": [{"type": "text", "text": "。"}]}}], "audio": null, "finished": false}, "usage": {"input_tokens": 28, "output_tokens": 398, "characters": 0, "total_tokens": 426, "image_count": 2, "size": "1280*1280"}}
{"request_id": "5b98e8f3-aeff-4c20-a26c-499a7525axxx", "output": {"text": null, "finish_reason": null, "choices": [{"finish_reason": "stop", "message": {"role": "assistant", "content": [{"type": "image", "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"}]}}], "audio": null, "finished": true}, "usage": {"input_tokens": 28, "output_tokens": 523, "characters": 0, "total_tokens": 551, "image_count": 3, "size": "1280*1280"}}

Asynchronous call

Request example

Note: The stream parameter is not required for asynchronous calls.

import os
import dashscope
from dashscope.v2 import DashScopeError

# 以下为华北2（北京）地域的配置，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域的region取值不同。
client = dashscope.Client(
    # 若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx"
    # 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

def main():
    """异步调用 - 图文输出"""
    print("========== wan2.6-image 异步调用 - 图文输出 ==========")

    # 创建异步任务
    print("---async call, creating task----")
    job = client.images.jobs.create(
        model="wan2.6-image",
        prompt="给我一个3张图的辣椒炒肉教程",
        # 异步调用不需要设置stream参数
        negative_prompt="",
        parameters={"enable_interleave": True, "max_images": 3},
        size="1280*1280"
    )

    print(f"任务创建成功:")
    print(job)

    # 等待任务完成
    print("\n---waiting for task completion----")
    done = client.images.jobs.wait(job)

    if done.succeeded:
        print("任务完成!")
        print(f"结果:")
        print(f"图片URL: {done.image_urls}")
    else:
        print(f"任务失败，状态: {done.status}")

if __name__ == "__main__":
    try:
        main()
    except DashScopeError as e:
        print(f"HTTP返回码：{e.status_code}")
        print(f"错误码：{e.code}")
        print(f"错误信息：{e.message}")
        print("请参考文档：https://help.aliyun.com/zh/model-studio/developer-reference/error-code")
Response example
  1. Response example for creating a task
{
    "request_id": "4fb3050f-de57-4a24-84ff-e37ee5xxxxxx",
    "task_id": "5c67585e-a3be-4943-b04d-c3fbb2xxxxxx",
    "status": "PENDING"
}
  1. Response example for querying the task result

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

{
    "request_id": "997a759b-fbb9-4b35-9a4d-6dab1xxxxxx",
    "task_id": "5c67585e-a3be-4943-b04d-c3fbb2xxxxxx",
    "status": "SUCCEEDED",
    "choices": [
        {
            "finish_reason": "stop",
            "message": {
                "role": "assistant",
                "content": [
                    {
                        "text": "辣椒炒肉是湘菜中的经典，也是许多人心中的家常美味。它以鲜辣爽口、肉质鲜嫩而闻名，制作过程简单，却能带来极致的味蕾享受。今天，我们就来一起学习这道菜的制作方法。\n\n首先，准备好所有食材是成功的第一步。新鲜的猪肉、红绿辣椒、蒜瓣和姜片是必不可少的。将猪肉切成薄片，辣椒切段，蒜和姜切片备用。",
                        "type": "text"
                    },
                    {
                        "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
                        "type": "image"
                    },
                    {
                        "text": "接下来是炒制的关键环节。热锅凉油，放入蒜片和姜片爆香，接着倒入切好的肉片，快速翻炒至肉片变色。肉片炒香后，加入切好的辣椒段，继续翻炒，让辣椒的香气充分释放出来，与肉片的鲜美完美融合。",
                        "type": "text"
                    },
                    {
                        "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
                        "type": "image"
                    },
                    {
                        "text": "最后，加入适量的生抽、老抽、蚝油和少许糖调味，快速翻炒均匀，让每一片肉和辣椒都裹上酱汁。待汤汁收浓，即可关火出锅。这道色香味俱全的辣椒炒肉就大功告成了！",
                        "type": "text"
                    },
                    {
                        "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
                        "type": "image"
                    }
                ]
            }
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 1,
        "FAILED": 0
    },
    "usage": {
        "input_tokens": 29,
        "output_tokens": 477,
        "size": "1280*1280",
        "total_tokens": 506,
        "image_count": 3
    }
}

DashScope Java SDK

The SDK parameter naming is basically the same as the HTTP API, with the parameter structure encapsulated according to language features.

Since tasks take a long time, the SDK encapsulates the HTTP asynchronous call process at the underlying layer and supports both synchronous and asynchronous calling methods.

The specific duration depends on the number of queuing tasks and service execution conditions. Please wait patiently when obtaining the result.

ImportantMake sure the DashScope Java SDK version is 2.22.6 or later before running the following code.

The base_url and API keys of each region are not interchangeable. The following examples use the Beijing region:

China (Beijing)

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1

When calling, replace {WorkspaceId} with your actual Workspace ID.

Singapore

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

When calling, replace {WorkspaceId} with your actual Workspace ID.

US (Virginia)

https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1

Germany (Frankfurt)

https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1

When calling, replace {WorkspaceId} with your actual Workspace ID.

The global deployment scope (Frankfurt region) only supports asynchronous calls.

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.6-image 图像编辑 - 同步调用示例
 */
public class Main {

    static {
        // 以下为北京地域url，各地域的base_url不同
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    // 若没有配置环境变量，请用百炼API Key将下行替换为：apiKey="sk-xxx"
    // 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/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(Arrays.asList(
                        // 支持多图输入，可以提供多张参考图片
                        Collections.singletonMap("text", "参考图1的风格和图2的背景，生成番茄炒蛋"),
                        Collections.singletonMap("image", "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"),
                        Collections.singletonMap("image", "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp")
                )).build();

        // 图像编辑使用普通同步调用，不需要设置stream和enable_interleave
        ImageGenerationParam param = ImageGenerationParam.builder()
                .apiKey(apiKey)
                .model("wan2.6-image")
                .messages(Collections.singletonList(message))
                .n(1)
                .size("1K")
                .negativePrompt("")
                .promptExtend(true)
                .build();

        ImageGeneration imageGeneration = new ImageGeneration();
        ImageGenerationResult result = null;
        try {
            System.out.println("---sync 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. Download the image promptly.

{
    "requestId": "b148327e-830f-414c-a8df-724dec28exxx",
    "usage": {
        "input_tokens": 0,
        "output_tokens": 0,
        "total_tokens": 0,
        "image_count": 1,
        "size": "1376*768"
    },
    "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
    },
    "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.6-image 图像编辑 - 异步调用示例
 */
public class Main {

    static {
        // 以下为北京地域url，各地域的base_url不同
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    // 若没有配置环境变量，请用百炼API Key将下行替换为：apiKey="sk-xxx"
    // 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/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(Arrays.asList(
                        // 支持多图输入，可以提供多张参考图片
                        Collections.singletonMap("text", "参考图1的风格和图2的背景，生成番茄炒蛋"),
                        Collections.singletonMap("image", "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"),
                        Collections.singletonMap("image", "https://img.alicdn.com/imgextra/i3/O1CN01SfG4J41UYn9WNt4X1_!!6000000002530-49-tps-1696-960.webp")
                )).build();

        ImageGenerationParam param = ImageGenerationParam.builder()
                .apiKey(apiKey)
                .model("wan2.6-image")
                .n(1)
                .size("1K")
                .negativePrompt("")
                .promptExtend(true)
                .messages(Arrays.asList(message))
                .build();

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

        String taskId = result.getOutput().getTaskId();
        // 等待任务完成
        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("任务完成结果:");
        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
{
    "status_code": 200,
    "request_id": "9cd85950-2e26-4b2c-b562-1694cf928xxx",
    "code": "",
    "message": "",
    "output": {
        "task_id": "4c861fbe-af89-4a2f-8fc5-4bb15c313xxx",
        "task_status": "PENDING"
    },
    "usage": null
}
  1. Response example for querying the task result

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

{
    "status_code": 200,
    "request_id": "cbdf1424-306e-4a52-82f3-8bf5d8a99xxx",
    "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": "1376*768",
        "total_tokens": 0,
        "image_count": 1
    }
}

Interleaved text-image output

Synchronous call (streaming only)

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 io.reactivex.Flowable;

import java.util.Collections;

/**
 * wan2.6-image 图文输出 - 流式调用示例
 */
public class Main {

    static {
        // 以下为北京地域url，各地域的base_url不同
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    // 若没有配置环境变量，请用百炼API Key将下行替换为：apiKey="sk-xxx"
    // 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void streamCall() throws ApiException, NoApiKeyException, UploadFileException {
        ImageGenerationMessage message = ImageGenerationMessage.builder()
                .role("user")
                .content(Collections.singletonList(
                        Collections.singletonMap("text", "给我一个3张图辣椒炒肉教程")
                )).build();

        // 图文输出必须使用流式调用
        ImageGenerationParam param = ImageGenerationParam.builder()
                .apiKey(apiKey)
                .model("wan2.6-image")
                .messages(Collections.singletonList(message))
                .stream(true) // 必须开启流式输出
                .enableInterleave(true)
                .size("1280*1280")
                .negativePrompt("")
                .maxImages(3)
                .build();

        ImageGeneration imageGeneration = new ImageGeneration();
        try {
            System.out.println("---stream call for image interleave----");
            Flowable<ImageGenerationResult> resultFlowable = imageGeneration.streamCall(param);
            resultFlowable.blockingForEach(result -> {
                System.out.println(JsonUtils.toJson(result));
            });
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            throw new RuntimeException(e.getMessage());
        }
    }

    public static void main(String[] args) {
        try {
            streamCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}
Response example

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

{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":0,"total_tokens":28,"image_count":0,"size":"0*0"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"text","text":"辣椒"}]}}],"finished":false},"status_code":200,"code":"","message":""}
{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":1,"total_tokens":29,"image_count":0,"size":"0*0"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"text","text":"炒"}]}}],"finished":false},"status_code":200,"code":"","message":""}
{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":2,"total_tokens":30,"image_count":0,"size":"0*0"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"text","text":"肉"}]}}],"finished":false},"status_code":200,"code":"","message":""}

......

{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":73,"total_tokens":101,"image_count":0,"size":"0*0"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"text","text":"。"}]}}],"finished":false},"status_code":200,"code":"","message":""}
{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":198,"total_tokens":226,"image_count":1,"size":"1280*1280"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"image","image":"https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"}]}}],"finished":false},"status_code":200,"code":"","message":""}
{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":199,"total_tokens":227,"image_count":1,"size":"1280*1280"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"text","text":"接下来"}]}}],"finished":false},"status_code":200,"code":"","message":""}

......

{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":245,"total_tokens":273,"image_count":1,"size":"1280*1280"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"text","text":"。"}]}}],"finished":false},"status_code":200,"code":"","message":""}
{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":368,"total_tokens":396,"image_count":2,"size":"1280*1280"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"image","image":"https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"}]}}],"finished":false},"status_code":200,"code":"","message":""}
{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":369,"total_tokens":397,"image_count":2,"size":"1280*1280"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"text","text":"最后"}]}}],"finished":false},"status_code":200,"code":"","message":""}

......

{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":416,"total_tokens":444,"image_count":2,"size":"1280*1280"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"text","text":"锅"}]}}],"finished":false},"status_code":200,"code":"","message":""}
{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":417,"total_tokens":445,"image_count":2,"size":"1280*1280"},"output":{"choices":[{"finish_reason":"null","message":{"role":"assistant","content":[{"type":"text","text":"。"}]}}],"finished":false},"status_code":200,"code":"","message":""}
{"requestId":"12c7432c-8028-4289-a97c-4e22df98bxxx","usage":{"input_tokens":28,"output_tokens":541,"total_tokens":569,"image_count":3,"size":"1280*1280"},"output":{"choices":[{"finish_reason":"stop","message":{"role":"assistant","content":[{"type":"image","image":"https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"}]}}],"finished":true},"status_code":200,"code":"","message":""}

Asynchronous call

Request example

Note: The stream parameter is not required for asynchronous calls.

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.6-image 图文输出 - 异步调用示例
 */
public class Main {

    static {
        // 以下为北京地域url，各地域的base_url不同
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    // 若没有配置环境变量，请用百炼API Key将下行替换为：apiKey="sk-xxx"
    // 各地域的API Key不同。获取API Key：https://help.aliyun.com/zh/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", "给我一个3张图的辣椒炒肉教程")
                )).build();

        ImageGenerationParam param = ImageGenerationParam.builder()
                .apiKey(apiKey)
                .model("wan2.6-image")
                .size("1280*1280")
                .enableInterleave(true)
                .maxImages(3)
                .negativePrompt("")
                .messages(Collections.singletonList(message))
                .build();

        ImageGeneration imageGeneration = new ImageGeneration();
        ImageGenerationResult result = null;
        try {
            System.out.println("---async call for image interleave, creating task----");
            result = imageGeneration.asyncCall(param);
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            throw new RuntimeException(e.getMessage());
        }
        System.out.println("任务创建结果:");
        System.out.println(JsonUtils.toJson(result));

        String taskId = result.getOutput().getTaskId();
        // 等待任务完成
        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("任务完成结果:");
        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": "7d6c5760-334b-48c4-9b1e-08ee9c7fexxx",
    "output": {
        "task_id": "1bb9d9fa-bf1a-43dc-b5fe-366c1dc70xxx",
        "task_status": "PENDING"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}
  1. Response example for querying the task result

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

{
    "requestId": "6ed62b00-2225-4fc3-8ee3-2aed0b484xxx",
    "usage": {
        "input_tokens": 29,
        "output_tokens": 471,
        "total_tokens": 500,
        "image_count": 3,
        "size": "1280*1280"
    },
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "text": "辣椒炒肉是湘菜中的经典，也是许多人心中的家常美味。它以鲜辣爽口、肉质鲜嫩而闻名，制作过程简单，却能带来极致的味蕾享受。今天，我们就来一起学习这道菜的制作方法。\n\n首先，准备好所有食材是成功的第一步。新鲜的猪肉、红绿辣椒、蒜瓣和姜片是必不可少的。将猪肉切成薄片，辣椒切段，蒜和姜切片备用。",
                            "type": "text"
                        },
                        {
                            "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
                            "type": "image"
                        },
                        {
                            "text": "接下来是腌制猪肉。将切好的猪肉片放入碗中，加入少许生抽、料酒、淀粉和食用油，用手抓匀，腌制10-15分钟。这样处理过的肉片会更加滑嫩入味。",
                            "type": "text"
                        },
                        {
                            "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
                            "type": "image"
                        },
                        {
                            "text": "最后，热锅凉油，放入腌制好的肉片快速滑炒至变色，盛出备用。锅中留底油，放入蒜片和姜片爆香，再加入辣椒段翻炒出香味。随后倒入肉片，加入生抽、老抽、少许糖和蚝油，快速翻炒均匀，撒上葱花即可出锅。",
                            "type": "text"
                        },
                        {
                            "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ],
        "task_id": "1bb9d9fa-bf1a-43dc-b5fe-366c1dc70836",
        "task_status": "SUCCEEDED",
        "finished": true,
        "submit_time": "2026-01-16 18:26:32.082",
        "scheduled_time": "2026-01-16 18:26:32.133",
        "end_time": "2026-01-16 18:28:41.748"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Limitations

  • Data retention: The task task_id and image url are retained for only 24 hours. They cannot be queried or downloaded after expiration.
  • Content moderation: Both the input prompt and the output image go through content safety moderation. Requests containing non-compliant content return the error "IPInfringementSuspect" or "DataInspectionFailed". For more information, see Error codes.

Billing and rate limiting

  • For the model free quota and billing unit price, see Model pricing.
  • For model rate limits, see Wan.
  • Billing description: Billed by the number of images successfully generated. Failed model calls or processing errors incur no fees and do not consume the new user free quota.

Error codes

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

FAQ

Q: Why does the code example fail to run?

A: Upgrade your SDK to the latest version. For updates, see Install the SDK.

Previous：Wan2.7 - image generation and editingNext：Wanxiang – General Image Editing 2.5