文档

虚拟模特API详情

更新时间:
一键部署

虚拟模特

说明

支持的领域 / 任务:aigc /虚拟模特

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

虚拟模特服务支持虚拟模特V1和虚拟模特V2两个版本。

虚拟模特V1(V1版本)

虚拟模特V2(V2版本)

  • 支持真人实拍图上传。

  • 生成图片分辨率为短边512或1024。

  • 支持真人、人台实拍图上传。

  • 生成图片分辨率为短边1024或2048。

  • 支持改变分辨率,生成图片长宽比支持"比例不变"、"16:9"、"4:3"、"1:1"、"3:4"、 "9:16"。

  • 文本引导效果更准确。

  • 支持背景参考图权重自由控制。

如想了解功能效果或使用流程,可以在通义万相-虚拟模特(V0.7)功能中进行初步体验。

输入内容&效果示意(V1版本):

输入图

参数配置

输出图

真人图示例

image.jpeg

"prompt":"一位年轻男性站着摆拍,在空荡的卧室里,窗户旁边,阳光照射进来,highly detailed,8K,极简主义风格"

"face_prompt":"英俊的男性,脸好,脸美,质量上乘,杰作,(逼真度:1.4)"

"predefined_face_id":"boy3"

image.png

输入内容&效果示意(V2版本):

输入图

参数配置

输出图

真人图示例

image.jpeg

"prompt":"a beautiful chinese girl, she stands in front of a pure pink background, she is smiling"

"face_prompt":"good face, beautiful face, best quality."

image.png

image.jpeg

"prompt":"a beautiful chinese girl, at a pastel-themed ice cream pop-up store,The sunny weather casts a warm glow, highlighting the colorful dessert displays and a clear blue sky, she is smiling"

"face_prompt":"good face, beautiful face, best quality."

image.png

image.jpeg

"prompt":"A woman stands on a rural road"

"face_prompt":"good face, beautiful face, best quality."

"background_image_url":image.png

image.png

image.png

"prompt":"A Europe handsome man, Natural light, open subway platform, he is waiting, behind is an incoming train, the train is coming from left to right"

"face_prompt":"good face, beautiful face, best quality."

"aspect_ratio":"4:3"

image.png

image.png

"prompt":"Person's hands hold a bottle for show, the background is saffron yellow, and sun light is on it"

"face_prompt":"good face, beautiful face, best quality."

image.png

人台图示例

image.png

"prompt":"A woman stands in front of a quaint French flower shop, the charming streetscape embodying the essence of a picturesque scene in France. Brightly colored flowers in an array of varieties spill out from buckets and vases, creating a vibrant tapestry that decorates the storefront. The cobblestone path tells tales of a city rich in history, and the shop itself, with its traditional façade and large windows, invites passersby to pause and indulge in the visual feast of petals and leaves. good hands"

"face_prompt":"good face, beautiful face, best quality."

"aspect_ratio":"4:3"

"background_image_url":image.png

image.png

image.png

"prompt":"A woman stands beside a luxurious swimming pool, her attire and posture suggesting leisure and relaxation. The pool's calm, crystal-clear waters reflect the surrounding opulent setting, with elegant lounge chairs inviting moments of repose under the sun. Perhaps it's a high-end resort or an upscale private villa, where the tiled pool deck and meticulously landscaped greenery speak of exclusivity and refinement."

"face_prompt":"good face, beautiful face, best quality."

"aspect_ratio":"4:3"

image.png

