T 版用法说明--veImageX-火山引擎

文档中心

立即注册

导航

T 版用法说明

最近更新时间：2025.02.14 11:38:29首次发布时间：2024.10.17 19:17:03

veImageX 当前支持您通过自定义访问 URL 的方式使用 T 版图片处理能力。您可以在源地址访问 URL 后拼接不同处理能力以及对应取值，以实现不同的图片处理效果。具体已支持能力、配置说明及相关访问示例如下所示。

注意事项

原图大小、分辨率等输入限制请参考图片处理使用限制。
该使用方式为白名单能力，使用前请提交工单联系技术支持完成相关配置。

前提条件

已开启自定义处理样式功能。

基础图片处理

快速缩略模版

您可通过以下常用图片处理模板，生成不同效果的缩略图。

imageView2/<mode>/w/<Width>
                 /h/<Height>
                 /format/<Format>
                 /q/<Quality>
                 /rq/<Quality>
                 /lq/<Quality>

参数	含义
/0/w//h/	限定缩略图的长边最多为，短边最多为，进行等比缩放，不裁剪。若只指定 w 参数则表示限定长边，短边按原图比例自适应调整。若只指定 h 参数则表示限定短边，长边按原图比例自适应调整。当图片长宽相同时，默认长边为图片的高。
/1/w//h/	限定缩略图的宽高最小值。该操作会将图像等比缩放直至某一边达到设定最小值，之后将另一边居中裁剪至设定值。若只指定一边，则表示宽高相等的正方形。例如，原图大小为 1000x500，将参数设定为 `?imageView2/1/w/500/h/400` 后，图像会先等比缩放至 800x400，之后左右各裁剪 150，得到 500x400 大小的图像。
/2/w//h/	限定缩略图的宽高最大值。该操作会将图像等比缩放至宽高都小于设定最大值。例如，原图大小为 1000x500，将参数设定为 `?imageView2/2/w/500/h/400` 后，图像会等比缩放至 500x250。如果只指定一边，则另一边等比自适应。
/3/w//h/	限定缩略图的宽高最小值。该操作会将图像等比缩放至宽高都大于设定最小值。例如，原图大小为 1000x500，将参数设定为 `?imageView2/3/w/500/h/400` 后，图像会等比缩放至 800x400。如果仅指定了一边的值，则另一边将默认设为相同的值。
/4/w//h/	限定缩略图的长边和短边的最小值分别为和，进行等比压缩；如果只指定一边，代表另外一边为同样的值。当图片长宽相同时，默认长边为图片的高。
/5/w//h/	限定缩略图的长边和短边的最大值分别为和，进行等比压缩，居中裁剪；如果只指定一边，则表示宽高相等的正方形；缩放后其中一边多余的部分会被裁剪掉。当图片长宽相同时，默认长边为图片的高。
/format/	目标缩略图的图片格式，可取值为：jpg，gif，png，webp，缺省时为原图格式。
/q/	图片质量，取值范围为 0 - 100，默认值为原图质量；取原图质量和指定质量的最小值；后面加`!`（注意为英文字符），表示强制使用指定值。
/rq/	图片的相对质量，取值范围 0 - 100，数值以原图质量为标准。例如原图质量为 80，将 `rquality` 设置为 80 后，得到处理结果图的图片质量为 64（80x80%）。
/lq/	图片的最低质量，取值范围为 0 - 100，设置结果图的质量参数最小值。例如：原图质量为 85，将 `lquality` 设置为 80 后，处理结果图的图片质量为 85；原图质量为 60，将 `lquality` 设置为 80 后，处理结果图的图片质量会被提升至 80。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定使用快速缩略模版 2 （缩略图的宽高最小值为 500 x 400）的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageView2/2/w/500/h/400

缩放（thumbnail）

imageMogr2/thumbnail/<imageSizeAndOffsetGeometry>

