图片编辑数据结构--veImageX-火山引擎

文档中心

veImageX

模板管理

图片编辑数据结构

基础功能

操作	操作名称	参数名称	参数类型	是否必填	参数描述
亮度	bright	bright	Float	是	调整图片亮度，取值范围为[-100, 100]。
对比度	contrast	contrast	Float	是	调整图片对比度，取值范围为[-100, 100]。
负片	invert	-	-	-	指定时即可使用负片效果，其效果暂不支持更改配置。
锐化	sharpen	sharpen	Float	是	锐化图片，取值范围为[0,100]。
高斯模糊	blur	sigma	Float	是	高斯模糊图片，取值 > 0，值越大图像越模糊。
旋转	rotate	angle	Float	是	旋转图片角度，取值范围为[0, 360]。
		bgcolor	String	否	旋转后填充的背景色，以 # 开始，后面跟 RGB 的十六进制值。
		bgalpha	Integer	否	旋转后填充背景色的透明度，取值范围为[0, 100]。
翻转	flip	flip	Integer	是	图片内容的翻转类型，取值如下所示： `1`：水平翻转图片； `2`：垂直翻转图片。
缩放	resize	width	Integer	是	缩放后图片的宽，取值为`0`表示按照宽高比自适应。
		height	Integer	是	缩放后图片的高，取值为`0`表示按照宽高比自适应。
		keepratio	bool	否	缩放后是否保持原图宽高比。取值如下所示： `true`：保持原图宽高比； `false`：不保持原图宽高比。
		mode	String	否	`keepratio`取值为`true`时必选的等比缩放模式，取值如下所示： `contain`：结果图宽高均不超过设置值，缩放图限制为设置宽高矩形容器内最大图； `cover`：结果图宽或高超过设置值，缩放图为延伸出设置宽高矩形容器框外最小图。
		policy	Integer	否	缩放适配，取值如下所示： `0`：表示缩放均可； `1`：表示只放大图片； `2`：表示只缩小图片。
裁剪	crop	crop	Integer	是	裁剪方式，取值如下所示： `1`：居上裁剪； `2`：居下裁剪； `3`：居左裁剪； `4`：居右裁剪； `5`：居中裁剪； `6`：按坐标裁剪； `9`：内切圆裁剪； `11`：定向裁剪。
		width	Integer	是	裁剪后图像宽度，仅当选择定向裁剪时可设置，若裁剪宽度不指定，默认为 0，即为原图宽度。
		height	Integer	是	裁剪后图像高度，仅当选择定向裁剪时可设置，若裁剪高度不指定，默认为 0，即为原图高度。
		lx	Integer	是	确定最终裁剪范围，仅按坐标裁剪时有效，(lx, ly)表示裁剪区域左上角坐标。
		ly	Integer	否	确定最终裁剪范围，仅按坐标裁剪时有效，(lx, ly)表示裁剪区域左上角坐标。
		rx	Integer	否	确定最终裁剪范围，仅按坐标裁剪时有效，(rx, ry)表示裁剪区域右下角坐标。
		ry	Integer	否	确定最终裁剪范围，仅按坐标裁剪时有效，(rx, ry)表示裁剪区域右下角坐标。
		radius	Integer	是	内切圆半径。仅当选择内切圆裁剪时设置有效，取值为整数，取值范围为[1，2048]。如果指定半径大于原图最大内切圆的半径，则圆的大小仍然是图片的最大内切圆。如果图片的最终格式是 png、webp 等支持透明通道的格式，则图片非圆形区域的地方将以透明填充。如果图片的最终格式是 jpg，则非圆形区域是以白色进行填充。推荐您保存成 png 格式。
		fix_crop_loc	Integer	否	说明 `fix_crop_loc` 和 `gravity` 二选一传入，同时传入时以 `gravity` 为准，`fix_crop_loc` 不作处理。指定定向裁剪的原点位置，取值范围为 [0,8]，具体原点位置对应关系请见定向裁剪原点示意图。
		fix_crop_x	Integer	否	定向裁剪的 X 方向偏移量，默认左上角为原点，取值范围为[0，图片边界]。取值如下所示： X > 0：向右偏移； X < 0：向左偏移。
		fix_crop_y	Integer	否	定向裁剪的 Y 方向偏移量，默认左上角为原点，取值范围为[0，图片边界]。取值如下所示： Y > 0：向下偏移； Y < 0：向上偏移。
		gravity	String	否	说明 `fix_crop_loc` 和 `gravity` 二选一传入，同时传入时以 `gravity` 为准，`fix_crop_loc` 不作处理。如果创建模板时，配置了 `gravity`，但实际的 URL 未传入原点位置，请求会报错。指定定向裁剪时的裁剪原点位置使用 URL 输入方式，取值固定为 `${crop_gravity}`。启用 URL 输入后，请在获取资源 URL 后拼接裁剪原点位置，各裁剪原点位置取值如下。左上：`northwest` 左中：`west` 左下：`southwest` 中上：`north` 居中：`center` 中下：`south` 右上：`northeast` 右中：`east` 右下：`southeast` 以 `http://test.example.com/tos-cn-example.png~tplv-example-001:{crop_gravity}.image` 为例，您应使用实际的原点位置替换 `{crop_gravity}`。