应用场景

  • 商品模特创意设计:电商商品设计领域,客户上传一张身着基础款连衣裙的模特照片,通过虚拟模特功能,选择维多利亚时代复古风格的虚拟模特与奢华背景,保留原有模特的优雅姿态,将连衣裙材质和色彩自动调整以匹配新场景,实现高端定制系列的视觉预览。

  • 珠宝饰品穿戴展示:珠宝商希望突出展示其新款项链,上传佩戴基础项链的半身人台照或者基础模特照,通过AI技术生成更为精致优美的虚拟模特,实现虚拟模特穿戴珠宝的璀璨效果,同时调整背景为高贵典雅的室内环境,提升商品档次感,增加珠宝细节纹理融合。

  • 模特鞋靴穿戴展示:设计师为展示新款多功能球鞋,上传穿着新款鞋靴的基础站立姿势的模特照片,利用虚拟模特技术快速更换生成新的虚拟模特,生成一系列从休闲街头风到专业运动风格背景展示图,满足不同顾客群体的场景需求,创造出多样化的时尚造型。

  • 童装童鞋模特生成:童装品牌需要展示儿童在多风格场景中的穿着效果,上传基础照片后,使用虚拟模特生成活泼可爱的儿童形象,更换为品牌最新童装系列,背景设置为学校、游乐场等场景,展现孩子们的天真烂漫与服装的舒适度,确保童装新品都能极速展示。

特色优势

  • 效果业界领先:虚拟模特生成图像语义一致性更精准,AI局部创作布局自然、细节丰富、画面细腻、结果逼真,又保持视觉效果的和谐与专业性,无需担心人工合成的痕迹。

  • 稳定、易用平台服务:提供在高并发、大流量下的稳定虚拟模特图片生成响应,可直接调用的简单推理API 接口,服务简单易用,易被集成,兼容性强。

  • 模特图高品质生成:支持人台图、真人图、服装图模特生成,支持16:9、4:3、1:1、3:4、9:16多比例图片生成,支持最大短边大小到2024,支持背景参考图输入和权重自由配置。

模型概览

模型名

模型简介

版本

wanx-virtualmodel

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

V1

virtualmodel-v2

通义万相-虚拟模特可以对上传的真人、人台实拍商品展示图进行智能生成,将其中的模特和背景替换为心仪的内容,在保持人物姿态不变的情况下,使用虚拟模特对商品进行更加精美、多样的展示。支持各种与模特产生互动的商品,如手持小商品、服装、鞋靴、配饰等。 生成图片分辨率为短边1024或2048,支持改变分辨率,文本引导效果更准确。

V2

输入限制

  • 图像格式:JPEG、JPG、PNG、webp。

  • 图像大小:不超过3MB。

  • 图像分辨率:大于256×256像素,小于4096x2048像素,人脸占比不低于128×128像素。

  • URL地址中不能包含中文字符。

  • V1版本prompt支持中英文,V2版本当前仅支持英文描述。

HTTP调用接口

功能描述

本模型需要相对较长的算法调用时间,所以在接口层面采用了异步调用的方式进行任务提交,在通过任务接口提交作业之后,系统会返回对应的作业ID,随后可以通过对应的异步作业查询接口获取任务的状态并且在作业到达最终完成态后取回对应的作业结果。

前提条件

接口限制:对单账户(含主账号与RAM子账号)任务下发接口限制QPS为2,并发任务数量限制为1。

作业提交接口调用

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/virtualmodel/generation/

入参描述

传参方式

字段

类型

必选

描述

示例值

V1版本

V2版本

Header

Content-Type

String

请求类型:application/json

application/json

☑️

☑️

Authorization

String

API-Key,例如:Bearer d1**2a

Bearer d1**2a

☑️

☑️

X-DashScope-Async

String

固定使用 enable,表明使用异步方式提交作业。

enable

☑️

☑️

Body

model

String

指明需要调用的模型,固定值

wanx-virtualmodel

☑️

☑️

input.base_image_url

String

原始真人展示图URL

图片限制:文件大小建议小于5M,图像格式jpg/png/jpeg/bmp,长宽比小于等于2,最大边长像素不大于4096

image.jpeg

http://aaa/bbb.jpg

☑️

☑️

备注:V2版本长宽比小于16:9

input.mask_image_url

Integer

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

