Skip to content

1. Model Description

Task data (such as task status, image URLs, etc.) will only be retained for 24 hours and will be automatically cleared after expiration. Please be sure to save the generated images in a timely manner.

2. Request Protocol

https

Parameter Name Type Description
anthorization string Authentication

3. Details of Functional Interfaces

3.1 Synchronous Image Generation

3.1.1 Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/wan/image/sync/generation

3.1.2 Request Header

Parameter Name Field Type Required or not default value Description
Content-Type string Yes - Request content type. This parameter must be set to application/json.
Authorization string Yes - Bearer

3.1.3 Request Body Parameters

Parameter Name Field Type Required or not default value Description
input object Yes - Basic information entered.
input.messages array Yes - An array containing the request content. Currently, only single-turn conversation is supported, which means you only need to pass one set of role and content parameters, and multi-turn conversations are not supported.
input.messages[].role string Yes - The role of the message. This parameter is fixedly set to user.
input.messages[].content array Yes - Array of message contents.
input.messages[].content[].text
 string
 No - Enter your prompt here. Both Chinese and English are supported. The maximum length is 5000 characters, with each Chinese character, letter, numeral or symbol counted as one character; any content exceeding the limit will be truncated automatically.
input.messages[].content[].image
 string
 No - Enter the URL or Base64 encoded string of the image. Image restrictions: - Image formats: JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP. - Image resolution: both the width and height of the image range from 240 to 8000 pixels, and the aspect ratio ranges from 1:8 to 8:1. - File size: no more than 20MB. Limit on the number of images: - 0 to 9 images can be passed in. - When multiple images are input, multiple contentobjects need to be passed in the imagearray, and the image order shall be defined according to the array order. Supported input formats: 1. Use a publicly accessible URL - HTTP or HTTPS protocol is supported. - Example value: http://wanx.alicdn.com/material/xxx.jpeg. 2. Pass the string of Base64-encoded image - Format: data:{MIME_type};base64,{base64_data} - Example: data: image/jpeg;base64, GDU7MtCZzEbTbmRZ. ..(for illustration only, the complete string shall be passed in practice)
parameters object No - Model parameter configuration.
parameters.bbox_list array[array[array[integer]]] No - Interactively edit the box selection area. - Correspondence rule: The length of the list must be consistent with 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](x of top-left corner, y of top-left corner, x of bottom-right corner, y of bottom-right corner), using the absolute pixel coordinates of the original image, with the top-left corner coordinate set to (0,0). - Restriction: A single image supports a maximum of 2 bounding boxes. Example: Input 3 images, where the 2nd image has no bounding boxes, and the 1st image has two bounding boxes:[[[0,0, 12,12], [25,25,100,100]], [], [[10,10,50,50]]]
parameters.enable_sequential boolean No false Image generation control mode: - false: default value. - true: enable batch image output mode.
parameters.size
 string
 No 2K Regarding the output image resolution parameter, the following two methods are supported and cannot be mixed: Model: wan2.7-image-pro - Method 1: Specify the resolution of the output image (recommended)- Supports three specifications: 1K, 2K (default), and 4K - Scope of application: - Text-to-image (no image input, non-collage generation): 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: - When an image is input: the output aspect ratio is consistent with the input image (the last one when multiple images are input), and is scaled to the selected resolution. - When no image is input: the output is a square. - Method 2: Specify the width and height pixel values of the generated image - Text-to-image: the total pixels are between [768 768,4096 4096], and the aspect ratio ranges from [1:8,8:1]. - Other scenarios: Total pixels range from [768 768,2048 2048], with aspect ratio ranging from [1:8,8:1]. Model: wan2.7-image - Method 1: Specify the resolution of the output image (recommended)- Supports two specifications: 1K and 2K (default), 4K is not supported. - Method 2: Specify the width and height pixel values of the generated image - In all scenarios, the total pixels range from [768 768,2048*2048], and the aspect ratio ranges from [1:8,8:1]. There may be a slight difference between the pixel value of the output image and the specified pixel value.
