Virtual Model API Reference

Related Guide: Virtual Model Generation

This document applies only to the Chinese mainland (Beijing) region. You must use an API key from this region.
The wanx-virtualmodel and virtualmodel-v2 models are available for a free trial only. After the free quota is exhausted, you cannot call these models, and paid usage is not supported. For alternatives, see Image editing - Qwen or Image Editing - Wanxiang 2.1.

Model Overview

Wanx-Virtual Model intelligently generates images from uploaded product display photos of real people or mannequins, replacing both the model and background with desired content. It uses virtual models to showcase products more elegantly and diversely while preserving the original pose. The model supports a wide range of products that interact with models, such as small handheld items, clothing, footwear, and accessories.

Model Version

Model Name

Model Description

Virtual Model

(V1)

wanx-virtualmodel

Supports uploading real model photos.

Generated image short side: 512 pixels or 1024 pixels.

Virtual Model V2

(V2)

virtualmodel-v2

Supports uploading real person and mannequin photos.
Generated image short side: 1024 pixels or 2048 pixels.
Supports changing resolution. Selectable aspect ratios: original ratio, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16, 1:2.
Supports flexible control over background reference image weight.
More accurate text-guided effects.

Model Name	Billing Price	Rate Limit (shared by Alibaba Cloud account and RAM user)		Free Quota(View)
Model Name	Billing Price	Task Submission API RPS Limit	Number of Simultaneously Processing Tasks	Free Quota(View)
wanx-virtualmodel	Currently for free trial only. After the free quota is used, you cannot invoke them. For alternative solutions, see Image Editing - Qianwen or Image Editing - Wanx 2.1.	2	1	500 images
virtualmodel-v2		2	1	500 images

Prerequisites

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

HTTP Calls

To reduce waiting time and prevent request timeouts, the service uses asynchronous invocation. Make two requests:

Create a task: First, send a request to create a text-to-image task. This request returns a task ID.
Query results by task ID: Use the task ID obtained in the previous step to query the model generation results.

Step 1: Create a task to obtain a task ID

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/virtualmodel/generation Replace {WorkspaceId} with your actual workspace ID.

Note: Unless otherwise specified, the following parameters are supported in Virtual Model V1 and V2.

Request Headers

AuthorizationstringRequiredUse an Alibaba Cloud Model Studio API key or a DashScope API key. Example: Bearer d1xxx2a.X-DashScope-AsyncstringRequiredWhether to use asynchronous invocation. HTTP supports only asynchronous invocation. Set it to enable.Content-TypestringRequiredThe request content type. It is fixed as application/json.

Request Body

modelstringRequiredThe model to invoke.inputobjectRequiredBasic information about the input image, such as its URL.

Properties

base_image_url stringRequiredThe URL of the original product display image featuring a real person.The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.Image requirements:

Formats: JPEG, JPG, PNG, WEBP.
Resolution: At least 256×256 pixels and no more than 4096×4096 pixels. The face area must be at least 128×128 pixels.
Aspect ratio: Greater than 1:2 and less than 2:1.
Size: No more than 5 MB.
The URL must not contain Chinese characters.

Real Person Image Example

mask_image_url stringRequiredThe URL of the mask image corresponding to the original image and specifying the area to retain. This is a black-and-white image (0, 255), where white indicates the main product area.The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.Image requirements:

Formats: JPEG, JPG, PNG, WEBP.
Resolution: Must match the resolution of the image specified by the base_image_url parameter.
Aspect ratio: Greater than 1:2 and less than 2:1.
Size: No more than 5 MB.
The URL must not contain Chinese characters.

Mask Image Example

predefined_face_id string OptionalThe ID of a preset character. Used only in V1.

Enumeration Examples

girl1

girl2

girl3

boy1

boy2

boy3

face_image_url string OptionalThe URL of the character image to replace.The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.Image requirements:

Formats: JPEG, JPG, PNG, WEBP.
Resolution: The long side must not exceed 2048 pixels, and the face area must be greater than 128×128 pixels.
Size: We recommend no more than 5 MB.

This parameter has lower priority than the predefined_face_id parameter.prompt stringRequiredA description of the background environment and the full-body appearance of the model in the generated image.Supports Chinese and English. Maximum length: 100 characters.Example: A young woman wearing white shorts, minimalist color palette, long shot, two-color effect, dark silver and light pink.face_prompt stringRequiredA description of the generated character’s face. Supports Chinese and English. Maximum length: 100 characters.Example: A young woman, beautiful face, best quality.background_image_url string OptionalThe URL of the background environment reference image.The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.Image requirements:

Formats: JPEG, JPG, PNG, WEBP.
Resolution: The long side must not exceed 4096 pixels.
Aspect ratio: Less than or equal to 2.
Size: No more than 5 MB.

bgstyle_scale float OptionalControls the weight of the background reference image. Used only in V2.Valid values: 0.0 to 1.0. Default value: 0.7.A larger value indicates a greater degree of reference.realPerson bool OptionalSpecifies whether the input image features a real person. Used only in V2.

true: Default value. The input image features a real person.
false: The input image features a mannequin or is not a real person.

style string OptionalThe style of the generated image. Used only in V2.Valid values: ["", "portrait"]. Default value: portrait.Description: Portrait mode adds depth of field to highlight the subject.seed integer OptionalControls the generation seed. Used only in V2.Valid values: -1 to 10000000. Default value: -1, which means the system randomly generates a seed.

Seed represents the random seed value. -1 means the system randomly generates a value. Values from 0 to 10000000 let you specify the random seed value. Using the same seed produces identical results.

