## 接口简介图片换装：基于用户输入的衣服图片，更换到指定的模特图上。即输入模特图A + 服装图B，输出A穿着指定服装B的照片 ## 限制条件 |名称 |内容 | |---|---| |输入图要求 |1. 图片格式：JPG(JPEG), PNG, JFIF 等常见格式, 建议使用JPG格式|\ | |2. 图片要求：小于5 MB，小于4096\*4096|\ | |3. 建议使用人物主体清晰的模特图与服装主体清晰的服装图，否则会导致出图效果不佳 | ## 请求说明 |名称 |内容 | |---|---| |接口地址 |[https://visual.volcengineapi.com](https://visual.volcengineapi.com/) | |请求方式 |POST | |Content\-Type |application/json | ## 提交任务 ### **提交任务请求参数** #### **Header参数** :::warning 本服务固定值：**Region为cn\-north\-1，Service为cv** ::: 主要用于鉴权，详见 [公共参数](https://www.volcengine.com/docs/6369/67268) \- 签名参数 \- 在Header中的场景部分 #### **Query参数** :::tip 拼接到url后的参数，示例：[https://visual.volcengineapi.com?Action=CVSubmitTask&Version=2022-08-31](https://visual.volcengineapi.com?Action=CVSubmitTask&Version=2022-08-31) ::: |参数 |可选/必选 |类型 |说明 | |---|---|---|---| |Action |必选 |String |接口名，取值：CVSubmitTask | |Version |必选 |String |版本号，取值：2022\-08\-31 | #### **Body参数** :::warning 业务请求参数，放到request.body中，MIME\-Type为**application/json** ::: |名称 |类型 |必选 |描述 |备注 | |---|---|---|---|---| |req_key |String |是 |服务标识| |\ | | | |取固定值: **dressing_diffusionV2** | | |model |Model |否 |模特配置| |\ | | | |当以base64形式传入模特图时，可不传该参数 | | |garment |Garment |是 |服装配置 | | |inference_config |InferenceConfig |否 |推理配置 | | |req_image_store_type |int |否 |模特图与服装图传入方式：| |\ | | | || |\ | | | |* 0：图片通过binary_data_base64参数传入，格式为：["模特图base64字符串", "服装图一base64字符串", "服装图二base64字符串"]。若为多件服装图，服装图顺序和 garment.data 顺序一致。| |\ | | | |* 1：图片通过model和garment中的url参数传入| |\ | | | || |\ | | | |默认值：1 | | |binary_data_base64 |Array of string |否 |以base64形式传入模特图与服装图| |\ | | | |如需使用该参数，请先将req_image_store_type设置为0。| |\ | | | |当以base64形式传入模特图时，model参数可不传，但garment.data中的type参数仍需传入。 | | **Model** 模特配置相关参数 |名称 |必选 |类型 |描述 |备注 | |---|---|---|---|---| |url |否 |String |模特图URL | | |protect_mask_url |否 |String |模特保护区域图URL |* 输入格式：PNG格式，保护区域为255，非保护区域为0|\ | | | | |* 上传时需要同步修改keep_head/keep_hand/keep_foot参数|\ | | | | |* 若同时上传protect_mask_url和keep_head/keep_hand/keep_foot字段，则取并集 | **Garment** 服装配置相关参数 |名称 |必选 |类型 |描述 |备注 | |---|---|---|---|---| |data |是 |Array of Data |服装图详细信息 |**当前最多仅支持配置2件服装，可以是上衣和下衣** | **Data** 服装图相关参数 |名称 |必选 |类型 |描述 |备注 | |---|---|---|---|---| |url |否 |String |服装图URL | | |type |是 |String |服装图的分类，取值如下：| |\ | | | || |\ | | | |* 传入上衣和下衣，同时换装时，需要传入指定上衣参数为"upper" + 下衣参数为"bottom"| |\ | | | |* 传入单件服装图则选："full" 或者不传入| |\ | | | || |\ | | | |默认值："full" | | **InferenceConfig** 推理配置相关参数 |名称 |必选 |类型 |描述 |备注 | |---|---|---|---|---| |do_sr |否 |bool |是否对结果进行超分处理| |\ | | | |默认值：false | | |seed |否 |int |随机种子参数，默认为\-1，表示系统随机生成seed| |\ | | | |默认值：\-1 | | |keep_head |否 |bool |是否保持模特原图的头（包括发型）| |\ | | | |默认值：true | | |keep_hand |否 |bool |是否保持模特原图的手| |\ | | | |默认值：false | | |keep_foot |否 |bool |是否保持模特原图的足| |\ | | | |默认值：false | | |num_steps |否 |int |模型推理步数，和算法效果、处理时间相关，使用非默认值时可能会影响性能| |\ | | | |默认值：16| |\ | | | |取值范围： [8, 50] | | |keep_upper |否 |bool |是否保持模特原图的上装| |\ | | | |默认值：false | | |keep_lower |否 |bool |是否保持模特原图的下装| |\ | | | |默认值：false | | |tight_mask |否 |String |模特图遮挡区域范围| |\ | | | |默认值："loose"| |\ | | | |支持类型：["tight", "loose", "bbox"]| |\ | | | |取值说明：| |\ | | | | "tight": 上窄下窄| |\ | | | | "loose": 上窄下宽（默认）| |\ | | | | "bbox": 上宽下宽| |\ | | | |默认值："loose" | | |p_bbox_iou_ratio |否 |float |当画面有多个人时，每个人的bbox与主体相交的比例| |\ | | | |默认值：0.3| |\ | | | |取值范围：[0, 1.0] | | |p_bbox_expand_ratio |否 |float |bbox在inference时扩大的比例| |\ | | | |默认值：1.1| |\ | | | |取值范围：[1.0, 1.5] | | |max_process_side_length |否 |int |当输入图像时，最大的边长若超过该数值，会先resize到图像到该最大边长| |\ | | | |默认值：1920| |\ | | | |取值范围：[1080, 4096] | | ### 提交任务返回参数 #### **通用返回参数** 请参考[通用返回字段及错误码](https://www.volcengine.com/docs/6444/69728) #### **业务返回参数** :::tip 重点关注data中以下字段，其他字段为公共返回(可忽略或不做解析) ::: |字段 |类型 |说明 | |---|---|---| |task_id |string |任务ID，用于查询结果 | ### 提交任务请求&返回完整示例 **请求示例：** 方式一：使用url参数传入模特图和服装图 ```JSON { "req_key": "dressing_diffusionV2", "model": { "url": "https://xxx" }, "garment": { "data": [ { "type": "upper", "url": "https://xxx" }, { "type": "bottom", "url": "https://xxx" } ] } } ``` 方式二：使用binary_data_base64参数传入模特图和服装图 ```JSON { "req_key": "dressing_diffusionV2", "binary_data_base64": ["模特图base64字符串", "服装图一base64字符串", "服装图二base64字符串"], "req_image_store_type": 0, "garment": { "data": [ { "type": "upper" }, { "type": "bottom" } ] } } ``` **返回示例：** ```JSON { "code": 10000, "data": { "task_id": "7392616336519610409" }, "message": "Success", "request_id": "20240720103939AF0029465CF6A74E51EC", "status": 10000, "time_elapsed": "104.852309ms" } ``` ## 查询任务 ### **查询任务请求参数** #### **Header参数** :::warning 本服务固定值：**Region为cn\-north\-1，Service为cv** ::: 主要用于鉴权，详见 [公共参数](https://www.volcengine.com/docs/6369/67268) \- 签名参数 \- 在Header中的场景部分 #### **Query参数** :::tip 拼接到url后的参数，示例：[https://visual.volcengineapi.com](https://visual.volcengineapi.com/)[?Action=CVGetResult&Version=2022-08-31](https://visual.volcengineapi.com?Action=CVGetResult&Version=2022-08-31) ::: |参数 |可选/必选 |类型 |说明 | |---|---|---|---| |Action |必选 |String |接口名，固定值：CVGetResult | |Version |必选 |String |版本号，固定值：**2022\-08\-31** | #### **Body参数** :::warning 业务请求参数，放到request.body中，MIME\-Type为**application/json** ::: |参数 |可选/必选 |类型 |说明 |示例 | |---|---|---|---|---| |req_key |必选 |String |服务标识| |\ | | | |取固定值: **dressing_diffusionV2** | | |task_id |必选 |String |任务ID，此字段的取值为**提交任务接口**的返回 | | |req_json |可选 |JSON String |**json序列化后的字符串**|"{\"logo_info\":{\"add_logo\":true,\"position\":0,\"language\":0,\"opacity\":0.3,\"logo_text_content\":\"这里是明水印内容\"},\"return_url\":true}" |\ | | | |目前支持水印配置和是否以图片链接形式返回，可在返回结果中添加 | | **ReqJson(序列化后的结果再赋值给req_json)** 配置信息 |**参数** |**可选/必选** |**类型** |**说明** | |---|---|---|---| |return_url |可选 |bool |输出是否返回图片链接 **（链接有效期为24小时）** | |logo_info |可选 |LogoInfo |水印信息 | **LogoInfo** 水印相关信息 |名称 |类型 |必选 |描述 | |---|---|---|---| |add_logo |Boolean |否 |是否添加水印。True为添加，False不添加。默认不添加 | |position |Int |否 |水印的位置，取值如下：|\ | | | |0\-右下角|\ | | | |1\-左下角|\ | | | |2\-左上角|\ | | | |3\-右上角|\ | | | |默认0 | |language |Int |否 |水印的语言，取值如下：|\ | | | |0\-中文（AI生成）|\ | | | |1\-英文（Generated by AI）|\ | | | |默认0 | |opacity |Float |否 |水印的不透明度，取值范围0\-1，1表示完全不透明，默认0.3 | |logo_text_content |String |否 |明水印自定义内容 | #### ### 查询任务返回参数 #### **通用返回参数** 请参考[通用返回字段及错误码](https://www.volcengine.com/docs/6444/69728) #### **业务返回参数** :::tip 重点关注data中以下字段，其他字段为公共返回(可忽略或不做解析) ::: |字段 |类型 |说明 | |---|---|---| |binary_data_base64 |Array of string |返回图片的base64数组 | |image_urls |Array of string |返回图片的url数组，输出图片格式为png格式 | |status |String |in_queue：任务已提交|\ | | |generating：任务已被消费，处理中|\ | | |done：处理完成，成功或者失败，可根据外层code&message进行判断|\ | | |not_found：任务未找到，可能原因是无此任务或任务已过期(12小时)|\ | | |expired：任务已过期，请尝试重新提交任务请求 | ### 查询任务请求&返回完整示例 **请求示例：** ```JSON { "req_key": "dressing_diffusionV2", "task_id": "<任务提交接口返回task_id>", "req_json": "{\"logo_info\":{\"add_logo\":true,\"position\":0,\"language\":0,\"opacity\":0.3,\"logo_text_content\":\"这里是明水印内容\"},\"return_url\":true}" } ``` **返回示例：** ```JSON { "code": 10000, "data": { "binary_data_base64": [], "image_urls": [ "https://xxx", ], "resp_data": "{\"progress\": 100, \"received_at\": 1747915233.5144498, \"processed_at\": 1747915233, \"finished_at\": 1747915311, \"binary_data_url_list\": [], \"binary_data_info_list\": [], \"code\": 0, \"message\": \"success\", \"results\": [{\"uri\": \"tos://image_tryon/temp/result/870a3566-3704-11f0-8154-024240456e81.png\", \"url\": \"https://tosv.byted.org/obj/ic-cv-digital-human-test/image_tryon/temp/result/870a3566-3704-11f0-8154-024240456e81.png\", \"inference_config\": {\"seed\": 2636286795}, \"score\": 7, \"reason\": \"The garment fits well and the model's body is displayed properly. The pose and background match the model photo. However, the texture of the sweater looks a bit unnatural.\"}, {\"uri\": \"tos://image_tryon/temp/result/8720103e-3704-11f0-8154-024240456e81.png\", \"url\": \"https://tosv.byted.org/obj/ic-cv-digital-human-test/image_tryon/temp/result/8720103e-3704-11f0-8154-024240456e81.png\", \"inference_config\": {\"seed\": 1048212177}, \"score\": 8, \"reason\": \"The garment fits well, the model's body is well - displayed, and the pose and background correspond accurately. The details of the dog and the bow are more natural compared to Image 1.\"}, {\"uri\": \"tos://image_tryon/temp/result/87389348-3704-11f0-8154-024240456e81.png\", \"url\": \"https://tosv.byted.org/obj/ic-cv-digital-human-test/image_tryon/temp/result/87389348-3704-11f0-8154-024240456e81.png\", \"inference_config\": {\"seed\": 3299657535}, \"score\": 6, \"reason\": \"The garment fits, but the position of the dog on the sweater seems slightly off compared to the original garment photo. Also, the overall look is less natural than Image 2.\"}], \"debug_info\": {\"processor\": {\"preprocess\": {\"time_cost\": 12.185985565185547}, \"inference\": {\"time_cost\": 57.61434316635132}, \"post_process\": {\"time_cost\": 7.532143831253052}}}}", "status": "done" }, "message": "Success", "request_id": "202505222001537BEEE896729EC59B35AF", "status": 10000, "time_elapsed": "1.251001589s" } ``` ## 错误码 ### **通用错误码** 请参考[通用返回字段及错误码](https://www.volcengine.com/docs/6444/69728) ### **业务错误码** |HttpCode |错误码 |错误消息 |描述 | |---|---|---|---| |200 |10000 |无 |请求成功 | |400 |50411 |Pre Img Risk Not Pass |输入图片前审核未通过 | |400 |50511 |Post Img Risk Not Pass |输出图片后审核未通过 | |400 |50412 |Text Risk Not Pass |输入文本前审核未通过 | |400 |50512 |Post Text Risk Not Pass |输出文本后审核未通过 | |400 |50413 |Post Text Risk Not Pass |输入文本NER、IP、Blocklist等拦截 | ## 接入说明 ### SDK使用说明请参考[SDK使用说明](https://www.volcengine.com/docs/6444/1340578) ### HTTP方式接入说明请参考[HTTP请求示例](https://www.volcengine.com/docs/6444/1390583)

智能视觉服务