贴边裁剪	trimv2	lmargin	Integer	是	图片内容左侧保留像素，即设置的边框距离原图中内容的距离，默认为 0。
		rmargin	Integer	是	图片内容右侧保留像素，即设置的边框距离原图中内容的距离，默认为 0。
		tmargin	Integer	是	图片内容上侧保留像素，即设置的边框距离原图中内容的距离，默认为 0。
		bmargin	Integer	是	图片内容下侧保留像素，即设置的边框距离原图中内容的距离，默认为 0。
		minw	Integer	是	图片最小输出宽度。默认为 0，单位为 px，表示原图的宽。与最小输出高度决定输出处理最小图片，若裁剪图大于该设置值时，输出裁剪图；裁剪图小于设置值时，将以原图的背景色补充剩余图片位置输出处理图。
		minh	Integer	是	图片最小输出高度。默认为 0，单位为 px，表示原图的高。与最小输出宽度决定输出处理最小图片，裁剪图大于该设置值时，输出裁剪图；裁剪图小于设置值时，将以原图的背景色补充剩余图片位置输出处理图。
智能人脸裁剪	smartv2	scene	String	是	裁剪场景。取值如下所示： `normal`：普通人脸裁剪； `cartoon`：动漫人脸裁剪。
		width	Integer	是	裁剪后图片的宽，单位为 px。默认为 0，表示原图的宽和高。当图片小于设置的宽高时，将不被裁剪。
		height	Integer	是	裁剪后图片的高，单位为 px。默认为 0，表示原图的宽和高。当图片小于设置的宽高时，将不被裁剪。
		policy	Integer	是	当裁剪失败时如何降级，取值如下所示： `1`：居中裁剪； `2`：高斯模糊； `3`：居上裁剪。
		sigma	Integer	否	高斯模糊参数。