aspect_ratio String OptionalThe aspect ratio of the generated image. Used only in V2.

Enumeration Values

Available aspect ratios:

Unchanged (default)
2:1
16:9
4:3
1:1
3:4
9:16
1:2

parametersobjectOptional

Properties

n Integer OptionalThe number of images to generate. Valid values: 1 to 4. Default value: 1.short_side_size stringRequiredThe short side size of the generated image, in pixels. The generated image maintains the same aspect ratio as the input image.V1 valid values: 512 and 1024.V2 valid values: 1024 and 2048.

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/virtualmodel/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx-virtualmodel",
  "input": {
    "base_image_url": "https://huarong123.oss-cn-hangzhou.aliyuncs.com/image/%E7%9C%9F%E4%BA%BA%E6%A8%A1%E7%89%B9%E5%AE%9E%E6%8B%8D-%E5%A5%B3%20%281%29.jpeg",
    "mask_image_url": "https://huarong123.oss-cn-hangzhou.aliyuncs.com/image/image.jpg",
    "prompt": "A young woman, wearing white shorts, minimalist color palette, long shot, two-color effect (dark silver and light pink)",
    "face_prompt": "Young woman, beautiful face, highest quality"
  },
  "parameters": {
    "short_side_size": "512",
    "n": 1
  }
}'

Response

outputobjectThe task output information.

Properties

task_id stringThe task ID.task_status stringThe task status.

PENDING: Queued
RUNNING: Processing
SUSPENDED: Suspended
SUCCEEDED: Successful
FAILED: Failed
UNKNOWN: Task does not exist or status is unknown

codestringThe error code of the API. This parameter is not returned for successful API requests.messagestringThe error message of the API. This parameter is not returned for successful API requests.request_idstringThe unique ID of the request. Use it to trace request details and troubleshoot issues.

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

Step 2: Query results by task ID

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} Replace {WorkspaceId} with your actual workspace ID.

Request Headers

AuthorizationstringRequiredUse an Alibaba Cloud Model Studio API key or a DashScope API key. Example: Bearer d1xxx2a.

URL Path Parameters

task_idstringRequiredThe task ID.

Obtain task results

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

Response

outputobjectThe task output information.

Properties

task_id stringThe task ID.task_status stringThe task status.

PENDING: Queued
RUNNING: Processing
SUSPENDED: Suspended
SUCCEEDED: Successful
FAILED: Failed
UNKNOWN: Task does not exist or status is unknown

resultsarray objectA list of task results, including image URLs.

Properties

url stringThe URL of the image generated by the model.

task_metrics objectTask metrics.

Properties

TOTAL integerThe total number of tasks.SUCCEEDED integerThe number of successful tasks.FAILED integerThe number of failed tasks.

submit_time stringThe task submission time.scheduled_time stringThe scheduled task execution time.end_time stringThe task completion time.result_url stringThe URL of the output image.codestringThe error code for failed task execution.messagestringThe detailed error message for failed task execution.

usageobjectOutput statistics.

Properties

image_count integerThe number of images generated by the model.

request_idstringThe unique ID of the request. Use it to trace request details and troubleshoot issues.

Successful Task Execution
Failed Task Execution

Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.

{
    "request_id": "f24149fe-4722-9763-xxxxxx",
    "output": {
        "task_id": "9d62befa-0139-4e4d-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-04-24 10:51:35.004",
        "scheduled_time": "2025-04-24 10:51:35.033",
        "end_time": "2025-04-24 10:51:59.424",
        "results": [
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/test_1.png"
            },
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/test_2.png"
            }
        ],
        "task_metrics": {
            "TOTAL": 2,
            "SUCCEEDED": 2,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 2
    }
}

{
  "request_id": "f24149fe-4722-9763-xxxxxx",
  "output": {
    "task_id": "9d62befa-0139-4e4d-xxxxxx",
    "task_status": "FAILED",
    "submit_time": "2024-05-16 13:50:xx.xxx",
    "scheduled_time": "2024-05-16 13:50:xx.xxx",
    "end_time": "2024-05-16 13:50:xx.xxx",
    "code": "InvalidImageResolution",
    "message": "The input image resolution is too large or small"
  },
  "usage": {
    "image_num": 0
  }
}

Error codes

If the model call fails and returns an error message, see Error codes for resolution. This API also returns specific status codes, as follows.

HTTP status code	API error code (code)	API error message (message)	Description
400	InvalidFile.Content	The input image has no human body or has unclear human body. Please upload other image	The input image contains no human body.
400	InvalidParameter	The request is missing required parameters or in a wrong format, please check the parameters that you send.	The input parameter format is incorrect.
400	InvalidURL	The request URL is invalid, please check the request URL is available and the request image format is one of the following types: JPEG, JPG, PNG, BMP, and WEBP.	The input image failed to download. Check your network or input format.
400	InvalidFile.Resolution	The image resolution is invalid, please make sure that the aspect ratio is smaller than 2.0, and largest length of image is smaller than 4096	The uploaded image size does not meet the requirements.
500	InternalError.Algo	An internal error occurs during computation, please try this model later.	Algorithm running error.

​Model Overview

​Prerequisites

​HTTP Calls

​Step 1: Create a task to obtain a task ID

Request Headers

Request Body

Response

​Step 2: Query results by task ID

Request Headers

URL Path Parameters

Response

​Error codes

Model Overview

Prerequisites

HTTP Calls

Step 1: Create a task to obtain a task ID

Step 2: Query results by task ID

Error codes