样式结构--veImageX-火山引擎

文档中心

导航

样式结构

最近更新时间：2023.02.02 19:11:14首次发布时间：2022.07.20 10:06:05

坐标轴定义

原点：画布左上角
X 轴：延画布左上角至右上角
Y 轴：延画布左上角至左下角

样式定义

参数	类型	是否必填	描述
id	String	是	样式 ID，新建样式时后端生成的唯一标识 ID。
name	String	是	样式名称。
width	Integer	是	画布宽度，取值范围为 (0, 10000]。
height	Integer	是	画布高度，取值范围为 (0, 10000]。
unit	String	否	尺寸单位。表示画布宽度和画布高度的像素单位，取值为`px`。
service	String	是	样式绑定的服务 ID。
background	JSON Object	否	画布背景。默认白底，宽高与画布保持一致。
elements	Array of elements	否	画布包含的要素列表，数组顺序即为要素渲染顺序。
output	JSON Object	否	输出图片设置，默认输出 webp 格式。支持以下取值： jpeg png webp heic

background

参数类型是否必填描述

参数	类型	是否必填	描述
fill	String	否	背景颜色，以 # 开始，后面跟 RGB 的十六进制值。传 6 位 HEX 代表 RGB 值，默认不透明。传 8 位 HEX 代表 RGBA 值，默认白色。
fillSrc	String	否	背景图的 URL 或 URI。
viewpoint	JSON Object	否	当 `fillSrc` 不为空时必填，用于指定背景图的绘制区域。该区域宽高比应等于画布的宽高比，选中背景图区域后会将该区域缩放至画布大小。

fill

String

否

背景颜色，以 # 开始，后面跟 RGB 的十六进制值。

传 6 位 HEX 代表 RGB 值，默认不透明。
传 8 位 HEX 代表 RGBA 值，默认白色。

fillSrc String 否背景图的 URL 或 URI。

viewpoint

JSON Object

否

当 fillSrc 不为空时必填，用于指定背景图的绘制区域。
该区域宽高比应等于画布的宽高比，选中背景图区域后会将该区域缩放至画布大小。

viewpoint

参数	类型	是否必填	描述
x	Float	否	图片绘制的左上角横坐标 = 图片宽度 * x ，取值范围为 [0,1)。默认值为 0。
y	Float	否	图片绘制的左上角纵坐标 = 图片高度 * y ，取值范围为 [0,1)。默认值为 0。
width	Float	否	图片绘制的宽 = 图片宽度 * width ，取值范围为 (0,1]。默认值为 1。
height	Float	否	图片绘制的高 = 图片高度 * height ，取值范围为 (0,1]。默认值为 1。

elements

参数	类型	是否必填	描述
id	String	是	要素 ID，样式内唯一标识。
name	String	否	要素名称。
type	String	是	要素类型，取值如下所示： image：图片 qrcode：二维码 text：文字 shape：形状
left	Integer	是	要素左上角横坐标。
top	Integer	是	要素左上角纵坐标。
width	Integer	是	要素宽，取值范围为 (0, 10000]。
height	Integer	是	要素高，取值范围为 (0, 10000]。
content	String	是	要素内容，可通过参数动态替换该字段值。当`type=image`时，取值图片 URL 或 URI；当`type=text`时，取值文本内容；当`type=qrcode`时，取值二维码内容；
opacity	Integer	否	要素透明度，取值范围为 [0,100]。默认值为 100，不透明。
angle	Float	否	要素旋转角度。为相对要素中心点逆时针旋转角度，取值范围为 [0,360]。
flipX	Bool	否	是否水平翻转要素，默认值为 `false`。取值如下所示： true：翻转； false：不翻转。
flipY	Bool	否	是否垂直翻转要素，默认值为 `false`。取值如下所示： true：翻转； false：不翻转。
attr	JSON Object	是	要素属性。

attr

要素类型	type	参数	类型	是否必填	描述
图片	image	fillptn	JSON Object	是	图片填充策略。
		filter	Array of image.filter	否	图片处理操作列表。
		mask	JSON Object	否	图片蒙版设置。