图文水印	watermark	pic.uri	String	否	上传的水印图片 URI，缺省情况下则不加图片水印。
		pic.opacity	Integer	否	水印图片的透明度，取值范围为[0, 100]。
		text.location	Integer	否	增加图文水印时文本水印相对于图片水印的位置。取值如下所示： `0`：在图片水印右侧，缺省情况下默认为图片水印右侧； `1`：在图片水印左侧； `2`：在图片水印上侧； `3`：在图片水印下侧。
		text.dx	Integer	否	文本水印相对于图片水印的水平偏移。
		text.dy	Integer	否	文本水印相对于图片水印的垂直偏移。
		text.content	String	否	文本水印内容。缺省情况下则不加文本水印。如果通过 URL 参数传入，需要事先经过 Base64 URL Safe 编码。
		text.font	String	否	文本水印字体。支持传入的字体请参考支持字体列表。缺省情况下默认使用思源黑体。
		text.size	Integer	否	文本的字号，单位为磅，不传或者传 0 则使用默认值 30。最大值为 200。
		text.color	String	否	文本颜色，以 # 开始，后面跟 RGB 的十六进制值。不传或者传空则默认使用白色。
		text.opacity	Integer	否	文本水印的透明度，取值范围为[0, 100]。
		text.align	Integer	否	多行文本对齐方式。取值如下所示： `0`：表示左对齐； `1`：表示居中对齐； `2`：表示右对齐。
		text.linespace	Float	否	多行文本行间距，为相对与单行文本高度的比例。
		text.shadow	Bool	否	文本是否有阴影，缺省情况下表示不带阴影。
		text.shadow.color	String	否	文本阴影颜色，以 # 开始，后面跟 RGB 的十六进制值。不传或者传空则默认使用黑色。
		text.shadow.opacity	Integer	否	文本阴影的透明度，取值范围为[0, 100]。
		text.shadow.blur	Float	否	文本阴影的高斯模糊值，取值 > 0，值越大则越模糊。
		text.shadow.dx	Integer	否	文本阴影的水平偏移，负值表示阴影在文本左侧，正值表示阴影在文本右侧。偏移的绝对值不能超过5。
		text.shadow.dy	Integer	否	文本阴影的垂直偏移，负值表示阴影在文本上侧，正值表示阴影在文本下侧。偏移的绝对值不能超过5。
		water.angle	Float	否	图文水印的角度，取值范围为[0, 360]。
		water.full	Bool	否	是否开启水印铺满，不传表示仅在 adapt.location 处展示水印。
		full.xratio	Float	否	水印铺满 X 向间距 = 水印宽 * xratio，传 0 或不传表示 X 向间距为 0。
		full.yratio	Float	否	水印铺满 Y 向间距 = 水印高 * yratio，传 0 或不传表示 Y 向间距为 0。
		water.random	Bool	否	图文水印位置是否为随机，默认不随机。取值如下所示： `true`：位置随机； `false`：位置不随机。
		adapt.location	Integer	是	图文水印所在位置编号，将图片划分为 9 宫格，从左到右，从上到下，依次从 1 到 9 编号。如下图所示。
		adapt.xym_same	Bool	否	水平和垂直边距是否保持相同，取值如下所示： `true`：表示保持边距相等； `false`：表示不保持边距相等。
		adapt.wratio	Float	是	图文水印相对于底图的宽度最小值。自适应公式搭配`wratio`和`wratio_max`值，设置水印相对底图的宽度。
		adapt.wratio_max	Float	否	图文水印相对于底图的宽度最大值。自适应公式搭配`wratio`和`wratio_max`值，设置水印相对底图的宽度。
		adapt.xmratio	Float	是	相对位置下图文水印水平边距，取值范围为[0,1]。
		adapt.ymratio	Float	是	相对位置下图文水印垂直边距系数，取值范围为[0,1]。
		adapt.xm_max	Integer	否	图文水印水平边距最大值。传 0 或者不传表示无限制。
		adapt.ym_max	Integer	否	图文水印垂直边距最大值。传 0 或者不传表示无限制。
		adapt.dx	Integer	否	绝对位置下图文水印距离底图的水平边距，超出底图水印部分不显示。
		adapt.dy	Integer	否	绝对位置下图文水印距离底图的垂直边距，超出底图水印部分不显示。
圆角矩形	round-corner	type	String	是	圆角类型，取值如下所示： `circle`：圆 `ellipse`：椭圆
		radius	Integer	否	仅当`type`取值为`circle`时代表圆角半径。
		radius_x	Integer	否	仅当`type`取值为`ellipse`时代表椭圆半长轴长度。
		radius_y	Integer	否	仅当`type`取值为`ellipse`时代表椭圆半短轴长度。
饱和度	saturation	saturation	Float	是	图片饱和度，取值范围为[-100,100]。当输入值为 0 时饱和度不变，当输入值为 -100 时图像为灰度图。
图片打码	mosaic	loc	Integer	否	打码位置，取值如下所示： `0`：全图 `1`：指定位置
		bbox	Array[Integer]	否	指定打码位置时左上角与右下角坐标值。4 个为一组，表示矩形位置，[x0,y0,x1,y1]
		type	Integer	否	打码类型，取值如下所示： `0`：像素格 `1`：指定图片
		shape	Integer	否	打码形状，取值如下所示： `0`：正方形 `1`：椭圆形
		uri	String	否	待打码图片存储 URI。
		stepx	Integer	是	像素格宽，单位为 px，值越大越模糊。
		stepy	Integer	是	像素格高，单位为 px，值越大越模糊。

附加组件

请在控制台开通指定的附加组件能力后，再创建对应能力的图片模板。