parameters.n integer No Close the gallery: 1; Enable the gallery: 12 Important n directly affects the cost. Cost = Unit Price × Number of successfully generated images. Please confirm the model price before calling. - When the group image mode is disabled, this value represents the number of generated images, with a value range of 1-4, default is 1; - When the group image mode is enabled, this value represents the maximum number of generated images, with a value range of 1-12, default is 12. The actual number is determined by the model and will not exceed n.
parameters.thinking_mode boolean No true Whether to enable the thinking mode, which defaults to true (enabled). This setting only takes effect when the group image mode is disabled and no image input is provided. When enabled, the model will enhance its reasoning ability to improve the quality of the generated images, but this will increase the generation time.
parameters.color_palette array No - Custom color theme: an object array containing colors (hex) and ratios, which needs to include 3 to 10 colors, and 8 colors are recommended. This option is only available when the group image mode (enable_sequential= false) is disabled.
parameters.color_palette[].hex string (when using color_palette) - A color value in hexadecimal (HEX) format.
parameters.color_palette[].ratio string (when using color_palette) - The percentage of each color shall be accurate to two decimal places (e. g. "25.00%"). The sum of all ratio values must be exactly 100.00%.
parameters.watermark bool No false Whether to add a watermark, which is located at the bottom right corner of the image with the fixed text "AI-generated". - false: default value, no watermark added. - true: watermark added.
parameters.seed integer No - Random number seed, value range[0,2147483647]. Using the same seedparameter value can keep the generated content relatively stable. If not provided, the algorithm will automatically use a random number seed. Note: The model generation process is probabilistic, so even if the same seedis used, it cannot be guaranteed that the generation result will be completely consistent every time.

3.1.4 Response Parameters

Parameter Name Field Type Description
output object Task output information.
output.choices array The output content generated by the model.
output.choices[].finish_reason string The reason for task termination. In case of natural termination, it is stop.
output.choices[].message object The message returned by the model.
output.choices[].message.role string The role of the message is fixed as assistant.
output.choices[].message.content array Array of message contents.
output.choices[].message.content[].type string The output type is fixed as image.
output.choices[].message.content[].image string Generate the URL of the image in PNG format. The link is valid for 24 hours, please download and save the image in time.
output.finished boolean Indicates whether the task is completed. - true: The task has been completed. - false: The task has not been completed.
usage object Output information statistics. Only successful results are counted.
usage.image_count integer The number of images to be generated.
usage.size string The resolution of the generated image. Example value: 1376*768.
usage.input_tokens integer Number of input tokens (no charge). Charges are based on the number of images.
usage.output_tokens integer Number of output tokens (no charge). Charges are based on the number of images.
usage.total_tokens integer Total number of tokens (non-charged). Charges are calculated based on the number of images.
request_id string A unique identifier for the request, which can be used for tracing request details and troubleshooting issues.
code string The error code for a failed request. This parameter will not be returned when the request succeeds.
message string Detailed information about the failed request. This parameter will not be returned when the request succeeds.

3.1.5 Request Example

Text-to-Image:

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/wan/image/sync/generation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_AK}' \
--data '{
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {"text": "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵"}
        ]
      }
    ]
  },
  "parameters": {
    "size": "2K",
    "n": 1,
    "watermark": false,
    "thinking_mode": true
  }
}'

Image Editing:

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/wan/image/sync/generation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_AK}' \
--data '{
  "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": "把图2的涂鸦喷绘在图1的汽车上"}
        ]
      }
    ]
  },
  "parameters": {
    "size": "2K",
    "n": 1,
    "watermark": false
  }
}'

Interactive Editing:

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/wan/image/sync/generation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_AK}' \
--data '{
  "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": "把图1的闹钟放在图2的框选的位置，保持场景和光线融合自然"}
        ]
      }
    ]
  },
  "parameters": {
    "bbox_list": [[],[[989, 515, 1138, 681]]],
    "size": "2K",
    "n": 1,
    "watermark": false
  }
}'

Gallery Generation:

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/wan/image/sync/generation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_AK}' \
--data '{
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {"text": "电影感组图，记录同一只流浪橘猫，特征必须前后一致。第一张：春天，橘猫穿梭在盛开的樱花树下；第二张：夏天，橘猫在老街的树荫下乘凉避暑；第三张：秋天，橘猫踩在满地的金色落叶上；第四张：冬天，橘猫在雪地上走留下足迹。"}
        ]
      }
    ]
  },
  "parameters": {
    "enable_sequential": true,
    "n": 4,
    "size": "2K"
  }
}'

3.1.6 Response Example

Task execution succeeded:

{
  "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 exception:

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

3.2 Asynchronous Image Task Creation

Applicable to time-consuming tasks. Please save the task_idafter successful creation, and query the status and results in accordance with Section 3.3. The validity period for querying the task_idis 24 hours.

The platform will automatically set X-DashScope-Async: enablewhen switching to a different supplier, so users do not need to pass this header.

3.2.1 Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/wan/image/async/generation

3.2.2 Request Header

Parameter Name Field Type Required or not default value Description
Content-Type string Yes - Request content type. This parameter must be set to application/json.
Authorization string Yes - Bearer

3.2.3 Request Body Parameters

Same as §3.1.3

3.2.4 Response Parameters

Parameter Name Field Type Description
output object Task output information.
output.task_id string Task ID. Valid for 24 hours.
output.task_status string Task status. Enumerated values: - PENDING: Task queued - RUNNING: Task in progress - SUCCEEDED: Task executed successfully - FAILED: Task execution failed - CANCELED: Task canceled - UNKNOWN: Task does not exist or status is unknown
request_id string A unique identifier for the request, which can be used for tracing request details and troubleshooting issues.
code string Error code for a failed request. This parameter will not be returned when the request succeeds.
message string Detailed information about the failed request. This parameter will not be returned when the request succeeds.

3.2.5 Request Example

Text-to-Image:

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/wan/image/async/generation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_AK}' \
--data '{
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {"text": "一间有着精致窗户的花店，漂亮的木质门，摆放着花朵"}
        ]
      }
    ]
  },
  "parameters": {
    "size": "2K",
    "n": 1,
    "watermark": false,
    "thinking_mode": true
  }
}'

The bodies for image editing, interactive editing, and image group generation are the same as the corresponding examples in Section 3.1.5, with only the URL changed to the asynchronous creation address of this section.

3.2.6 Response Example

Success response:

{
  "output": {
    "task_status": "PENDING",
    "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
  },
  "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Exception Response:

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

3.3 Image Query Task

Replace{taskId}entirely with the task_id returned by the asynchronous creation interface. This follows the same path as the existing Wan video task query.

State transition during polling:

  • PENDING (Queued) → RUNNING (Processing) → SUCCEEDED (Succeeded) / FAILED (Failed).

  • The status of the initial query is usually PENDING (queued) or RUNNING (processing).

  • When the status changes to SUCCEEDED, the response will contain the URL of the generated image.

  • If the status is FAILED, please check the error message and try again.

3.3.1 Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/wan/tasks/{taskId}

3.3.2 Request Header / Path Parameters

Parameter Name Field Type Required or not default value Description
Authorization string Yes - Bearer
taskId string Yes - Task ID.

3.3.3 Response Parameters

Parameter Name Field Type Description
request_id string A unique identifier for the request, which can be used for tracing request details and troubleshooting issues.
output object Task output information.
output.task_id string Task ID. Valid for 24 hours upon query.
output.task_status
 string Task status. Enumerated values: - PENDING: Task is queued - RUNNING: Task is being processed - SUCCEEDED: Task executed successfully - FAILED: Task execution failed - CANCELED: Task has been canceled - UNKNOWN: Task does not exist or status is unknown
output.submit_time string Task submission time. The time zone is UTC+ 8, and the format is YYYY-MM-DD HH: mm: ss. SSS.
output.scheduled_time string Task execution time. The time zone is UTC+ 8, and the format is YYYY-MM-DD HH: mm: ss. SSS.
output.end_time string Task completion time. The time zone is UTC+ 8, and the format is YYYY-MM-DD HH: mm: ss. SSS.
output.finished boolean Indicates whether the task is completed. - true: The task has been completed. - false: The task has not been completed.
output.choices array The output content generated by the model.
output.choices[].finish_reason string The reason for task termination; when it ends naturally, it is stop.
output.choices[].message object The message returned by the model.
output.choices[].message.role string The role of the message is fixed as assistant.
output.choices[].message.content array Array of message contents.
output.choices[].message.content[].type string The output type, whose enumeration values are text and image.
output.choices[].message.content[].text string Generated text.
output.choices[].message.content[].image string Generate the URL of the image in PNG format. The link is valid for 24 hours, please download and save the image in time.
usage object Output information statistics. Only successful results are counted.
usage.image_count integer The number of images to be generated.
usage.size string The resolution of the generated image. Example value: 1376*768.
usage.input_tokens integer Number of input tokens (no charge). Charges are based on the number of images.
usage.output_tokens integer Number of output tokens (no charge). Charges are based on the number of images.
usage.total_tokens integer Total number of tokens (non-charged). Charges are calculated based on the number of images.
code string The error code for a failed request. This parameter will not be returned when the request succeeds.
message string Detailed information about the failed request. This parameter will not be returned when the request succeeds.

3.3.4 Request Example

curl -X GET 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/wan/tasks/{taskId}' \
--header 'Authorization: Bearer {YOUR_AK}'

3.3.5 Response Example

Task execution succeeded:

{
  "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 exception:

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