图片处理--veImageX-火山引擎

文档中心

立即注册

导航

图片处理

最近更新时间：2025.03.24 10:24:02首次发布时间：2023.09.01 17:05:27

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

前提条件

在控制台开启自定义处理样式，且指定处理参数为 Q 版。

图片基本处理（imageView）

imageView/<mode>
         /w/<width>
         /h/<height>
         /q/<quality>
         /format/<format>

参数配置	说明	访问示例
`/<mode>`	必填。图像缩放处理模式，取值如下所示： `1`：同时指定宽度和高度，等比裁剪原图正中部分并缩放为x大小的新图片 `2`：同时指定宽度和高度，原图缩小为不超出x大小的缩略图，避免裁剪长边 `2`：仅指定宽度，高度等比缩小 `2`：仅指定高度，宽度等比缩小	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageView/1/w/100/h/200/q/70/format/png
`/w/<width>`	目标图片的宽度，单位为像素（px）
`/h/<height>`	目标图片的高度，单位为像素（px）
`/q/<quality>`	目标图片的图像质量，取值范围为[1,100]，缺省为85
`/format/<format>`	目标图片的输出格式，取值范围：jpg，gif，png，webp等，缺省为原图格式

图像基础处理（imageView2）

图像基础处理能力包含了图片缩放、指定输出格式、渐进式加载和压缩质量参数。

imageView2/<mode>/w/<LongEdge>  
                 /h/<ShortEdge>  
                 /format/<Format>  
                 /interlace/<Interlace>  
                 /q/<Quality>

缩放

参数配置	说明	访问示例
`/0/w/<LongEdge>/h/<ShortEdge>`	限定缩略图的长边最多为，短边最多为，进行等比缩放，不裁剪。如果只指定 w 参数则表示限定长边（短边自适应），只指定 h 参数则表示限定短边（长边自适应）。适用场景：适合移动设备上做缩略图。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageView2/0/w/100/h/200
`/1/w/<Width>/h/<Height>`	限定缩略图的宽最少为，高最少为，进行等比缩放，居中裁剪。转后的缩略图通常恰好是 x 的大小（有一个边缩放的时候会因为超出矩形框而被裁剪掉多余部分）。如果只指定 w 参数或只指定 h 参数，代表限定为长宽相等的正方图。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageView2/1/w/100/h/200
`/2/w/<Width>/h/<Height>`	限定缩略图的宽最多为，高最多为，进行等比缩放，不裁剪。如果只指定 w 参数则表示限定宽（高自适应），只指定 h 参数则表示限定高（宽自适应）。它和模式0类似，区别只是限定宽和高，不是限定长边和短边。适用场景：适合 PC 端上做缩略图。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageView2/2/w/100/h/200
`/3/w/<Width>/h/<Height>`	限定缩略图的宽最少为，高最少为，进行等比缩放，不裁剪。如果只指定 w 参数或只指定 h 参数，代表长宽限定为同样的值。你可以理解为模式 1 是模式 3 的结果再做居中裁剪得到的。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageView2/3/w/100/h/200
`/4/w/<LongEdge>/h/<ShortEdge>`	限定缩略图的长边最少为，短边最少为，进行等比缩放，不裁剪。如果只指定 w 参数或只指定 h 参数，表示长边短边限定为同样的值。适用场景：该模式适合在手持设备做图片的全屏查看（把这里的长边短边分别设为手机屏幕的分辨率即可），生成的图片尺寸刚好充满整个屏幕（某一个边可能会超出屏幕）。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageView2/4/w/100/h/200
`/5/w/<LongEdge>/h/<ShortEdge>`	限定缩略图的长边最少为，短边最少为，进行等比缩放，居中裁剪。如果只指定 w 参数或只指定 h 参数，表示长边短边限定为同样的值。同上模式4，但超出限定的矩形部分会被裁剪。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageView2/5/w/100/h/200

格式转换

参数配置	说明	访问示例
`/format/<Format>`	新图的指定输出格式，取值范围：jpg，gif，png，webp、heic、avif等，默认为原图格式。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageView2/1/w/100/h/200/format/webp