参数	含义
/thumbnail/!p	指定图片的宽高为原图的 %，取值范围为 1 - 1000 的整数，超出则不处理。
/thumbnail/!px	指定图片的宽为原图的 %，高度不变，取值范围为 1 - 1000 的整数，超出则不处理。
/thumbnail/!xp	指定图片的高为原图的 %，宽度不变，取值范围为 1 - 1000 的整数，超出则不处理。
/thumbnail/x	指定目标图片宽度为，高度等比缩放，取值范围为 1 - 10000 的整数，超出则按 10000 进行处理。
/thumbnail/x	指定目标图片高度为，宽度等比缩放，取值范围为 1 - 10000 的整数，超出则按 10000 进行处理。
/thumbnail/x	限定缩略图的宽度和高度的最大值分别为和，进行等比缩放，缩放比例取宽缩放比和高缩放比的较小值，和 Height 的取值范围为 1 - 10000，超出则按 10000 进行处理。说明宽缩放比：目标宽/原图宽；高缩放比：目标高/原图高。
/thumbnail/!xr	限定缩略图的宽度和高度的最小值分别为和，进行等比缩放，缩放比例取宽缩放比和高缩放比的较大值，和的取值范围为 1 - 10000，超出则按 10000 进行处理。说明宽缩放比：目标宽/原图宽；高缩放比：目标高/原图高。
/thumbnail/x>	限定缩略图的宽度和高度的最大值分别为和，进行等比缩小，缩放比例取宽缩放比和高缩放比的较小值，和的取值范围为 1 - 10000，超出则按 10000 进行处理。如果目标宽（高）大于原图宽（高），则不处理。说明宽缩放比：目标宽/原图宽；高缩放比：目标高/原图高。
/thumbnail/x<	限定缩略图的宽度和高度的最大值分别为和，进行等比放大，缩放比例取宽缩放比和高缩放比的较小值，和的取值范围为 1 - 10000，超出则按 10000 进行处理。如果目标宽（高）大于原图宽（高），则不处理。说明宽缩放比：目标宽/原图宽；高缩放比：目标高/原图高。
/thumbnail/x!	忽略原图宽高比例，指定图片宽度为，高度为，强行缩放图片，可能导致目标图片变形，和的取值范围为 1 - 10000，超出则按 10000 进行处理。
/thumbnail/@	等比缩放图片，缩放后的图像，总像素数量不超过 Area。
/pad/	将原图缩放为指定和的矩形内的最大图片，之后使用 `color` 参数指定的颜色居中填充空白部分。取值如下所示： `0`：不使用 pad 模式 `1`：使用 pad 模式
/color/	填充颜色，缺省为白色，需设置为十六进制 RGB 格式（如 #FF0000），详情参考 RGB 编码表，需经过 URL 安全的 Base64 编码，默认值为 #FFFFFF。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定忽略原图宽高比例模式，宽高为 500x400 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/thumbnail/500x400!

格式转换（format）

支持格式转换以及渐进显示。

imageMogr2/format/<Format>

参数	是否必选	含义
/format/	是	将原图转换为指定格式，可填写的值为：png、jpg、heic、webp、awebp、heic、heif、avif、vvic、astc。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定图片格式转换为 avif 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/format/avif

高斯模糊（blur）

为图片增加模糊效果。

imageMogr2/blur/<radius>x<sigma>

参数	含义
	设置模糊半径，取值范围为 1 - 50，数值越大，图片越模糊。
	设置正态分布的标准差，必须大于 0，数值越大，图片越模糊。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定高斯模糊半径为 8，标准差为 5 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/blur/8x5

旋转（rotate）

imageMogr2/rotate/<rotateDegree>
          /flip/<flip>

参数	含义
/rotate/	普通旋转：图片顺时针旋转角度，取值范围为 0 - 360，默认不旋转。
/flip/	镜像翻转，支持取值如下： `vertical`：表示垂直翻转 `horizontal`：表示水平翻转。

参数

含义

/rotate/

普通旋转：图片顺时针旋转角度，取值范围为 0 - 360，默认不旋转。

/flip/

镜像翻转，支持取值如下：

vertical：表示垂直翻转
horizontal：表示水平翻转。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定顺时针旋转 60 度的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/rotate/60

裁剪（cut）

提供图片裁剪的功能，支持以下多种裁剪方式：

自定义裁剪：设置裁剪锚点后（锚点参考九宫格方位图），可基于该锚点自定义设置需要裁剪的宽高；
缩放裁剪：设置指定的宽高后，会先进行等比缩小后再裁剪；
内切圆裁剪：可以将图片裁剪为圆形；
圆角裁剪：可以将图片的四角裁剪为圆弧形；
人脸智能裁剪：可以自动识别图片内的人脸并裁剪出来；
自适应裁剪：按指定的宽高比对图片进行裁剪。

imageMogr2/cut/<width>x<height>x<dx>x<dy>
          /crop/<imageSizeAndOffsetGeometry>
          /iradius/<radius>
          /rradius/<radius>
          /rcrop/<MinRatio>x<MaxRatio>