文字	text	font	String	否	文字字体，默认为思源黑体。支持字体取值请参考字体列表。
		fontSize	Float	否	文字字号。默认值 30，单位为 px。仅当`fontAdapt`取值为`false`时生效。
		fontAdapt	Bool	否	是否开启字号自适应。仅当`adapt`取值为`false`时生效。
		fillptn	JSON Object	否	文字颜色填充模式，默认以纯白色填充。
		textAlign	Integer	否	多行文本对齐方式，取值如下所示： 0：左对齐/上对齐； 1：居中对齐； 2：右对齐/下对齐； 3：两端对齐。
		textAlignH	Integer	否	文本内容相对于文字框的对齐方式，取值如下所示： 0：上对齐/右对齐； 1：居中对齐； 2：下对齐/左对齐。
		lineSpace	Float	否	多行文本行间距，为相对于单行文本高度的比例。默认值为 1.2 倍行距，取值范围为[0.5,2.5]。说明因文本框大小等限制，结果图中文本行间距调整效果可能无法按预期呈现，例如部分文字的显示不全。
		wordSpace	Float	否	文字字间距，单位为 1/1000 em。默认值为 0，取值范围为[-1000,2000]。
		writingMode	Integer	否	文本绘制模式，取值如下所示： 0：从左往右； 1：从上往下。
		bold	Bool	否	是否加粗，取值如下所示： true：加粗； false：不加粗。
		oblique	Bool	否	是否倾斜，取值如下所示： true：倾斜； false：不倾斜。
		linethrough	Bool	否	是否添加删除线，取值如下所示： true：添加； false：不添加。
		underline	Bool	否	是否添加下划线，取值如下所示： true：添加； false：不添加。
		adapt	Bool	否	是否自适应，取值如下所示： true：不自动换行，要素长度等于单行文本的最大长度； false：将根据要素大小自动换行。
		border	JSON Object	否	文字边框，默认无边框。
二维码	qrcode	type	Integer	是	二维码类型，取值如下所示： 0：文本； 1：网页链接。
形状	shape	type	String	是	形状类型，取值如下所示： line：线； rect：矩形； circle：圆。
		fillColor	String	是	填充颜色。以 # 开始，后面跟 RGB 的十六进制值。传 6 位 HEX 代表 RGB 值，默认不透明；传 8 位 HEX 代表 RGBA 值。
		strokeColor	String	否	描线颜色。以 # 开始，后面跟 RGB 的十六进制值。传 6 位 HEX 代表 RGB 值，默认不透明；传 8 位 HEX 代表 RGBA 值。
		weight	Integer	是	边框粗细，取值范围为 (0,100]。
		dash	Integer	否	虚线 dash 值，取值大于 0，值越大则虚线间的间隔越大。
		radius	Float	否	圆角半径，仅当`type`取值为`rect`时生效。默认值为 0，为矩形边框。

image.fillptn

参数	类型	是否必填	描述
ptn	Integer	是	填充策略，取值如下所示： 0：强制宽高； 1：匹配短边裁剪； 2：匹配长边缩略； 3：固定高度、宽度自适应； 4：固定宽度、高度自适应； 5：不缩放。
viewpoint	JSON Object	否	图片渲染区域，仅当`ptn=0`时生效。
viewLoc	Integer	否	图片展示位置，仅当`ptn不为0`时生效。 1：左上； 2：中上； 3：右上； 4：左中； 5：居中； 6：右中； 7：左下； 8：中下； 9：右下。
bgColor	String	否	背景填充颜色，以 # 开始，后面跟 RGB 的十六进制值。默认空，无填充。

image.filter

参数	类型	是否必填	描述
name	String	是	操作名称。
param	JSON Map	否	操作参数列表。

image.filter.param

编辑操作	name	参数名称	参数类型	是否必填	参数描述
亮度	bright	bright	Float	是	调整图片亮度，取值范围为 [-100, 100]。
对比度	contrast	contrast	Float	是	调整图片对比度，取值范围为 [-100, 100]。
负片	invert	-	-	-	-
锐化	sharpen	sharpen	Float	是	锐化图片，取值大于等于 0。
高斯模糊	blur	sigma	Float	是	高斯模糊图片，取值大于 0。
饱和度	saturation	saturation	Float	是	图片的饱和度，取值范围为 [-100, 100]。

image.mask

参数类型是否必填描述

uri String 是蒙版图片的 TOS URI 或完整 URL（任意公网可访问 URL）。

参数	类型	是否必填	描述
uri	String	是	蒙版图片的 TOS URI 或完整 URL（任意公网可访问 URL）。
fillptn	Integer	是	蒙版填充策略，取值如下所示： 0：强制宽高； 1：匹配短边裁剪； 2：匹配长边缩略； 3：固定高度、宽度自适应； 4：固定宽度、高度自适应； 5：不缩放。
viewLoc	Integer	否	蒙版展示位置，仅当`fillptn不为0`时生效。 1：左上； 2：中上； 3：右上； 4：左中； 5：居中； 6：右中； 7：左下； 8：中下； 9：右下。

fillptn

Integer

是

蒙版填充策略，取值如下所示：

