虚拟模特,虚拟模特生成-大模型服务平台百炼(Model Studio)-阿里云帮助中心

本文介绍万相-虚拟模特模型的输入输出参数。该模型可以对上传的真人或者人台实拍商品展示图进行智能生成，将其中的模特和背景替换为心仪的内容。在保持人物姿态不变的情况下，使用虚拟模特对商品进行更加精美、多样的展示。同时支持各种与模特产生互动的商品，如手持小商品、服装、鞋靴、配饰等。

相关指南：虚拟模特生成

重要

本文档仅适用于华北2（北京）地域，且必须使用该地域的API Key。
wanx-virtualmodel、virtualmodel-v2 模型当前仅提供免费体验，免费额度用完后不可调用且不支持付费，推荐参考图像编辑-千问或图像编辑-万相2.1获取替代方案。

模型概览

万相-虚拟模特可以对上传的真人实拍商品展示图进行智能生成，将其中的模特和背景替换为心仪的内容，在保持人物姿态不变的情况下，使用虚拟模特对商品进行更加精美、多样的展示。支持各种与模特产生互动的商品，如手持小商品、服装、鞋靴、配饰等。

模型版本

模型名称

模型简介

虚拟模特

（V1版本）

wanx-virtualmodel

支持真人实拍图上传

生成的图片短边：512像素或1024像素

虚拟模特V2

（V2版本）

virtualmodel-v2

支持真人、人台实拍图上传
生成的图片短边为：1024像素或2048像素
支持改变分辨率，生成图片长宽比可选择：比例不变、2:1、16:9、4:3、1:1、3:4、 9:16、1:2。
支持背景参考图权重自由控制
文本引导效果更准确

模型名称	计费单价	限流（主账号与RAM子账号共用）	免费额度（查看）
wanx-virtualmodel	目前仅供免费体验。免费额度用完后不可调用，推荐参考图像编辑-千问或图像编辑-万相2.1获取替代方案。	2	1	500张
virtualmodel-v2

模型名称

计费单价

限流（主账号与RAM子账号共用）

免费额度（查看）

任务下发接口RPS限制

同时处理中任务数量

wanx-virtualmodel

目前仅供免费体验。

免费额度用完后不可调用，推荐参考图像编辑-千问或图像编辑-万相2.1获取替代方案。

500张

virtualmodel-v2

前提条件

您需要已获取与配置 API Key并配置API Key到环境变量。请将示例代码中的 DASHSCOPE_API_HOST 替换为获取的 API Host。

HTTP调用

为了减少等待时间并且避免请求超时，服务采用异步方式提供。您需要发起两个请求：

创建任务：首先发送一个请求创建文生图任务，该请求会返回任务ID。
根据任务ID查询结果：使用上一步获得的任务ID，查询模型生成的结果。

步骤1：创建任务获取任务ID

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

调用时请将{WorkspaceId}替换为真实的业务空间ID。

注意：若无特殊说明，下面的参数支持在虚拟模特模型V1版本和V2版本中使用。

请求头（Headers）

Authorizationstring必选

推荐您使用阿里云百炼API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。

X-DashScope-Asyncstring必选

是否使用异步调用。HTTP只支持异步调用，设置为enable。

Content-Typestring必选

请求内容类型。固定为application/json。

请求体（Request Body）

modelstring必选

调用模型。

inputobject必选

输入图像的基本信息，比如图像URL地址。

属性

base_image_url string必选

原始真人展示图像URL地址。

URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。

图像限制：

图像格式：JPEG、JPG、PNG、WEBP。
图像分辨率：不低于256×256像素且不超过4096×4096像素，人脸占比不低于128×128像素。
图修比例：长宽比大于1:2且小于2:1。
图像大小：不超过5MB。
URL地址中不能包含中文字符。

真人图像示例

mask_image_url string必选

对应原图的期望保留区域mask图URL，图片为（0,255）的黑白图，其中白色表示商品主体区域。

URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。

图片限制：

图像格式：JPEG、JPG、PNG、WEBP。
图像分辨率：与base_image_url参数对应的图像保持一致。
图修比例：长宽比大于1:2且小于2:1。
图像大小：不超过5MB。
URL地址中不能包含中文字符。

mask图像示例

predefined_face_id string 可选

预设人物ID。仅在V1版本使用。

枚举示例

girl1

girl2

girl3

boy1

boy2

boy3

face_image_url string 可选

期望替换的人物图像URL地址。

URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。

图片限制：

图像格式：JPEG、JPG、PNG、WEBP。
图像分辨率：长边像素不大于2048，人脸区域大于128×128像素。
图像大小：建议不超过5MB。

优先级低于predefined_face_id参数。

prompt string必选