图片限制:文件大小建议小于5M,图像格式jpg/png/jpeg/bmp,长宽比小于等于2,mask图片分辨率与input.base_image保持一致,最大边长像素不大于4096

image.png

http://aaa/bbb.jpg

☑️

☑️

备注:V2版本长宽比小于16:9

input.predefined_face_id

String

预设人物ID:

"girl1"image.png

"girl2"image.png

"girl3"image.png

"boy1"image.png

"boy2"image.png

"boy3"image.png

"girl3"

☑️

input.face_image_url

String

期望替换的人物图片的 URL

图片限制:文件大小小于5M,图像格式jpg/png/jpeg/bmp,图像长边像素不大于2048,人脸区域大于128*128

优先级低于predefined_face_id

http://aaa/bbb.jpg

☑️

☑️

input.prompt

String

生成图像背景环境、模特全身形象描述prompt,支持中英文,小于 100 字符;

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

☑️

备注:支持中英文输入

☑️

备注:V2版本当前仅支持英文

示例:a beautiful chinese girl, she stands in front of a plain pink background

input.face_prompt

String

生成人像面部描述prompt,支持中英文,小于 100 字符;

一名年轻女子,面容娇好,最好的品质

☑️

备注:支持中英文输入

☑️

备注:V2版本当前仅支持英文

示例:good face, beautiful face, best quality.

input.background_image_url

String

背景环境参考图URL

图片限制:文件大小小于5M,图像格式jpg/png/jpeg/bmp,长宽比小于等于2,最大边长像素不大于4096

http://aaa/bbb.jpg

☑️

☑️

input.bgstyle_scale

Float

背景参考图权重控制参数:范围[0.0-1.0], 默认0.7。

说明:数值越大表示参考程度越大

☑️

input.realPerson

Bool

输入图片是否是真人;

true:真人 (默认值)

false:人台/非真人

"realPerson": true

☑️

input.style

String

生成图片风格:

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

说明: portrait模式会增加一些景深,突出人像的效果

"style": "portrait"

☑️

input.seed

Integer

控制生成seed:范围[-1,10000000]。默认值为-1, 则系统随机内置seed.

说明:seed表示随机种子值,-1表示系统内部随机一个值;0至10000000则是由用户自行决定所用的随机种子值,同样的seed值会生成相同的结果。

"seed": 42

☑️

input.aspect_ratio

String

生成图片长宽比: 可选值包括["比例不变","16:9","4:3","1:1","3:4", "9:16"]。默认值为"比例不变"

"aspect_ratio": "1:1"

☑️

parameters.n

Integer

图片生成的数量,支持 1~4 张,默认值 1

"parameters": {

"short_side_size": "512",

"n": 2

}

☑️

☑️

parameters.short_side_size

String

指定生成的图像短边大小,生成图片和输入的原图会保持相同的长宽比,可选值 :512 和 1024

☑️

备注:

V1版本:512和1024

☑️

备注:

V2版本:1024和2048

出参描述

字段

类型

描述

示例值

output.task_id

String

本次请求的异步任务的作业 id,实际作业结果需要通过异步任务查询接口获取。

13b1848b-5493-4c0e-8c44-68d038b492af

output.task_status

String

提交异步任务后的作业状态。

PENDING

request_id

String

本次请求的系统唯一码

7574ee8f-38a3-4b1e-9280-11c33ab46e51

请求示例

以下示例展示通过CURL命令来调用本模型的脚本

需要使用您的API-KEY替换示例中的 your-dashscope-api-key ,代码才能正常运行。

V1版本:

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/virtualmodel/generation' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx-virtualmodel",
  "input": {
    "base_image_url": "http://xxx/1.jpg",
    "mask_image_url": "http://xxx/2.jpg",
    "prompt": "一名年轻女子,身穿白色短裤,极简风格调色板,长镜头,双色效果,暗银色和浅粉色",
    "face_prompt": "一名年轻女子,面容娇好,最好的品质"
  },
  "parameters": {
    "short_side_size": "512",
    "n": 2
  }
}'