压缩质量参数

参数配置	说明	访问示例
`/q/<Quality>`	指定图片的质量，仅针对有损压缩时有效。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageView2/1/w/100/h/200/q/80

图像高级处理（imageMogr2）

图像高级处理能力包含了缩放、裁剪、渐进式加载、旋转、高斯模糊功能。

imageMogr2/thumbnail/!<Scale>p   
          /thumbnail/!<Scale>px
          /thumbnail/!x<Scale>p
          /thumbnail/<Width>x
          /thumbnail/x<Height>
          /thumbnail/<Width>x<Height>
          /thumbnail/!<Width>x<Height>r
          /thumbnail/<Width>x<Height>!
          /thumbnail/<Width>x<Height>>
          /thumbnail/<Width>x<Height><
          /thumbnail/<Area>@
 imageMogr2/corp/crop/<Width>x        
            /crop/x<Height>
            /crop/<Width>x<Height>
            /crop/!{cropsize}a<dx>a<dy>
            /crop/!{cropsize}-<dx>a<dy>
            /crop/!{cropsize}a<dx>-<dy>
            /crop/!{cropsize}-<dx>-<dy>
imageMogr2/gravity/<Gravity>
imageMogr2/format/<Format>        
imageMogr2/interlace/<Interlace>       
imageMogr2/quality/<Quality>         
imageMogr2/rotate/<rotate>              
imageMogr2/blur/<blur>

缩放

参数配置	说明	访问示例
`/thumbnail/!<Scale>p`	基于原图的长宽，按指定百分比缩放。`Scale` 的取值范围为 [1,999]。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/!300p
`/thumbnail/!<Scale>px`	以百分比形式指定目标图片宽度，高度不变。`Scale` 的取值范围为 [1,999]。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/!300px
`/thumbnail/!x<Scale>p`	以百分比形式指定目标图片高度，宽度不变。`Scale` 的取值范围为 [1,999]。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/!x300p
`/thumbnail/<Width>x`	指定目标图片宽度，高度等比缩放，`Width` 取值范围为 [1,9999]。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/300x
`/thumbnail/x<Height>`	指定目标图片高度，宽度等比缩放，`Height` 取值范围为 [1,9999]。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/x300
`/thumbnail/<Width>x<Height>`	等比缩放，比例值为宽缩放比和高缩放比的较小值，`Width` 和 `Height` 取值范围为 [1,9999]。宽缩放比：目标宽/原图宽高缩放比：目标高/原图高	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/200x300
`/thumbnail/!<Width>x<Height>r`	等比缩放，比例值为宽缩放比和高缩放比的较大值，`Width` 和 `Height` 取值范围为 [1,9999]。宽缩放比：目标宽/原图宽高缩放比：目标高/原图高	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/!200x300r
`/thumbnail/<Width>x<Height>!`	按指定宽高值强行缩略，可能导致目标图片变形，`Width` 和 `Height` 取值范围为 [1,9999]。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/200x300!
`/thumbnail/<Width>x<Height>>`	等比缩小，比例值为宽缩放比和高缩放比的较小值。如果目标宽和高都大于原图宽和高，则不变，`Width` 和 `Height` 取值范围为 [1,9999]。宽缩放比：目标宽/原图宽高缩放比：目标高/原图高	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/400x300>
`/thumbnail/<Width>x<Height><`	等比放大，比例值为宽缩放比和高缩放比的较小值。如果目标宽(高)小于原图宽(高)，则不变，`Width` 和 `Height` 取值范围为 [1,9999]。宽缩放比：目标宽/原图宽高缩放比：目标高/原图高	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/200x300<
`/thumbnail/<Area>@`	按原图高宽比例等比缩放，缩放后的像素数量不超过指定值，`Area` 取值范围[1,24999999]。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/thumbnail/10000@

裁剪

