You need to enable JavaScript to run this app.
导航
veImageX
  • 文档首页
    • /veImageX/开发指南/数据处理（proscessing）/基础图像处理（历史版本）/用法说明/A 版用法说明
A 版用法说明
最近更新时间：2024.08.05 17:36:32首次发布时间：2023.09.01 17:05:27
我的收藏

veImageX 当前支持您通过自定义访问 URL 的方式使用 A 版图片处理能力。您可以在源地址 URL 后拼接不同处理能力以及对应取值，以实现不同的图片处理效果。

前提条件

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

拼写规则

  • 您可以通过替换 action、param 和 value 实现处理效果，以及叠加不同 action，查看最终图片效果。

  • x-oss-process=image/或x-tos-process=image/两种标识的最终处理效果相同。

传参方式

根据 action 的类型和取值数量，具体有以下 2 种参数传值方式：

类型说明示例

1

当一个 action 仅需传入一个参数时，传参格式可简写为action,value

  • 示例一：指定图片输出格式为 jpeg，即format,jpeg
  • 示例二：指定图片绝对质量参数为 100，即quality,100
2其它情况，action 后边均需要写上对应的 param 和 value示例：等比缩放，指定目标缩放图的宽度为 100px，即resize,w_100

功能说明

压缩质量参数（quality）

功能（action）参数（param）传参格式配置说明

quality

Q

quality,Q_xx

自定义绝对质量参数值。表示将原图质量压缩至 Q%，如果原图质量小于指定参数值，则按照原图质量重新进行压缩。取值范围为 [1,100]。
例如：若原图质量为 100，指定quality,Q_90时，返回最终图片质量约为 90。

说明

该参数只能对保存格式为 JPG 的图片使用，对其他格式的图片无效果。

q

quality,q_xx

自定义相对质量参数值。表示对原图按百分比进行质量压缩。取值范围为 [1,100]。
例如：若原图质量为 80，指定quality,q_90时，返回最终图片质量约为 72。

说明

只有 JPG 格式的原图添加该参数，才可以决定图片的相对质量。如果原图为 WebP 格式，添加该参数相当于指定了原图绝对质量，即与参数 Q 的作用相同。

示例

格式转换（format）

功能（action）参数（param）传参格式配置说明
format-format,xxx处理后图片的格式，不指定或取值 image 表示返回原图格式。支持取值有：png、jpeg、heic、 heif、webp、awebp、avif、avis

示例

缩放（resize）

功能（action）参数（param）传参格式是否必填配置说明

resize

m

resize,m_xx

是

指定缩放模式，取值如下所示：

  • lfit：（默认）等比缩放，缩放图限制为指定 w 与 h 的矩形内的最大图片。
  • mfit：等比缩放，缩放图为延伸出指定 w 与 h 的矩形框外的最小图片。
  • fill：将原图等比缩放为延伸出指定 w 与 h 的矩形框外的最小图片，然后将超出的部分进行居中裁剪。
  • pad：将原图缩放为指定 w 与 h 的矩形内的最大图片，然后使用指定颜色居中填充空白部分。
  • fixed：固定宽高，强制缩放。
wresize,w_xx是指定缩放结果图的宽度，取值范围为 [1,16384]，单位为 px。
hresize,h_xx是指定缩放结果图的高度，取值范围为 [1,16384]，单位为 px。

l

resize,l_xx

是

指定缩放结果图的最长边，取值范围为 [1,16384]，单位为 px。
长边是指原尺寸与目标尺寸的比值大的边。例如，原图为 400px * 200px，缩放为 800px * 100px。由于（400/800）<（200/100），因此在该缩放操作中，200为长边。

s

resize,s_xx

是

指定缩放结果图的最短边，取值范围为 [1,16384]，单位为 px。
短边是指原尺寸与目标尺寸的比值小的边。
例如，原图为 400px * 200px，缩放为800 px * 100 px。由于（400/800）<（200/100），因此在该缩放操作中，400为短边。

limit

resize,limit_xx

否

当结果图分辨率大于原图分辨率时，是否进行缩放。取值如下所示：

  • 1：（默认）返回按照原图分辨率转换的图片（可能和原图的体积不一样）。
  • 0：按指定参数进行缩放。

color

resize,color_xx

是（仅当m为pad时）

当缩放模式选择为 pad（缩放填充）时，可以设置填充的颜色。
RGB 颜色值，例如：000000 表示黑色，FFFFFF 表示白色。默认值为 FFFFFF（白色）。

示例

普通裁剪（crop）

功能（action）参数（param）传参格式配置说明

crop

g

crop,g_xx

设置裁剪的原点位置。原点按照九宫格的形式分布，取值如下所示：

  • nw：左上
  • north：中上
  • ne：右上
  • west：左中
  • center：中部
  • east：右中
  • sw：左下
  • south：中下
  • se：右下
wcrop,w_xx裁剪后图片的宽，单位为 px。取值范围为[0,图片高度]。
hcrop,h_xx裁剪后图片的高，单位为 px。取值范围为[0,图片高度]。
xcrop,x_xx指定裁剪起点横坐标（默认左上角为原点），取值范围为[0,图片边界]。
ycrop,y_xx指定裁剪起点纵坐标（默认左上角为原点），取值范围为[0,图片边界]。

定向裁剪原点示意图

示例

水印（watermark）

说明

当前仅支持添加图片水印。

功能（action）参数（param）是否必填传参格式配置说明
watermarkimage是watermark,image_xx经 Base64 编码处理后的图片水印名称字符串。

P

否

watermark,p_xx