裁剪方式	参数	含义
自定义裁剪	/cut/	指定目标图片的宽为，取值范围为[0,原图宽度]，默认为原图宽。
	/cut/	指定目标图片的高为，取值范围为[0,原图高度]，默认为原图高。
	/cut/	相对于图片裁剪锚点（默认为左上顶点）水平向右偏移，取值范围为[0,原图宽的边界]，默认为 0。
	/cut/	相对于图片裁剪锚点（默认为左上顶点）水平向下偏移，取值范围为[0,原图宽的边界]，默认为 0。
	/cut/gravity/	图片裁剪的锚点位置，默认为左上顶点 northwest，详情请参见九宫格方位图。
缩放裁剪	/crop/x	先限定图片宽度最小值为 width，高度最小值为 height ，进行等比缩小，然后以宽为 width，高为 height 进行居中裁剪，和的取值范围[0,原图宽高]，默认为原图宽高。如果仅设定了宽度或高度，例如`/crop/<width>x` ，处理结果为不缩放居中裁剪，效果等同于`/cut/<width>/gravity/center`。
缩放裁剪	/crop/gravity/	图片裁剪的锚点位置，默认为中心点 center，详情请参见九宫格方位图。
内切圆裁剪	/iradius/	内切圆裁剪功能，是内切圆的半径，取值范围[1,原图最小边的一半]。内切圆的圆心为图片的中心。图片格式为 gif 时，不支持该参数。处理后图片如果是 PNG、WebP 或 BMP 等支持透明通道的图片，那么图片非圆形区域的部分将会以透明填充。如果是 JPG 图片，不支持透明通道，非圆形区域是以白色进行填充。
圆角裁剪	/rradius/	圆角裁剪功能，为图片圆角边缘的半径，取值范围为大于 0 且小于原图最小边一半的整数。圆角与原图边缘相切。图片格式为 gif 时，不支持该参数。处理后图片如果是 PNG、WebP 或 BMP 等支持透明通道的图片，那么图片非圆形区域的部分将会以透明填充。如果是 JPG 图片，不支持透明通道，非圆形区域是以白色进行填充。
自适应裁剪	/rcrop/x	基于指定的图片宽高比范围进行裁剪。表示最小宽高比，表示最大宽高比，值均为 1-10000 的整数。MinRatio 和 MaxRatio 的计算方式为 100 x 宽/高，值 1 表示宽高比为 1:100，值 100 表示宽高比为 1:1。如果原图宽高比小于最小宽高比，则对图片按照最小宽高比进行宽不变的居中裁剪；如果原图宽高比大于最大宽高比，则对图片按照最大宽高比进行高不变的居中裁剪。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定自定义裁剪，相对于图片左上顶点水平向右平移 100 像素，垂直向下平移 10 像素，指定目标图片大小为 600×600 进行裁剪的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/cut/600x600x100x10
指定缩放裁剪模式，宽高为 600x400 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/crop/600x400
指定内切圆裁剪，半径为 200 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/iradius/200
指定圆角裁剪，半径为 100 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/rradius/100
指定自适应裁剪，宽高比的范围为最小 1:2，最大 1:1 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/rcrop/50x100

渐进显示（interlace）

仅支持 jpeg 的渐进式加载。

imageMogr2/interlace/<Mode>

参数	含义
/interlace/	输出为渐进式 jpg 格式。取值如下所示：。 `0`：不开启渐进式 `1`：开启渐进式该参数仅在输出图片格式为 jpg 格式时有效。如果输出非 jpg 图片格式，会忽略该参数，默认值为 0。

参数

含义

/interlace/

输出为渐进式 jpg 格式。取值如下所示：。

0：不开启渐进式
1：开启渐进式

该参数仅在输出图片格式为 jpg 格式时有效。如果输出非 jpg 图片格式，会忽略该参数，默认值为 0。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定设置为渐进显示的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/interlace/1

亮度（bright）

imageMogr2/bright/<value>

参数	含义
/bright/	图片亮度调节功能，为亮度参数值，取值范围为[-100, 100]的整数。取值＜0：降低图片亮度。取值 = 0：不调整图片亮度。取值＞0：提高图片亮度。

参数

含义

/bright/

图片亮度调节功能，为亮度参数值，取值范围为[-100, 100]的整数。

取值＜0：降低图片亮度。
取值 = 0：不调整图片亮度。
取值＞0：提高图片亮度。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定亮度为 70 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/bright/70

对比度（contrast）

