即梦 API 需求整理
请你帮我用这个即梦api写一段python代码。
要求
- 输入两张图片路径,人的图像路径1.jpg,衣服的路径2.jpg
- 将两张图片传入api接受返回的图片
- 并将返回的图片保存在指定目录
- 要有良好的封装性,支持函数调用。
- 利用python实现
接口简介
图片换装:基于用户输入的衣服图片,更换到指定的模特图上。即输入模特图A + 服装图B,输出A穿着指定服装B的照片
限制条件
名称
内容
输入图要求
图片格式:JPG(JPEG), PNG, JFIF 等常见格式, 建议使用JPG格式
图片要求:小于5 MB,小于4096*4096
建议使用人物主体清晰的模特图与服装主体清晰的服装图,否则会导致出图效果不佳
请求说明
名称
内容
接口地址
https://visual.volcengineapi.com
请求方式
POST
Content-Type
application/json
提交任务
提交任务请求参数
Header参数
注意
本服务固定值:Region为cn-north-1,Service为cv
主要用于鉴权,详见 公共参数 - 签名参数 - 在Header中的场景部分
Query参数
拼接到url后的参数,示例:https://visual.volcengineapi.com?Action=CVSubmitTask&Version=2022-08-31
参数
可选/必选
类型
说明
Action
必选
String
接口名,取值:CVSubmitTask
Version
必选
String
版本号,取值:2022-08-31
Body参数
注意
业务请求参数,放到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]
提交任务返回参数
通用返回参数
请参考通用返回字段及错误码
业务返回参数
重点关注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, //状态码,判断状态,code!=10000的情况下,不会返回task_id
"data": {
"task_id": "7392616336519610409" //任务ID,查询接口使用
},
"message": "Success",
"request_id": "20240720103939AF0029465CF6A74E51EC", //排查错误的关键信息
"time_elapsed": "104.852309ms" //链路耗时
}
查询任务
查询任务请求参数
Header参数
注意
本服务固定值:Region为cn-north-1,Service为cv
主要用于鉴权,详见 公共参数 - 签名参数 - 在Header中的场景部分
Query参数
拼接到url后的参数,示例:https://visual.volcengineapi.com?Action=CVGetResult&Version=2022-08-31
参数
可选/必选
类型
说明
Action
必选
String
接口名,固定值:CVGetResult
Version
必选
String
版本号,固定值:2022-08-31
Body参数
注意
业务请求参数,放到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
水印信息
aigc_meta
可选
AIGCMeta
隐式标识
隐式标识验证方式:
查看【png】或【mp4】格式,人工智能生成合成内容表示服务平台(后续预计增加jpg)
https://www.gcmark.com/web/index.html#/mark/check/image
查看【jpg】格式,使用app11 segment查看aigc元数据内容
如 https://cyber.meme.tips/jpdump/#
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表示完全不透明,默认1
logo_text_content
String
否
明水印自定义内容
AIGCMeta
隐式标识,依据《人工智能生成合成内容标识办法》&《网络安全技术人工智能生成合成内容标识方法》
名称
类型
可选/必选
描述
content_producer
string
可选
内容生成服务ID
producer_id
string
必选
内容生成服务商给此图片数据的唯一ID
content_propagator
string
可选
内容传播服务商ID
propagate_id
string
可选
传播服务商给此图片数据的唯一ID
查询任务返回参数
通用返回参数
请参考通用返回字段及错误码
业务返回参数
说明
重点关注data中以下字段,其他字段为公共返回(可忽略或不做解析)
字段
类型
说明
binary_data_base64
Array of string
返回图片的base64数组
image_urls
Array of string
返回图片的url数组(有效期为 24 小时)
输出图片格式为png格式
resp_data
String
算法返回的一些信息,可忽略,是json序列化字符串
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\":false,\"position\":0,\"language\":0,\"opacity\":1,\"logo_text_content\":\"这里是明水印内容\"},\"return_url\":true,\"aigc_meta\":{\"content_producer\":\"xxx\",\"producer_id\":\"xxx\",\"content_propagator\":\"xxx\",\"propagate_id\":\"xxx\"}}"
}
返回示例:
JSON
复制
{
"code": 10000, //状态码,优先判断 code=10000, 然后再判断data.status,否则解析有可能会panic
"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",
"status": 10000, //无需关注,请忽略
"request_id": "2025061718460554C9B78D23B0BAB45B2A", //排查错误的关键信息
"time_elapsed": "508.312154ms" //链路耗时
}
返回报错示例:
JSON
复制
{
"code": 50413, //状态码,优先判断 code=10000, 然后再判断data.status,否则解析有可能会panic
"data": null, //code!=10000的情况下,该字段返回为null
"message": "Post Text Risk Not Pass", //错误信息
"request_id": "202511281418218670D408837A9B0EB58F", //排查错误的关键信息
"status": 50413, //无需关注,请忽略
"time_elapsed": "36.799829ms" //链路耗时
}
错误码
通用错误码
请参考通用返回字段及错误码
业务错误码
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使用说明
HTTP方式接入说明
请参考HTTP请求示例使用方式
把代码放在同级目录
很好!代码已经可以正常工作了。我来给你展示几种调用方式:
即梦API图片换装工具
我已经添加了6个详细的使用示例!你可以根据需求选择:
📝 调用方式说明
方式1:简单调用(推荐)
python
| |
方式2:使用类(更灵活)
python
| |
方式3:批量处理
python
| |
🎯 快速开始
在你的任何Python文件中:
python
| |
所有示例都在代码中,取消注释即可运行!
代码文件
change_clothes.py
| |