指定图片水印按照要添加水印的原图的比例进行缩放，取值为缩放的百分比。取值范围为[1,100]。
例如设置参数值为10，如果原图为100×100， 则图片水印大小为10×10。当原图变成了200×200，则图片水印大小为20×20。

说明

示例：水印图为 example.png 且缩放百分比为 30。则 image 为imagexdemo.jpeg?x-tos-process=image/resize,P_30编码后的值，即aW1hZ2V4ZGVtby5qcGVnP3gtb3NzLXByb2Nlc3M9aW1hZ2UvcmVzaXplLFBfMzA=

t否watermark,t_xx指定图片水印的透明度。取值范围为[0,100]，默认值为 100。

g

否

watermark,g_xx

指定水印在图片中的位置。取值如下所示：

  • nw：左上
  • north：中上
  • ne：右上
  • west：左中
  • center：中部
  • east：右中
  • sw：左下
  • south：中下
  • se（默认值）：右下
x否watermark,x_xx指定水印的水平边距， 即距离图片边缘的水平距离。这个参数只有当水印位置是左上、左中、左下、右上、右中、右下才有意义。取值范围为[0,4096]，默认值为 10，单位为 px。
y否watermark,y_xx指定水印的垂直边距，即距离图片边缘的垂直距离， 这个参数只有当水印位置是左上、中上、右上、左下、中下、右下才有意义。取值范围为[0,4096]，默认值为 10，单位为 px。
voffset否watermark,voffset_xx指定水印的中线垂直偏移。当水印位置在左中、中部、右中时，可以指定水印位置根据中线往上或者往下偏移。取值范围为[-1000,1000]，默认值为 0，单位为 px。

图文水印指定位置示意图

说明

设定完水印在 9 宫格中的位置后， 进一步微调位置，只能使用边距系数或者绝对值（像素）中的一种。如果两种都写在URL参数中，用绝对值（像素）来调整边距将生效。

示例

模糊 （blur）

为图片增加模糊效果。

功能（action）参数（param）是否必填传参格式配置说明
blurr是blur,r_xx设置模糊半径。取值范围为[1,50]。取值越大，图片越模糊。
s是blur,s_xx设置正态分布的标准差。取值范围为[1,50]。取值越大，图片越模糊。

示例

锐化（sharpen）

提高图片清晰度。

功能（action）参数（param）传参格式配置说明
sharpen-sharpen,xx设置锐化强度，取值范围是[50,399]。值越大，图片轮廓边缘越清晰，但效果可能会失真。

示例

亮度（bright）

支持调整图片亮度。

功能（action）参数（param）传参格式配置说明

bright

-

bright,xx

设置图片亮度，取值范围为[-100,100]。

  • 取值＜0：降低图片亮度。
  • 取值=0：不调整图片亮度。
  • 取值＞0：提高图片亮度。
    100变成纯白，-100变成纯黑。

示例

对比度（contrast）

支持设置图像灰度反差的大小。

功能（action）参数（param）传参格式配置说明

contrast

-

contrast,xx

设置图片对比度，取值范围为[-100,100]。

  • 取值＜0：降低图片对比度。
  • 取值=0：维持原图对比度。
  • 取值＞0：提高图片对比度。

说明

值越大，图片黑白的区分越明显；反之越不明显。

示例

旋转（rotate）

支持通过旋转参数，将原图按指定方向旋转。

功能（action）参数（param）传参格式配置说明
rotate-rotate,xx设置图片顺时针旋转角度，取值范围为[0,360]。

示例

内切圆（circle）

支持通过内切圆参数，将图片处理成内切圆。

功能（action）参数（param）传参格式配置说明
radiusrradius,r_xx以图片中心为圆心裁剪内切圆，取值范围为[1,4096]。

示例

圆角矩形（rounded-corners）

支持将矩形图片的 4 个角切成圆角。

功能（action）参数（param）传参格式配置说明
rounded-cornersrrounded-corners,r_xx将图片切出圆角，指定圆角的半径。取值范围为[1,4096]。

示例

索引切割（indexcrop）

支持将存储的原图按指定大小分割，并截取需要的图片。

功能（action）参数（param）传参格式配置说明
indexcropxindexcrop,x_xx指定在x轴切割出的每块区域的长度。x参数与y参数只能任选其一。取值范围为[1,图片宽度]。
yindexcrop,y_xx指定在y轴切割出的每块区域的长度。x参数与y参数只能任选其一。取值范围为[1,图片宽度]。
iindexcrop,i_xx选择切割后返回的图片区域。取值范围为 [0,区域数），默认值为 0，表示第一块。如果要返回最后一块，您需要根据图片本身的大小结合切割参数的取值范围划定。

示例

渐进显示（interlace）

支持当网络环境较差或图片较大时，图片在网页上渐进显示。

功能（action）参数（param）传参格式配置说明

interlace

-

indexcrop,xx

指定是否设置图片为渐进显示。取值如下所示：

  • 1：渐进显示。表示图片会按照从上到下的顺序一行一行地加载显示。
  • 0：标准显示。表示先显示整个图片的模糊轮廓，然后逐渐加载直至显示完整的图片。

注意

仅针对输出格式为 jpeg 时，该配置生效。

示例

获取图片主色调（average-hue）

支持获取图片主色调，返回值为 RGB 值。

访问示例：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?x-tos-process=image/average-hue

获取信息（info）

支持获取部分图片可能包含可交换图像文件 EXIF 信息。

访问示例：https://imagexdemo.volcimagextest.com/tos-cn-i-i4o5y3y840/imagexdemo.jpeg?x-tos-process=image/info