imageMogr2/contrast/<value>

参数	含义
/contrast/	图片对比度调节功能，为对比度参数值，取值范围为[-100, 100]的整数。取值＜0：降低图片对比度。取值 = 0：不调整图片对比度。取值＞0：提高图片对比度。

参数

含义

/contrast/

图片对比度调节功能，为对比度参数值，取值范围为[-100, 100]的整数。

取值＜0：降低图片对比度。
取值 = 0：不调整图片对比度。
取值＞0：提高图片对比度。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定对比度为 -50 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/contrast/-50

锐化（sharpen）

imageMogr2/sharpen/<value>

参数	含义
/sharpen/	图片锐化功能，为锐化参数值，取值范围为 10 - 300 间的整数（推荐使用 70）。参数值越大，锐化效果越明显。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定锐化为 70 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/sharpen/70

灰度图（grayscale）

imageMogr2/grayscale/<value>

参数	含义
/grayscale/	将图片设置为灰度图。取值如下所示： `0`：不改变图片。 `1`：将图片变为灰度图。

参数

含义

/grayscale/

将图片设置为灰度图。取值如下所示：

0：不改变图片。
1：将图片变为灰度图。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定转为灰度图的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/grayscale/1

获取图片 EXIF 信息（exif）

http://域名/文件存储路径?exif

配置	说明
域名	veImageX 图像处理服务中绑定的域名，状态为正常可用，您可在控制台获取。
文件存储路径	和域名同一个服务下存储的文件路径，您可在控制台获取。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
访问示例：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?exif

具体返回参数如下所示

{
   "Artist":{
      "val":"Pedro Salaverria"
   },
   "ColorSpace":{
      "val":"sRGB"
   },
   "Contrast":{
      "val":"Normal"
   },
   "Copyright":{
      "val":"Pedro Salaverria (Photographer) - [None] (Editor)"
   },
   "CustomRendered":{
      "val":"Normal process"
   },
   "DateTime":{
      "val":"2016:04:14 16:24:38"
   },
   "DateTimeDigitized":{
      "val":"2016:04:14 16:24:38"
   },
   "DateTimeOriginal":{
      "val":"2016:04:14 16:24:38"
   },
   "DigitalZoomRatio":{
      "val":" 1"
   },
   "ExifVersion":{
      "val":"Exif Version 2.1"
   },
   "ExposureBiasValue":{
      "val":"0.00 EV"
   },
   "ExposureMode":{
      "val":"Manual exposure"
   },
   "ExposureProgram":{
      "val":"Manual"
   },
   "ExposureTime":{
      "val":"1/500 sec."
   },
   "FNumber":{
      "val":"f/8.0"
   },
   "FileSource":{
      "val":"DSC"
   },
   "Flash":{
      "val":"Flash did not fire, compulsory flash mode"
   },
   ...后续内容已省略...
}

获取图片基本信息（info）

http://域名/文件存储路径?imageInfo

配置	说明
域名	veImageX 图像处理服务中绑定的域名，状态为正常可用，您可在控制台获取。
文件存储路径	和域名同一个服务下存储的文件路径，您可在控制台获取。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
访问示例：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageInfo

具体返回参数如下所示：

{ 
   "size": 63859,  //文件大小，单位为 Byte
   "format": "jpeg", //图片格式
   "width": 1023,  //宽度，单位为 px
   "height": 683,   //高度，单位为 px
   "orientation": "Top-left"  //记录图片拍摄的相机的旋转信息
}

管道操作符（|）

您可通过|分隔多种处理样式，实际处理时会按照先后顺序对图片进行不同处理，当前最多支持 10 层管道。
规则：http://域名/文件存储路径?imageMogr2/<操作1>|imageMogr2/<操作2>

配置	说明
域名	veImageX 图像处理服务中绑定的域名，状态为正常可用，您可在控制台获取。
文件存储路径	和域名同一个服务下存储的文件路径，您可在控制台获取。

示例

原图：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg
指定缩放图片宽高为 50%，且高斯模糊参数中模糊半径为 8，sigma 值为 5 的处理图访问地址：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?imageMogr2/blur/8x5|imageMogr2/thumbnail/!50p

常见问题

对图片拼接多个处理样式没有生效？

T 版支持的管道操作符为 |，使用其他符号（如 ?）连接不同处理样式将无法正常生效，尽管参数解析可能不报错。如果您遇到该问题，可以自行检查请求参数，或者联系技术支持寻求帮助。