DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio API Reference (Models) Image Generation Creative Tools Virtual Model

Virtual Model API Reference

Updated at:
Copy as MD
Product
My Favorites

This topic describes the input and output parameters of the Wanx-Virtual Model. This 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.

Related Guide: Virtual Model Generation

Important

  • 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 NameBilling PriceRate Limit (shared by Alibaba Cloud account and RAM user)

Free Quota(View)

Task Submission API RPS LimitNumber of Simultaneously Processing Tasks

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

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

AuthorizationstringRequired

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

X-DashScope-AsyncstringRequired

Whether to use asynchronous invocation. HTTP supports only asynchronous invocation. Set it to enable.

Content-TypestringRequired

The request content type. It is fixed as application/json.

Request Body

modelstringRequired

The model to invoke.

inputobjectRequired

Basic information about the input image, such as its URL.

Properties

base_image_url stringRequired

The 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

image

mask_image_url stringRequired

The 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

image.png

predefined_face_id string Optional

The ID of a preset character. Used only in V1.

Enumeration Examples

  • girl1
image
  • girl2
image
  • girl3
image
  • boy1
image
  • boy2
image
  • boy3
image

face_image_url string Optional

The 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 stringRequired

A 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 stringRequired

A 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 Optional

The 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 Optional

Controls 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 Optional

Specifies 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 Optional

The 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 Optional

Controls 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 Optional

The 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 Optional

The number of images to generate. Valid values: 1 to 4. Default value: 1.

short_side_size stringRequired

The 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
  }
}'

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": "virtualmodel-v2",
  "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",
    "background_image_url": "https://huarong123.oss-cn-hangzhou.aliyuncs.com/image/%E8%99%9A%E6%8B%9F%E6%A8%A1%E7%89%B9%E7%94%9F%E6%88%90%E8%83%8C%E6%99%AF%E5%9B%BE.png",
    "prompt": "a beautiful chinese woman stands in front of a plain white background",
    "face_prompt": "a beautiful chinese woman, good face, best face, best quality"
  },
  "parameters": {
      "short_side_size": "1024",
      "n": 1
  }
}'

Response

outputobject

The task output information.

Properties

task_id string

The task ID.

task_status string

The task status.

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

codestring

The error code of the API. This parameter is not returned for successful API requests.

messagestring

The error message of the API. This parameter is not returned for successful API requests.

request_idstring

The 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"
}

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

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

AuthorizationstringRequired

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

URL Path Parameters

task_idstringRequired

The 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

outputobject

The task output information.

Properties

task_id string

The task ID.

task_status string

The task status.

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

resultsarray object

A list of task results, including image URLs.

Properties

url string

The URL of the image generated by the model.

task_metrics object

Task metrics.

Properties

TOTAL integer

The total number of tasks.

SUCCEEDED integer

The number of successful tasks.

FAILED integer

The number of failed tasks.

submit_time string

The task submission time.

scheduled_time string

The scheduled task execution time.

end_time string

The task completion time.

result_url string

The URL of the output image.

codestring

The error code for failed task execution.

messagestring

The detailed error message for failed task execution.

usageobject

Output statistics.

Properties

image_count integer

The number of images generated by the model.

request_idstring

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

Successful 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
    }
}

Failed Task Execution

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

Previous：Portrait style repaintNext：Footwear model