参数配置	说明	访问示例
`/crop/<Width>x`	指定目标图片宽度，高度不变。取值范围为[0,10000]。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/corp/100x
`/crop/x<Height>`	指定目标图片高度，宽度不变。取值范围为[0,10000]。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/corp/x100
`/crop/<Width>x<Height>`	同时指定目标图片宽高。取值范围为[0,10000]。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/corp/100x300
`/crop/!{cropsize}a<dx>a<dy>`	相对于偏移锚点，向右偏移 dx 个像素，同时向下偏移 dy 个像素。取值范围不限，小于原图宽高即可。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/crop/!300x300a30a100
`/crop/!{cropsize}-<dx>a<dy>`	相对于偏移锚点，从指定宽度中减去 dx 个像素，同时向下偏移 dy 个像素。取值范围不限，小于原图宽高即可。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/crop/!300x300-30a100
`/crop/!{cropsize}a<dx>-<dy>`	相对于偏移锚点，向右偏移 dx 个像素，同时从指定高度中减去 dy 个像素。取值范围不限，小于原图宽高即可。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/crop/!300x300a30-100
`/crop/!{cropsize}-<dx>-<dy>`	相对于偏移锚点，从指定宽度中减去 dx 个像素，同时从指定高度中减去 dy 个像素。取值范围不限，小于原图宽高即可。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/crop/!300x300-30-100

格式转换

参数配置	说明	访问示例
`/format/<Format>`	新图的输出格式取值范围：jpg，gif，png，webp、heic、avif、awebp等，默认为原图格式,注意高效压缩格式单独收费。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/fomat/webp

渐进式加载

参数配置	说明	访问示例
`/interlace/<Interlace>`	jpg 是否支持渐进显示，仅适用于 jpg 格式，弱网下展示效果模糊到清晰展示，现代网络下几乎无影响。取值如下所示： `1` ：支持渐进显示 `0`：（默认）不支持渐进显示	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/interlace/1

参数配置

说明

访问示例

/interlace/<Interlace>

jpg 是否支持渐进显示，仅适用于 jpg 格式，弱网下展示效果模糊到清晰展示，现代网络下几乎无影响。取值如下所示：

1 ：支持渐进显示
0：（默认）不支持渐进显示

https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/interlace/1

旋转

参数配置	说明	访问示例
`/rotate/<rotate>`	普通旋转：图片顺时针旋转角度，取值范围为[1,360]，默认为不旋转。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/rotate/30

高斯模糊

参数配置	说明	访问示例
`/blur/<blur>`	高斯模糊参数。`<blur>`为`<radius>x<sigma>`。其中 `radius` 是模糊半径，取值范围为[1,50]。`sigma` 是正态分布的标准差，必须大于 0。图片格式为 gif 时，不支持该参数。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageMogr2/blur/20x50

图文水印（watermark）

图片水印：
watermark/1
         /image/<encodedImageURL>
         /dissolve/<dissolve>
         /gravity/<gravity>
         /dx/<distanceX>
         /dy/<distanceY>
         /ws/<watermarkScale>
         /wst/<watermarkScaleType>
文字水印：
watermark/2
         /text/<encodedText>
         /font/<encodedFontName> 
         /fontsize/<fontSize>
         /fontstyle/<fontStyle>
         /fill/<encodedTextColor>
         /dissolve/<dissolve>
         /gravity/<gravity>
         /dx/<distanceX>
         /dy/<distanceY>

图片水印

参数配置	说明	访问示例
`/image/<encodedImageURL>` `/dissolve/<dissolve>`	水印的源路径，按照格式需要将图片水印的 url 均需要经过base64 编码。说明更换图片水印时，建议更换图片的文件名。透明度，取值范围[1,100]，默认值为 100（完全不透明）。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?watermark/1/image/aHR0cDovL2ltYWdleGRlbW8udm9sY2ltYWdleHRlc3QuY29tLzEuanBlZw==/dissolve/50/gravity/SouthEast/dx/20/dy/20/ws/0.2
`/gravity/<gravity>`	水印位置，支持以下取值： `NorthWest`：左上 `North`：中上 `NorthEast`：右上 `West`：左中 `Center`：居中 `East`：右中 `SouthWest`：左下 `South`：中下 `SouthEast`：（默认）右下
`/dx/<distanceX>`	横轴边距，单位为像素(px)，默认值为10。
`/dy/<distanceY>`	纵轴边距，单位为像素(px)，默认值为10。
`/ws/<watermarkScale>`	水印图片自适应原图的比例，`ws`的取值范围为[0,1]。具体是指水印图片保持原比例，比如默认是按照短边，则水印图片短边=原图短边＊ws。
`/wst/<watermarkScaleType>`	水印图片自适应原图的类型，取值如下所示： `0`：（默认）自适应原图的短边 `1`：自适应原图的长边 `2`：自适应原图的宽 `3`：自适应原图的高