操作	操作名称	参数名称	参数类型	是否必填	参数描述
图像降噪	denoise	mode	String	是	模型，默认为 `general_model`，即通用模型。
		intensity	Float	是	降噪强度，取值范围为[0,1]。取值为`0`时表示不降噪，取值越大降噪强度越大。
		can_demotion	Boolean	否	降级设置，取值如下所示： `false`：（默认）优先返回处理后的图片; `true`：优先响应原图
画质评分	quality	ratio	Integer	是	采样率，取值范围为[0,100]，取值为0时则代表源站请求均不会进入打分环节，取值为 100 时代表默认源站请求全部会进入打分环节。
画质评分	quality	types	String	是	画质评估项，取值如下所示： `vqscore`：主观质量 `aesthetic`：大众美学 `noise`：噪声强度
图像超分辨率（云端）	super_resolution	mode	Integer	是	超分模型，取值如下所示： `0`：超分普通模型 `1`：超分增强模型 `2`：超分 VR 模型
		can_demotion	Boolean	否	降级设置，取值如下所示： `false`：（默认）优先返回处理后的图片; `true`：优先响应原图
		long_max	Float	是	仅当满足图像边界输入的图像执行超分处理，超分允许处理的长边范围最大值。取值为 0 时，代表忽略输入限制。
		long_min	Float	是	仅当满足图像边界输入的图像执行超分处理，超分允许处理的长边范围最小值。取值为 0 时，代表忽略输入限制。
		short_max	Float	是	仅当满足图像边界输入的图像执行超分处理，超分允许处理的短边范围最大值。取值为 0 时，代表忽略输入限制。
		short_min	Float	是	仅当满足图像边界输入的图像执行超分处理，超分允许处理的短边范围最小值。取值为 0 时，代表忽略输入限制。
		multiple	Float	是	输出倍率。当`mode`取值为`0/1`时，该值的取值范围为[2,8]的整数。当`mode`取值为`2`时，该值的取值范围为[1,2]，支持两位小数，超过 3k * 6k 的图片仅支持 1 倍超分。
		policy	Integer	是	图像边界输入的逻辑计算方式，取值如下所示： `0`：同时满足长边和短边要求 `1`：任意满足长边或短边要求
		save_tos	Boolean	否	是否存储结果图，取值如下所示： `false`：（默认）不存储 `true`：存储
		denoise_ratio	Float	当`mode`取值为`2`时，必填	仅当`mode`取值为`2`时，支持设置该值。降噪强度，取值范围为(0, 1)。
		sharp_ratio	Float	当`mode`取值为`2`时，必填	仅当`mode`取值为`2`时，支持设置该值。锐化强度，取值范围为(0, 1)。
集智瘦身	slim	can_demotion	Boolean	是	是否允许降级，取值如下所示： `false`：优先返回处理后的图片; `true`：优先响应原图
		mode	Integer	是	模型，固定取值为`0`，表示通用瘦身模型。
		save_tos	Boolean	否	是否存储结果图，取值如下所示： `false`：（默认）不存储 `true`：存储当 `async` 为 `true` 时，本项必须为 true。
		async	Boolean	否	是否首次访问直接降级 `false`：（默认）首次访问不直接降级 `true`：首次访问直接降级
智能背景移除	segment	can_demotion	Boolean	是	是否允许降级，取值如下所示： `false`：优先返回处理后的图片; `true`：优先响应原图
		mode	Integer	是	处理模式：取值如下所示： `0`：粗线条处理，效率更优； `1`：发丝级细线条处理，效果更优
		object_class	Integer	是	处理模型，取值如下所示： `0`：通用模型 `1`：人像模型v1 `2`：商品模型v1 `3`：人像模型v2 `4`：商品模型v2
		save_tos	Boolean	否	是否存储结果图，取值如下所示： `false`：（默认）不存储 `true`：存储
		contour_color	String	否	仅当`object_class`取值 `3/4` 时，为必填。描边颜色。支持以 HEX、HSL、RGP 表示。例如`HEX`中白色为`#FFFFFF`。
		contour_size	Integer	否	仅当`object_class`取值 `3/4` 时，为必填。描边粗细。单位为 px。取值范围为 0 到正整数，默认 10px。
