图片处理

URL 访问

通过 URL 访问图片时，对图片进行处理，并把处理后的图片返回。

URL 访问的格式

例如：

图片 URL 是 http://fss-my.vhostgo.com/westtest/example/demo.jpg， 间隔标识符是 !， 功能是 格式转换成 webp， 访问的 URL 是 http://fss-my.vhostgo.com/westtest/example/demo.jpg!/format/webp。

间隔标识符

用于分隔图片 URL 和处理信息，有 3 种可选，分别是：!（感叹号/默认值）、-（中划线）和 _（下划线），可在控制中心，在 「对象存储」 > 「bucket详情」 中设置。

缩略图版本

缩略图版本可在控制中心，「对象存储」 > 「bucket详情」 中创建。

例如 缩略图版本名称是 west123， 访问的 URL 是

http://fss-my.vhostgo.com/westtest/example/demo.jpg!west123。 其中，! 是间隔标识符。

原图保护密钥

图片添加保护密钥后，访问时需要带上 「间隔标识符」 和 「保护密钥」，才能访问图片。

例如，保护密钥是 test，访问图片 URL 是 http://fss-my.vhostgo.com/westtest/example/secret.jpg!test。 如果保护密钥跟缩略图版本名称相同，当作保护密钥。特别地，对有保护密钥的图片进行处理时，不需要加保护密钥。

混合使用

假设存在缩略图版本 west123，现在针对某类图片需要调整缩略图版本的配置，比如限定宽度为 500px（/fw/500），可以使用缩略图版本与参数混合，通过参数对缩略图版本进行动态调整。因为，参数的优先级高于缩略图版本。 混合使用是：

上传预处理混合使用是：

上传预处理

在上传图片时，对上传的图片进行处理，并保存处理后的图片到fss。

支持的 API： REST API

参数名是 x-gmkerl-thumb，参数值是 参数或缩略图版本。处理参数见功能版块。

异步处理

举例

例 1：转换图片格式为 png

例 2：限定图片宽度为 300px、锐化、压缩质量 80、存储为 png 格式（参数不区分先后顺序）

缩小&放大

参数 值 说明
/fw/<width> 宽，如 300 限定宽度，高度自适应
/fh/<height> 高，如 200 限定高度，宽度自适应
/max/<max> 最长边，如 200 限定最长边，短边自适应
/min/<min> 最短边，如 200 限定最短边，长边自适应
/fwfh/<w>x<h> 宽x高，如 300×200 限定宽度或高度，宽高不足时不缩放
/fwfh2/<w>x<h> 宽x高，如 300×200 限定宽度最小值和高度最小值，宽高不足时不缩放
/both/<w>x<h> 宽x高，如 300×200 固定宽度和高度，宽高不足时居中裁剪再缩放。特别地，配合 /force/true 使用时，宽高不足时只缩放，不裁剪
/sq/<w> 宽或高，如 300 图片缩放成正方形，宽高相等
/scale/<scale> 缩放比例，如 50 宽高等比例缩放，取值范围 [1-1000]
/wscale/<wscale> 宽度缩放比例，如 200 宽度按比例缩放，高度不变，取值范围 [1-1000]
/hscale/<hscale> 高度缩放比例，如 200 高度按比例缩放，宽度不变，取值范围 [1-1000]
/fxfn/<max>x<min> 长边x短边，如 300×200 限定长边或短边，进行等比缩放，不裁剪
/fxfn2/<max>x<min> 长边x短边，如 300×200 限定长边最小值和短边最小值，进行等比缩放，不裁剪
/fp/<integer> 宽高像素积，如 200000 宽高等比例缩放，直到宽高像素积小于但最接近指定值，取值范围 [1-25000000]
/force/<boolean> true 不支持放大的参数，指定 /force/ 为 true 进行放大，默认 false

注

裁剪

参数 值 说明
/crop/<w>x<h>a<x>a<y> 宽x高axay，如 300x200a80a60 缩小或放大前进行裁剪
/clip/<w>x<h>a<x>a<y> 宽x高axay，如 300x200a80a60 缩小或放大后进行裁剪
/gravity/<gravity> 位置，如 north 裁剪开始的方位，默认 northwest，详见方位说明。特别地，/gravity 需要放在 /crop 或 /clip 的后面
/roundrect/<roundrect> 圆角半径，如 20 裁剪时对四角进行圆化（圆角裁剪），默认 10

注

水印

图片水印

参数 值 说明
/watermark/url/<url> Base64 编码字符串 水印相对路径的 Base64 编码，相对路径包含 /，比如 /path/to/watermark.png。水印需要上传到待处理图片的服务下。详见[注]
/align/<align> 位置，如 north 水印图片放置方位，默认 northwest，详见方位说明
/margin/<x>x<y> 横偏移x纵偏移，如 15×10 水印图片横纵相对偏移，默认 0x0
/opacity/<opacity> 透明度，如 90 水印图片透明度，默认 100，取值范围 [0-100]，值越大越不透明，0 完全透明，100 完全不透明
/percent/<integer> 百分比值，如 50 水印图片自适应原图短边的比例，默认 0，表示不设置该参数，详见[注]
/repeat/<boolean> true 水印图片是否重复铺满原图，默认 false
/animate/<boolean> true 允许对动态图片加水印，默认 false