V2版本:

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/virtualmodel/generation' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "model": "virtualmodel-v2",
  "input": {
    "base_image_url": "http://xxx/1.jpg",
    "mask_image_url": "http://xxx/2.jpg",
    "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": 2
  }
}'

响应示例

{
    "output": {
		"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1", 
    	"task_status": "PENDING"
    }
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

异常响应示例

在提交作业请求出错的情况下,输出的结果中会通过 code 和 message 指明出错原因。

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

作业任务状态查询和结果获取接口

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

入参描述

传参方式

字段

类型

必选

描述

示例值

Url Path

task_id

String

需要查询作业的 task_id

13b1848b-5493-4c0e-8c44-68d038b492af

Header

Authorization

String

API-Key,例如:Bearer d1**2a

Bearer d1**2a

出参描述

字段

类型

描述

示例值

output.task_id

String

本次请求的异步任务的作业 id,实际作业结果需要通过异步任务查询接口获取。

13b1848b-5493-4c0e-8c44-68d038b492af

output.task_status

String

被查询作业的作业状态

任务状态:

PENDING 排队中

RUNNING 处理中

SUCCEEDED 成功

FAILED 失败

UNKNOWN 作业不存在或状态未知

output.result_url

String

  • 如果作业成功,包含模型生成的结果图像的 URL,可以在 24 小时之内随时下载。

"result_url": "http://oss.aliyuncs.com/xxx/abc.jpg"

usage.image_count

Integer

本次请求生成图像计量

"image_count": 1

request_id

String

本次请求的系统唯一码

7574ee8f-38a3-4b1e-9280-11c33ab46e51

请求示例

以下示例展示通过CURL命令来调用本模型的脚本。

说明

需要使用您的API-KEY替换示例中的 your-dashscope-api-key ,代码才能正常运行。

curl -X GET \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-af6e-a0c6a421c010

响应示例(作业执行中)

作业提交后将处于排队状态,在得到调度之后将转为运行状态,此时作业的状态为RUNNING,task_metrics将给出具体batch状态。

{
    "request_id":"e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output":{
        "task_id":"86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status":"RUNNING",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

响应示例(作业成功执行完毕)

如果作业执行完成并成功之后,再次查询作业状态,接口将在告知作业状态的同时,一并将作业的结果返回。对于本模型,作业在结束之后的状态会持续保留24小时以备客户随时查询,24小时之后,作业将从系统中清除,相关的结果也将一并清除;对应的,作业生成的结果为图像的URL地址,出于安全考虑,该URL的下载有效期也是24小时,需要用户在获取作业结果后根据需要及时使用或者转存。

{
    "request_id":"<your request id>",
    "output":{
        "task_id":"<your task id>",
        "task_status":"SUCCEEDED",
        "submit_time":"xxx",
        "scheduled_time":"xxx",
        "end_time":"xxx",
        "error_message":"Success",
        "start_time":"xxx",
        "model_index":0,
        "error_code":0,
        "result_url":"http://oss.aliyuncs.com/xxx/abc.jpg"
    },
    "usage":{
        "image_count":1
    }
}

响应示例(作业失败)

如果因为某种原因作业失败,则作业状态会设置为FAILED,并且通过code和message字段指明错误原因。

{
  "request_id": "<your request id>",
  "output": {
    "task_id": "<your task id>",
    "task_status": "FAILED",
    "submit_time": "xxx",
    "scheduled_time": "xxx",
    "end_time": "xxx",
    "code": "InvalidImageResolution",
    "message": "The input image resolution is too large or small"
  },
  "usage": {
    "image_num": 0
  }
}

状态码说明

DashScope灵积模型服务通用状态码请查阅:状态码说明

同时本模型还有如下特定错误码:

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.

算法运行错误