文档

图像背景生成API详情

更新时间:

图像背景生成

说明

支持的领域 / 任务:aigc /图像背景生成

通义万相-图像背景生成可以基于输入的前景图像素材拓展生成背景信息,实现自然的光影融合效果,与细腻的写实画面生成。

支持文本描述、图像引导等多种方式,同时支持对生成的图像智能添加文字内容。支持通用、家居和美妆分场景的多个预设模型。支持边缘引导元素生成,指定背景生成图片里有前景和背景特定内容元素引导生成。

生成方式&效果示意:

20230919142710.jpg

模型概览

模型名

模型简介

wanx-background-generation-v2

通义万相-图像背景生成可以基于输入的前景图像素材拓展生成背景信息,实现自然的光影融合效果,与细腻的写实画面生成。支持文本描述、图像引导等多种方式,同时支持对生成的图像智能添加文字内容。

HTTP调用接口

功能描述

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

前提条件

说明

接口限制:对单账户(含主账号与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-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种场景:

  • GENERAL: 通用场景,默认值

  • ROOM: 室内家居场景

  • COSMETIC:美妆场景,也适用于大部分小商品摆放场景

边缘引导元素生成方法

  1. PS抠图,导出带透明背景的4通道格式图像

  2. 环境准备:

  pip install controlnet-aux==0.0.7
  1. 运行代码:

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

状态码说明

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

  • 本页导读 (0)