文字水印

参数配置	说明	访问示例
`/text/<encodedText>`	水印文字内容（经过URL安全的Base64编码）	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?watermark/2/text/dmVJbWFnZVg=/fontsize/800/fill/I0ZGMDAwMA==/font/U291cmNlIEhhbiBTZXJpZiBTQw==/fontstyle/aGVhdnk=
`/font/<encodedFontName>`	水印文字字体（经过URL安全的Base64编码），取值如下所示： Source Han Sans SC：（默认）思源黑体，编码后值为`U291cmNlIEhhbiBTYW5zIFND` Source Han Serif SC：思源宋体，编码后值为`U291cmNlIEhhbiBTZXJpZiBTQw==`
`/fontstyle/<fontStyle>`	水印字体样式（经过URL安全的Base64编码），默认为系统自动选择字体样式。思源黑体支持字体样式：normal、heavy、extralight、regular、bold、light、medium 思源宋体支持字体样式：semibold、bold、extralight、regular、light、medium、heavy
`/fontsize/<fontSize>`	水印文字大小，单位: 缇，等于1/20磅，默认值是240缇。
`/fill/<encodedTextColor`>	水印文字颜色，RGB格式，可以是颜色名称（例如 red）或十六进制（例如 #FF0000），参考RGB颜色编码表，默认为黑色。经过 URL 安全的 Base64 编码。
`/dissolve/<dissolve>`	透明度，取值范围为[1,100]，默认值为100（完全不透明）。
`/gravity/<gravity>`	水印位置，参考水印位置参数表，默认值为`SouthEast`，同图片水印位置
`/dx/<distanceX>`	横轴边距，单位为像素(px)，默认值为10。
`/dy/<distanceY>`	纵轴边距，单位为像素(px)，默认值为10。

图文水印指定位置示意图

图片圆角（roundPic）

roundPic/radius/<radius>
        /radiusx/<radiusx>
        /radiusy/<radiusy>

参数配置	说明	访问示例
`/radius/<radius>`	指定圆角半径大小，水平和垂直的值相同，可以使用像素数（如200）或百分比（如!25p）。不能与`radiusx`和`radiusy`同时使用。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?roundPic/radius/400 https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?roundPic/radius/!45p
`/radiusx/<radiusx>`	指定圆角水平半径大小，可以使用像素数（如200）或百分比（如!25p）。需要与`radiusy`同时使用。	https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?roundPic/radiusx/300/radiusy/200 https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?roundPic/radiusx/!30p/radiusy/!20p
`/radiusy/<radiusy>`	指定圆角垂直半径大小，可以使用像素数（如200）或百分比（如!25p）。需要与`radiusx`同时使用。

imageInfo

查询图片基本信息，包含图片格式、图片大小和色彩模型等。暂不支持获取处理后配置信息。您可通过在源文件访问地址后添加?imageInfo获取具体参数。
访问示例：https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?imageInfo
具体返回参数如下所示：

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

exif

查询数码相机的照片设定的可交换图像文件格式。您可通过在源文件访问地址后添加?exif获取具体参数。

缩略图等经过云处理的新图片不支持 EXIF。
原图格式为avif、heif不支持 EXIF。
原图只支持 20MB 以内的图片。

访问示例：https://imagexdemo.volcimagextest.com/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"
   },
   ...后续内容已省略...
}

管道操作符（|）

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

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

示例

原图：https://imagexdemo.volcimagextest.com/imagexdemo.jpeg
指定图片圆角半径大小为 300，顺时针旋转角度为 30，处理图访问地址：https://imagexdemo.volcimagextest.com/imagexdemo.jpeg?roundPic/radius/300|imageMogr2/rotate/30