盲水印	hidden_mark	info	String	是	水印内容。不超过 16 字。
		strength	Integer	是	算法强度，强度越高，图像抵抗攻击性能越强。取值如下所示： `low`：低强度，适用于纯色图场景以及对图像质量要求高； `medium`：中强度，默认中强度； `strong`：高强度，适合图像纹理丰富时使用。
		algorithm	Integer	是	算法模型，取值如下所示： `default`：文本嵌入模型，默认文本嵌入模型； `adapt_resize`：画质自适应文本嵌入模型。
图像修复	erasev2	model	String	是	修复模型，固定取值为`eraser_model_imagex_0.1.0`，即自动检测并擦除类型模型。
		bbox	List Of 0..1	是	处理范围矩形框。长度为 4 的 0-1 浮点数数组
		user_ocr	list	否	是否指定文本擦除，取值如下所示： `0`：（默认值）关闭 `1`：开启。仅当开启后，匹配模式和匹配文本才会生效。
		ocr_mode	list	否	匹配模式，仅支持取值为 `1`，表示模糊匹配。若输入文字内容，则擦除目标区域内包含该文字的对应文本行全部内容；若不输入文字内容，则擦除目标区域内所有检测到的文字内容。
		text	list	否	匹配文本
图像增强	enhance	mode	Integer	是	模型，取值如下所示： `0`：通用模型 `1`：低质专清模型 `3`：画质优化模型
		can_demotion	Boolean	是	是否允许降级，取值如下所示： `false`：优先返回处理后的图片; `true`：优先响应原图
		save_tos	Boolean	否	是否存储结果图，取值如下所示： `false`：（默认）不存储 `true`：存储
	adapt_enhance	can_demotion	Boolean	是	是否允许降级，取值如下所示： `false`：优先返回处理后的图片; `true`：优先响应原图
		save_tos	Boolean	否	是否存储结果图，取值如下所示： `false`：（默认）不存储 `true`：存储
		actions	Array of actions	是	高级处理配置

actions

参数名称	参数类型	是否必填	参数描述
Name	String	是	自适应增强处理场景，取值如下所示： `face_enhance`：人脸增强 `low_quality`：低质增强 `low_quality_deblur`：低质增强-去模糊化 `super_resolution`：图像超分
Param	Array of Params	是	具体参数配置

参数名称

参数类型

是否必填

参数描述

Name

String

是

自适应增强处理场景，取值如下所示：

face_enhance：人脸增强
low_quality：低质增强
low_quality_deblur：低质增强-去模糊化
super_resolution：图像超分

Param

Array of Params

是

具体参数配置

Params

参数名称	参数类型	是否必填	参数描述
face_cnt_max	String	否	当 `Name` 为 `face_enhance` 时，为必填。最大处理人脸数量。取值为大于 0 的整数，默认值为 3。图像中人脸数目大于输入值时不执行增强，返回原图。
low_quality.long_max	Integer	否	当 `Name 为 low_quality` 时，为必填。处理支持的最长边
low_quality.long_min	Integer	否	当 `Name` 为 `low_quality` 时，为必填。处理支持的最短边
low_quality_deblur.face_cnt_max	String	否	当 `Name` 为 `low_quality_deblur` 时，为必填。最大处理人脸取值为大于等于 -1 的整数。默认人脸数量值为 -1，表示图像内人脸都执行增强。图像人脸数目大于输入值时不执行增强，返回原图。
long_max	Integer	否	当 `Name` 为 `super_resolution` 时，为必填。最长边的最大值
long_min	Integer	否	当`Name` 为 `super_resolution` 时，为必填。最长边的最小值
multiple	String	否	超分倍数，仅支持 2 倍和 4 倍，默认为 2 倍超分。4 倍超分辨率只适用于 1024 x 1024 以下分辨率图像的画质增强。

其他说明

定向裁剪原点示意图

图文水印指定位置示意图

最近更新时间：2025.12.16 16:12:04

这个页面对您有帮助吗？

有用

无用

veImageX

基础功能 #

附加组件 #

actions #

Params #

其他说明 #

定向裁剪原点示意图 #

图文水印指定位置示意图 #

基础功能

附加组件

actions

Params

其他说明

定向裁剪原点示意图

图文水印指定位置示意图