0：强制宽高；
1：匹配短边裁剪；
2：匹配长边缩略；
3：固定高度、宽度自适应；
4：固定宽度、高度自适应；
5：不缩放。

viewLoc

Integer

否

蒙版展示位置，仅当fillptn不为0时生效。

1：左上；
2：中上；
3：右上；
4：左中；
5：居中；
6：右中；
7：左下；
8：中下；
9：右下。

text.fillptn

参数	类型	是否必填	描述
name	String	是	颜色填充模式。
param	JSON Map	是	颜色填充参数。

text.fillptn.param

填充模式	name	参数名称	参数类型	是否必填	参数描述
纯色	color	color	String	是	文字填充颜色。以 # 开始，后面跟 RGB 的十六进制值。传 6 位 HEX 代表 RGB 值，默认不透明。传 8 位 HEX 代表 RGBA 值，默认白色。

填充模式

name

参数名称

参数类型

是否必填

参数描述

纯色

color

String

是

文字填充颜色。以 # 开始，后面跟 RGB 的十六进制值。

传 6 位 HEX 代表 RGB 值，默认不透明。
传 8 位 HEX 代表 RGBA 值，默认白色。

text.border

参数	类型	是否必填	描述
weight	Integer	是	边框粗细。
dash	Integer	否	虚线 dash 值。取值大于 0 时生效，值越大则虚线间的间隔越大，暂无最大限制。
radius	Float	否	圆角半径。默认值为 0，为矩形边框。
color	String	是	边框颜色。以 # 开始，后面跟 RGB 的十六进制值。传 6 位 HEX 代表 RGB 值，默认不透明。传 8 位 HEX 代表 RGBA 值。
paddingTop	Integer	否	上边距，默认值为 0。 `adapt=false`时表示相对文本区域的距离； `adapt=true`时表示相对文本的距离。
paddingBottom	Integer	否	下边距，默认值为 0。 `adapt=false`时表示相对文本区域的距离； `adapt=true`时表示相对文本的距离。
paddingLeft	Integer	否	左边距，默认值为 0。 `adapt=false`时表示相对文本区域的距离； `adapt=true`时表示相对文本的距离。
paddingRight	Integer	否	右边距，默认值为 0。 `adapt=false`时表示相对文本区域的距离； `adapt=true`时表示相对文本的距离。

output

参数	类型	是否必填	描述
format	String	否	渲染结果输出格式，可选取值：JPEG、WEBP、PNG、HEIC。默认 WEBP。
quality	Integer	否	渲染结果编码质量参数，取值范围为 [0,100]。默认值为 75，该值越高则表示结果图编码质量越高。

样式示例

{
    "id": "6130814f8241a65f9838427*",
    "name": "样式示例",
    "width": 1080,
    "height": 1920,
    "unit": "px",
    "service": "241hsrmp5*",
    
    "background": {
        "fill": "#FFFFFF",
        "fillSrc": "imagex-rc/previe*.jpg",
        "viewpoint": {
            "x": 0.25,
            "y": 0,
            "width": 0.5,
            "height": 1
        }
    },
    
    "elements": [
        {
            "id": "ele1",
            "name": "图片要素",
            "type": "image",
            "left": 50,
            "top": 100,
            "width": 400,
            "height": 800,
            "content": "tos-cn-i-19tz3ytenx/2cfccfd443a380b561f12ec385d*.jpg",
            "opacity": 75,
            "attr": {
                "viewpoint": {
                    "x": 0,
                    "y": 0,
                    "width": 1,
                    "height": 1
                },
                "filter": [
                    {
                        "name": "bright",
                        "param": {
                            "bright": 70
                        }
                    }
                ]
            }
        },
        {
            "id": "ele2",
            "name": "文字要素",
            "type": "text",
            "left": 720,
            "top": 300,
            "width": 100,
            "height": 50,
            "content": "这里是文字",
            "attr": {
                "font": "SourceHanSans-Regular.ttf",
                "fontSize": 30,
                "fillptn": {
                    "name": "color",
                    "param": {
                        "color": "#FFFFFF"
                    }
                },
                "textAlign": 0, 
                "lineSpace": 1.2,
                "wordSpace": 0,
                "opacity": 75,
                "writingMode": 0
            }
        },
        {
            "id": "ele3",
            "name": "二维码要素",
            "type": "qrcode",
            "left": 1000,
            "top": 10,
            "width": 80,
            "height": 80,
            "content": "这里是一段文字",
            "attr": {
                "type": 0
            }
        }
    ],
    
    "output" {
        "format": "WEBP",
        "quality": 75
    }
}