图像背景生成API详情
图像背景生成
支持的领域 / 任务：aigc /图像背景生成
通义万相-图像背景生成可以基于输入的前景图像素材拓展生成背景信息，实现自然的光影融合效果，与细腻的写实画面生成。
支持文本描述、图像引导等多种方式，同时支持对生成的图像智能添加文字内容。支持通用、家居和美妆分场景的多个预设模型。支持边缘引导元素生成，指定背景生成图片里有前景和背景特定内容元素引导生成。
生成方式&效果示意：
模型概览
模型名 | 模型简介 |
wanx-background-generation-v2 | 通义万相-图像背景生成可以基于输入的前景图像素材拓展生成背景信息，实现自然的光影融合效果，与细腻的写实画面生成。支持文本描述、图像引导等多种方式，同时支持对生成的图像智能添加文字内容。 |
HTTP调用接口
功能描述
本模型需要相对较长的算法调用时间，所以在接口层面采用了异步调用的方式进行任务提交，在通过任务接口提交作业之后，系统会返回对应的作业ID，随后可以通过对应的异步作业查询接口获取任务的状态并且在作业到达最终完成态后取回对应的作业结果。
前提条件
已开通服务并获得API-KEY：获取API-KEY。
接口限制：对单账户（含主账号与RAM子账号）任务下发接口限制QPS为2，并发任务数量限制为1。
作业提交接口调用
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/background-generation/generation/
入参描述
传参方式 | 字段 | 类型 | 必选 | 描述 | 示例值 |
Header | Content-Type | String | 是 | 请求类型：application/json | application/json |
Authorization | String | 是 | API-Key，例如：Bearer d1**2a | Bearer d1**2a | |
X-DashScope-WorkSpace | String | 否 | 指明本次调用需要使用的workspace；需要注意的是，对于子账号Apikey调用，此参数为必选项，子账号必须归属于某个workspace才能调用；对于主账号Apikey此项为可选项，添加则使用对应的workspace身份，不添加则使用主账号身份。 | ws_QTggmeAxxxxx | |
X-DashScope-Async | String | 是 | 固定使用 enable，表明使用异步方式提交作业。 | enable | |
Body | model | String | 是 | 指明需要调用的模型，固定值 | wanx-background-generation-v2 |
input.base_image_url | String | 是 | 透明背景的主体图像URL。需要为带透明背景的RGBA 四通道图像，支持png格式，分辨率长边不超过2048像素。输出图像的分辨率与该输入图相同 | http://abc.com/a.png | |
input.ref_image_url | String | ref_image_url 和 ref_prompt 至少输入一个 | 引导图URL, 支持 jpg, png，webp等常见格式图像； | http://abc.com/b.jpg | |
input.ref_prompt | String | 引导文本提示词，支持中英双语，不超过70个单词。 | 在沙漠的地面上，远处有植物和落日，丰富的细节，柔和的光线 | ||
input.neg_ref_prompt | String | 否 | 负向提示词，不希望出现的内容。大部分情况下建议缺省该参数，这样会使用模型内置的默认值 | 低质量的，模糊的，错误的 | |
input.reference_edge.foreground_edge | String | 否 | 前景元素，需要为带透明背景的RGBA 四通道图像，分辨率和主体图像相同，如果不同则自动会resize到和主体图像同一个分辨率。前景元素生成的图层在主体前面，可以对主体形成遮挡。元素图像的生成方式参考边缘引导元素生成方法介绍 | reference_edge:{ "foreground_edge":["http://abc.com/edge_1.png"], "background_edge":["http://abc.com/edge_2.png"] } | |
input.reference_edge.background_edge | String | 否 | 背景元素，生成图层在主体的后面，如果重叠会被主体遮挡，其它提要求同前景元素 | ||
input.title | String | 否 | 图像上添加文字主标题。算法自动确定文字的大小和位置，限制1-8个字符 | 分享好时光 | |
input.sub_title | String | 否 | 图像上添加文字副标题。算法自动确定文字的大小和位置，限制1-10个字符。 仅当title不为空时生效 | 只为不一样的你 | |
parameters.n | Integer | 否 | 图片生成的数量，支持1~4 张，默认值1 | "parameters": { "n": 2, "noise_level": 350, "ref_prompt_weight": 0.3, "scene_type": "GENERAL" } | |
parameters.noise_level | Integer | 否 | 当ref_image_url不为空时生效。在图像引导的过程中添加随机变化，数值越大与参考图相似度越低，默认值300，取值范围[0,999] | ||
parameters.ref_prompt_weight | Float | 否 | 仅当ref_image_url和ref_prompt同时输入时生效，该参数设定文本和图像引导的权重。ref_prompt_weight表示文本的权重，图像引导的权重为1-ref_prompt_weight。默认值0.5，取值范围 [0,1] | ||
parameters.scene_type | String | 否 | 使用场景，当前包含3种场景：
|
边缘引导元素生成方法
PS抠图，导出带透明背景的4通道格式图像
环境准备：
pip install controlnet-aux==0.0.7运行代码：
from PIL import Image
from controlnet_aux.processor import Processor
hed_processor = Processor('softedge_hed')
def make_elements(name):
img=Image.open(name)
r,g,b,a=img.split()
img=img.convert('RGB')
hed_img = hed_processor(img, to_pil=True).resize(img.size).convert('RGB')
hed_img.putalpha(a)
hed_img.save('result.png')出参描述
字段 | 类型 | 描述 | 示例值 |
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> ，代码才能正常运行。
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/background-generation/generation/' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer <your-dashscope-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"model": "wanx-background-generation-v2",
"input": {
"base_image_url": "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/main_images/new_main_img/a.png",
"ref_image_url": "https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/ref_images/d1faf4f26c8c4ea798d043a8bf3784bb_2.png",
"ref_prompt": "放在布满苔藓的土地上，被蕨类植物叶片包围，背景是茂盛的植被，丰富的光影细节",
"reference_edge": {
"foreground_edge": [
"https://vision-poster.oss-cn-shanghai.aliyuncs.com/lllcho.lc/data/test_data/images/huaban_soft_edge/6cdd13941cef1b11d885aea1717b983ae566b8efc9094-vcsvxa_fw658webp.png"
]
}
},
"parameters": {
"n": 4,
"noise_level": 300,
"ref_prompt_weight": 0.5,
"scene_type": "GENERAL"
}
}'响应示例
{
"output": {
"task_id": "xxxxxxxx",
"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.results | Object | 模型生成的结果对象 | ||
output.results.urls | Array | 生成的叠加了文字的图片结果。图像分辨率大小与输入input.base_image_url图像的相同 | "result_url": "http://oss.aliyuncs.com/xxx/abc.jpg" | |
output.results.text_result | Object | 文字子结果对象 | ||
output.results.text_result.urls | Array | 生成的未叠加文字的图片结果 | ||
output.results.text_result.params | Array | 对应每一张图的文字参数 | ||
output.results.text_result.params[x].sample_id | integer | 输出图像的索引 | ||
output.results.text_result.params[x].layers[x] | Object | 输出图像中文字图层对象 | ||
output.results.text_result.params[x].layers 中的文字图层 | type | String | 固定值 "text" | |
sub_type | String | 文本类型，如Title：主标题，SubTitle：副标题 | ||
content | String | 文本内容，默认“标题” | ||
idx | Integer | 图层索引，从0开始 | ||
font_family | String | 使用的字体名称，目前支持的包括：阿里巴巴普惠体、站酷文艺体、钉钉进步体 | ||
font_size | Integer | 文字字号大小 | ||
font_weight | String | 字重，可选值包括：bold, normal, light | ||
font_color | String | 字体颜色，采用HEX表示的RGB | ||
direction | String | 文字方向。horizon：水平；vertical：垂直 | ||
alignment | String | 对齐方式：left、middle、right | ||
opacity | Float | 透明度，0~1，1完全不透明 | ||
fontItalic | Bool | 是否斜体 | ||
font_line_through | Bool | 是否删除线 | ||
font_under_line | Bool | 是否下划线 | ||
top | Integer | 文本框坐标的上 | ||
left | Integer | 文本框坐标的左 | ||
width | Integer | 文本框坐标的宽度 | ||
height | Integer | 文本框坐标的高度 | ||
text_shadow | Integer | 文字x方向和y方向的阴影大小与颜色，无阴影则输出None | "2px 2px #80808080" | |
text_stroke | String | 文字描边像素大小和颜色，无描边则输出None | "1px #fffffff0" | |
output.results.text_result.params[x].layers 中的蒙版图层 | type | String | 固定值 "text_mask" | |
idx | Integer | 图层索引，大于0的整数 | ||
opacity | Float | 透明度，0~1，1完全不透明 | ||
top | Integer | 文本框坐标的上 | ||
left | Integer | 文本框坐标的左 | ||
width | Integer | 文本框坐标的宽度 | ||
height | Integer | 文本框坐标的高度 | ||
gradient | Object | 无渐变时，值为null； 有渐变时，类似Fabric.js的格式。color表示颜色，coords决定渐变的方向 | { "color_stops": [ { "color": "#f1cfdb", "offset": 0.5 }, { "color": "#f1cfdb", "offset": 0.5 } ], "coords": { "x1": 256, "x2": 256, "y1": 0, "y2": 248 }, "gradient_units": "pixels", "type": "linear" } | |
radius | Integer | 圆角半径，大于0的整数 | ||
box_shadow | String | 蒙版阴影效果，x方向和y方向的阴影大小和颜色，无阴影则输出None | "2px 2px #80808080" | |
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小时，需要用户在获取作业结果后根据需要及时使用或者转存。
{
"output":{
"task_id":"a8532587-fa8c-4ef8-82be-0c46b17950d1",
"task_status":"SUCCEEDED",
"results":[
{
"url":"https://xxx/1.jpg"
},
{
"url":"https://xxx/2.jpg"
},
{
"url":"https://xxx/3.jpg"
}
],
"text_result":{
"urls": [
{
"url":"https://xxx/1.jpg"
},
{
"url":"https://xxx/2.jpg"
},
{
"url":"https://xxx/3.jpg"
}
],
"params": [
{
"sample_idx": 1,
"layers": [
{
"type": "text_mask",
"idx": 0,
"color": "#f2eee4",
"opacity": 0.8,
"top": 0,
"left": 0,
"width": 768,
"height": 340,
"radius": 0,
"gradient": {
"type": "linear",
"gradient_units": "pixels",
"coords": {
"x1": 0,
"y1": 340,
"x2": 0,
"y2": 0
},
"color_stops": [
{
"offset": 0,
"color": "#f2eee400"
},
{
"offset": 1,
"color": "#f2eee4ff"
}
]
}
},
{
"type": "text",
"sub_type": "Title",
"content": "分享好时光",
"idx": 1,
"font_size": 98,
"font_family": "阿里巴巴普惠体",
"direction": "horizontal",
"alignment": "center",
"font_color": "#5b4c2f",
"opacity": 1,
"font_weight": "Regular",
"font_italic": false,
"font_line_through": false,
"font_under_line": false,
"top": 34,
"left": 88,
"width": 591,
"height": 98,
"line_height": 1,
"text_shadow": "0px 0px #80808080",
"text_stroke": "0px #fffffff0"
},
{
"type": "text_mask",
"idx": 2,
"color": "#5b4c2f",
"opacity": 1,
"top": 152,
"left": 235,
"width": 297,
"height": 65,
"radius": 40,
"gradient": {
"type": "linear",
"gradient_units": "pixels",
"coords": {
"x1": 0,
"y1": 0,
"x2": 0,
"y2": 65
},
"color_stops": [
{
"offset": 0,
"color": "#5b4c2fff"
},
{
"offset": 1,
"color": "#5b4c2fff"
}
]
},
"box_shadow": "2px 0px #80808080"
},
{
"type": "text",
"sub_type": "Title",
"content": "只为不一样的你",
"idx": 3,
"font_size": 35,
"font_family": "阿里巴巴普惠体",
"direction": "horizontal",
"alignment": "center",
"font_color": "#f2ede3",
"opacity": 1,
"font_weight": "Medium",
"font_italic": false,
"font_line_through": false,
"font_under_line": false,
"top": 152,
"left": 235,
"width": 297,
"height": 65,
"line_height": 1,
"text_shadow": 0
}
]
},
{
"sample_idx": 0,
"layers": [
{
"type": "text_mask",
"idx": 0,
"color": "#e7a047",
"opacity": 0.8,
"top": 0,
"left": 0,
"width": 768,
"height": 340,
"radius": 0,
"gradient": {
"type": "linear",
"gradient_units": "pixels",
"coords": {
"x1": 0,
"y1": 340,
"x2": 0,
"y2": 0
},
"color_stops": [
{
"offset": 0,
"color": "#e7a04700"
},
{
"offset": 1,
"color": "#e7a047ff"
}
]
}
},
{
"type": "text",
"sub_type": "Title",
"content": "分享好时光",
"idx": 1,
"font_size": 98,
"font_family": "阿里巴巴普惠体",
"direction": "horizontal",
"alignment": "center",
"font_color": "#2f1905",
"opacity": 1,
"font_weight": "Regular",
"font_italic": false,
"font_line_through": false,
"font_under_line": false,
"top": 34,
"left": 88,
"width": 591,
"height": 98,
"line_height": 1,
"text_shadow": "1px 0px #80808080",
"text_stroke": "0px #fffffff0"
},
{
"type": "text_mask",
"idx": 2,
"color": "#2f1905",
"opacity": 1,
"top": 152,
"left": 235,
"width": 297,
"height": 65,
"radius": 40,
"gradient": {
"type": "linear",
"gradient_units": "pixels",
"coords": {
"x1": 0,
"y1": 0,
"x2": 0,
"y2": 65
},
"color_stops": [
{
"offset": 0,
"color": "#2f1905ff"
},
{
"offset": 1,
"color": "#2f1905ff"
}
]
},
"box_shadow": "0px 2px #80808080"
},
{
"type": "text",
"sub_type": "Title",
"content": "只为不一样的你",
"idx": 3,
"font_size": 35,
"font_family": "阿里巴巴普惠体",
"direction": "horizontal",
"alignment": "center",
"font_color": "#dc9f65",
"opacity": 1,
"font_weight": "Medium",
"font_italic": false,
"font_line_through": false,
"font_under_line": false,
"top": 152,
"left": 235,
"width": 297,
"height": 65,
"line_height": 1,
"text_shadow": 0
}
]
},
{
"sample_idx": 2,
"layers": [
{
"type": "text_mask",
"idx": 0,
"color": "#cf9a5a",
"opacity": 0.8,
"top": 0,
"left": 0,
"width": 768,
"height": 340,
"radius": 0,
"gradient": {
"type": "linear",
"gradient_units": "pixels",
"coords": {
"x1": 0,
"y1": 340,
"x2": 0,
"y2": 0
},
"color_stops": [
{
"offset": 0,
"color": "#cf9a5a00"
},
{
"offset": 1,
"color": "#cf9a5aff"
}
]
}
},
{
"type": "text",
"sub_type": "Title",
"content": "分享好时光",
"idx": 1,
"font_size": 100,
"font_family": "阿里巴巴普惠体",
"direction": "horizontal",
"alignment": "center",
"font_color": "#191208",
"opacity": 1,
"font_weight": "Regular",
"font_italic": false,
"font_line_through": false,
"font_under_line": false,
"top": 121,
"left": 84,
"width": 600,
"height": 100,
"line_height": 1,
"text_shadow": "2px 3px #80808080",
"text_stroke": "0px #fffffff0"
},
{
"type": "text_mask",
"idx": 2,
"color": "#191208",
"opacity": 1,
"top": 35,
"left": 233,
"width": 302,
"height": 66,
"radius": 40,
"gradient": {
"type": "linear",
"gradient_units": "pixels",
"coords": {
"x1": 0,
"y1": 0,
"x2": 0,
"y2": 66
},
"color_stops": [
{
"offset": 0,
"color": "#191208ff"
},
{
"offset": 1,
"color": "#191208ff"
}
]
},
"box_shadow": "2px 0px #80808080"
},
{
"type": "text",
"sub_type": "Title",
"content": "只为不一样的你",
"idx": 3,
"font_size": 36,
"font_family": "阿里巴巴普惠体",
"direction": "horizontal",
"alignment": "center",
"font_color": "#fbf0e1",
"opacity": 1,
"font_weight": "Medium",
"font_italic": false,
"font_line_through": false,
"font_under_line": false,
"top": 35,
"left": 233,
"width": 302,
"height": 66,
"line_height": 1,
"text_shadow": 0
}
]
}
]
}
},
"usage":{
"image_count":4
},
"request_id":"7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}响应示例（作业失败）
如果因为某种原因作业失败，则作业状态会设置为FAILED，并且通过code和message字段指明错误原因。
{
"request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
"output": {
"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
"task_status": "FAILED",
"code": "xxx",
"message": "xxxxxx",
}
}状态码说明
大模型服务通用状态码请查阅：状态码说明
- 本页导读 （1）