针对生成图像背景环境、模特的全身形象描述。

支持中英文，小于100字符。

示例：一名年轻女子，身穿白色短裤，极简风格调色板，长镜头，双色效果，暗银色和浅粉色。

face_prompt string必选

生成人像面部描述，支持中英文，小于100字符。

示例：一名年轻女子，面容娇好，最好的品质。

background_image_url string 可选

背景环境参考图像URL地址。

URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。

图片限制：

图像格式：JPEG、JPG、PNG、WEBP。
图像分辨率：图像长边像素不大于4096。
图像比例：长宽比小于等于2。
图像大小：不超过5MB。

bgstyle_scale float 可选

背景参考图像权重控制。仅在V2版本使用。

取值范围：[0.0, 1.0]，默认0.7。

数值越大表示参考程度越大。

realPerson bool 可选

输入图片是否是真人。仅在V2版本使用。

true：默认值，表示输入图像是真人。
false：表示输入图像是人台或者非真人。

style string 可选

生成图片风格。仅在V2版本使用。

可选参数["","portrait"]，默认是portrait，

说明：portrait模式会增加一些景深，突出人像的效果*。*

seed integer 可选

控制生成seed。仅在V2版本使用。

取值范围：[0, 4294967290]。不传时系统随机生成 seed。指定具体值（0～4294967290）时使用固定随机种子，相同 seed 值会生成相同结果。

aspect_ratio String 可选

生成图片长宽比例。仅在V2版本使用。

枚举值

可选的比例有：

比例不变，默认值
2:1
16:9
4:3
1:1
3:4
9:16
1:2

parametersobject可选

属性

n Integer 可选

生成图像的数量，支持 1~4 张，默认值 1。

short_side_size string必选

指定生成的图像短边大小，单位：像素。生成图片和输入原图会保持相同的长宽比。

V1版本可选值：512和1024。

V2版本可选值：1024和2048

虚拟模特V1

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": "一名年轻女子，身穿白色短裤，极简风格调色板，长镜头，双色效果（暗银色和浅粉色）",
    "face_prompt": "年轻女子，面容姣好，最高品质"
  },
  "parameters": {
    "short_side_size": "512",
    "n": 1
  }
}'

虚拟模特V2

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

响应

outputobject

任务输出信息。

属性

task_id string

任务id。

task_status string

任务状态。

PENDING：排队中
RUNNING：处理中
SUSPENDED：挂起
SUCCEEDED：执行成功
FAILED：执行失败
UNKNOWN：任务不存在或状态未知

codestring

接口错误码。接口成功请求不会返回该参数。

messagestring

接口错误信息。接口成功请求不会返回该参数。

request_idstring

请求唯一标识。可用于请求明细溯源和问题排查。

成功响应

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

步骤2：根据任务ID查询结果

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

调用时请将{WorkspaceId}替换为真实的业务空间ID。

请求头（Headers）

Authorizationstring必选

推荐使用阿里云百炼API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。

URL路径参数（Path parameters）

task_idstring必选

任务id。

获取任务结果

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

响应

outputobject

任务输出信息。

属性

task_id string

任务id。

task_status string

任务状态。

PENDING：排队中
RUNNING：处理中
SUSPENDED：挂起
SUCCEEDED：执行成功
FAILED：执行失败
UNKNOWN：任务不存在或状态未知

resultsarray object

任务结果列表，包括图像URL。

属性

url string

模型生成图片的URL地址。

task_metrics object

任务信息统计指标。

属性

TOTAL integer

总的任务数。

SUCCEEDED integer

任务状态为成功的任务数。

FAILED integer

任务状态为失败的任务数。

submit_time string

任务提交时间。

scheduled_time string

任务排期执行时间。

end_time string

任务完成时间。

result_url string

输出图片url。

codestring

任务执行失败的错误码。

messagestring

任务执行失败的详细信息。

usageobject

输出信息统计。

属性

image_count integer

模型生成图像的数量。

request_idstring

请求唯一标识。可用于请求明细溯源和问题排查。

任务执行成功

任务数据（如任务状态、图像URL等）仅保留24小时，超时后会被自动清除。请您务必及时保存生成的图像。

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

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。

此API还有特定状态码，具体如下所示。

HTTP状态码	接口错误码（code）	接口错误信息（message）	含义说明
400	InvalidFile.Content	The input image has no human body or has unclear human body. Please upload other image	输入图片中没有人
400	InvalidParameter	The request is missing required parameters or in a wrong format, please check the parameters that you send.	入参格式不对
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.	输入图片下载失败，请检查网络或者输入格式
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	上传图片大小不符合要求
500	InternalError.Algo	An internal error occurs during computation, please try this model later.	算法运行错误