文字水印

参数 值 说明
/watermark/text/<text> 文字内容，如 5L2g5aW977yB 文字内容的 Base64 编码字符串，示例为 你好！
/size/<size> 大小，如 16 文字大小，单位 px，默认 40
/font/<font> 字体，如 simsun（宋体） 文字字体，默认 simsun。字体使用时，需要用参数名。参数名见字体列表
/color/<color> RRGGBB，如 FF0000（红色） 字体颜色，默认 000000（黑色）
/border/<border> RRGGBBAA，如 FF000000（不透明红色） 文字描边，默认 FFFFFFFF（透明白色），详见 border 说明
/align/<align> 位置，如 north 文字放置方位，默认 northwest，详见方位说明
/margin/<x>x<y> 横偏移x纵偏移，如 15×10 文字横纵相对偏移，默认 0x0
/opacity/<opacity> 透明度，如 90 文字透明度，默认 100，取值范围 [0-100]，值越大越不透明，0 完全透明，100 完全不透明
/animate/<boolean> true 允许对动态图片加水印，默认 false

多个水印

特别地，水印个数越多，处理耗时越长，建议不要超过 3 个。

注

image description

名称 类型 参数名
宋体 中文字体 simsun
黑体 中文字体 simhei
楷体 中文字体 simkai
隶书 中文字体 simli
幼圆 中文字体 simyou
仿宋 中文字体 simfang
简体中文 中文字体 sc
繁体中文 中文字体 tc
Arial 英文字体 arial
Georgia 英文字体 georgia
Helvetica 英文字体 helvetica
Times-New-Roman 英文字体 roman

旋转

参数 值 说明
/rotate/<固定值> auto 自动扶正
/rotate/<angle> (0, 360]，如 90° 按角度旋转

翻转

参数 值 说明
/flip/<orientation> 方向，如 left,right 翻转方向，可选值：left,right、top,down

注

边框

为图片添加边框，支持设置边框颜色。

参数 值 说明
/border/<w>x<h> 宽x高，如 3×2 边框尺寸，w 表示左右边框宽度，h 表示上下边框宽度
/brdcolor/<brdcolor> RRGGBBAA，如 FF000000（红色不透明） 边框颜色和透明度，默认 FFFFFF00（白色不透明）

注

画布

为图片添加画布，相当于把图片放入画布中。

参数 值 说明
/canvas/<w>x<h>a<x>a<y> 宽x高axay，如 600x400a50a20 画布尺寸，w 表示画布宽，h 表示画布高，x、y 表示图片左上角在画布中的坐标，如果 x、y 不存在，则图片在画布中间
/cvscolor/<FFFFFF00> RRGGBBAA，如 FF000000（红色不透明） 边框颜色和透明度，默认 FFFFFF00（白色不透明）
/gravity/<northwest> 方位，如 north 裁剪开始的方位，默认 northwest。特别地，/gravity 需要放在 /canvas 后面

注

灰白图

把图片转换成灰白图，适用于公祭、艺术欣赏等场景，参数如下：

参数 值 说明
/gray/<boolean> true 是否把图片转换成灰白图，默认 false

注

Exif 编辑

以 /exifset/ 开头，后面的参数如下：

参数 值 说明
/copyright/、<Base64 版权信息> string 指定 Exif 中的版权信息，需要 Base64 编码
/artist/、<Base64 作者信息> string 指定 Exif 中的作者信息，需要 Base64 编码

举例

输出设置

参数 值 说明
/format/<图片格式> string 可选值 jpg、png、webp。webp 包含动态 WebP
/lossless/<boolean> true 无损压缩，默认 false。仅当输出格式是 WebP 时有效
/quality/<quality> 整数值，如 75 设置压缩质量，可选范围[1-99]
/compress/<boolean> true JPG 、 PNG 大小压缩优化，默认 false
/coalesce/<boolean> false 是否填充动态 GIF 图像中共同部分，默认 true，见「注」
/progressive/<boolean> true JPG 图片渐进式加载，图片加载从模糊到清晰
/exifswitch/<boolean> true 保留 EXIF 信息 ，默认会删除 EXIF 信息
/noicc/<boolean> true 清除图片 ICC 信息，默认 false
/strip/<boolean> true 去除图片所有元信息，包括 EXIF 、ICC 等。默认 false
/ignore-error/<boolean> true 是否忽略错误返回原图 ，默认 false，返回错误

注

主题色提取

参数 值 说明
/excolor/<integer> 颜色数量，如 128 提取的颜色数量。可选值：[1-4096]
/exformat/<exformat> 颜色进制，如 hex 返回颜色的进制，默认 dec。可选值：dec、hex

注

静态图渐变

参数 值 说明
/gdori/<orientation> 方向，如 top,down（自上而下） 渐变方向
/gdpos/<gdpos> 开始位置,结束位置，如 10,100 渐变从开始位置至结束位置。单位像素（px）
/gdstartcolor/<gdstartcolor> RRGGBBAA，如 FF000000（红色不透明） 开始位置颜色及透明度
/gdstopcolor/<gdstopcolor> RRGGBBAA，如 FF000000（红色不透明） 结束位置颜色及透明度

注