如何通过图片 URL 进行图片云处理？

URL 作图

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

URL 作图的格式

图片 URL + 间隔标识符 + 参数

例如

图片 URL 是 https://p.upyun.com/docs/cloud/demo.jpg，

间隔标识符是 !，

功能是 格式转换成 webp，

访问的 URL 是 https://p.upyun.com/docs/cloud/demo.jpg!/format/webp。

间隔标识符

用于分隔图片 URL 和处理信息，有 3 种可选，分别是：!（感叹号/默认值）、-（中划线）和 _（下划线）。

支持格式

类型	值
输入格式	JPG、JPEG、PNG、WebP、动态 WebP、GIF、动态 GIF、BMP、SVG等
输出格式	JPG、PNG、WebP、动态 WebP

其他约束

图片宽或高最大不能超过 2 万像素，「宽 * 高 * 帧数」最大不能超过 2 亿。

功能

缩小&放大

参数	值	说明
`/fw/<width>`	宽，如 300	限定宽度，高度自适应
`/fh/<height>`	高，如 200	限定高度，宽度自适应
`/max/<max>`	最长边，如 200	限定最长边，短边自适应
`/min/<min>`	最短边，如 200	限定最短边，长边自适应
`/fwfh/<w>x<h>`	宽x高，如 300x200	限定宽度或高度，宽高不足时不缩放
`/fwfh2/<w>x<h>`	宽x高，如 300x200	限定宽度最小值和高度最小值，宽高不足时不缩放
`/both/<w>x<h>`	宽x高，如 300x200	固定宽度和高度，宽高不足时居中裁剪再缩放特别地，配合 `/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短边，如 300x200	限定长边或短边，进行等比缩放，不裁剪
`/fxfn2/<max>x<min>`	长边x短边，如 300x200	限定长边最小值和短边最小值，进行等比缩放，不裁剪
`/fp/<integer>`	宽高像素积，如 200000	宽高等比例缩放，直到宽高像素积小于但最接近指定值，取值范围 `[1-25000000]`
`/force/<boolean>`	true	不支持放大的参数，指定 `/force/` 为 `true` 进行放大，默认 `false`

注

fwfh 当原图宽与期望缩放的宽的比例大于原图高与期望缩放的高的比例时，是 fw；否则，是 fh。
scale 值取 20 时，缩小后的图片宽高是原图宽高的 20%；取 200 时，放大后的图片宽高是原图宽高的 200%。
特别地，大部分参数默认不支持放大，如果需要放大，请指定 /force/true 。
<w>x<h> 中的 x 是小写字母 x，不是乘号。

裁剪

参数	值	说明
`/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`

注

<w>x<h> 中的 x 是小写字母 x，不是乘号。当 <w>x<h> 是 0x0 时，自动根据偏移量计算裁剪图片宽、高。
a<x>s<y> 中的 <x>、<y> 表示偏移量，a、s 表示正、负，x 正负判断依据是：往 east 方向偏移，为 a；往 west 方向偏移，为 s; y 正负判断依据是：往 south 方向偏移，为 a；往 north 方向偏移，为 s。

水印

图片水印

参数	值	说明
`/watermark/url/<url>`	编码字符串，如 `L3BhdGgvdG8vd2F0ZXJtYXJrLnBuZw==`	水印图片的 URI，示例为 `/path/to/watermark.png` 的 Base64 编码字符串。特别地，水印图片必须和待处理图片在同一服务名下
`/align/<align>`	位置，如 north	水印图片放置方位，默认 `northwest`，详见方位说明
`/margin/<x>x<y>`	横偏移x纵偏移，如 15x10	水印图片横纵相对偏移，默认 `20x20`
`/opacity/<opacity>`	透明度，如 90	水印图片透明度，默认 `100`，取值范围 `[0-100]`，值越大越不透明，`0` 完全透明，`100` 完全不透明
`/percent/<integer>`	百分比值，如 50	水印图片自适应原图短边的比例，取值范围 `[0-100]`，默认 `0`，`0` 表示不设置该参数
`/repeat/<boolean>`	true	水印图片是否重复铺满原图，默认 `false`
`/animate/<boolean>`	true	允许对动态图片加水印，默认 `false`

文字水印

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

多个水印

把图片水印或文字水印参数重复。例如，一个文字水印 + 一个图片水印：

/watermark/text/5L2g5aW977yB/font/simhei/watermark/url/L2RvY3MvY2xvdWQvdXB5dW4tbG9nby5wbmc=/align/southeast

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

注

图片水印的 url 需要 base64 编码，并把编码后的字符串中的 /（斜杠）替换成 |（竖线）。
align 或 gravity 的 9 个方位：

    northwest     |     north      |     northeast

    west          |     center     |       east

    southwest     |     south      |     southeast

文字水印的 text 需要 base64 编码，并把编码后的字符串中的 /（斜杠）替换成 |（竖线）。
文字水印的中含中文内容（text）时，字体（font）请使用中文字体，否则会乱码。
字体列表：

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

border 的值 RRGGBBAA，RRGGBB 表示边框颜色；AA 表示不透明度，取值 [0-255]，值越大越透明，00表示完全不透明，FF 表示完全透明。

<x>x<y> 中，连接 <x>与<y>是小写字母 x，不是乘号。

旋转

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

翻转

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

注

left,right 表示从左向右翻转，top,down 表示从上向下翻转。

锐化

提高图片模糊部位的清晰度或聚焦程度。

参数	值	说明
`/unsharp/<boolean>`	true	锐化，默认 `false`

高斯模糊

减少图片噪音和降低图片细节层次，使图片模糊化。

参数	值	说明
`/gaussblur/<radius>x<sigma>`	模糊半径x标准差，如 5x2	高斯模糊

注

0 <= radius <= 50 且 radius 是整数，sigma 是正整数。当 radius = 0 时，raduis 根据 sigma 自动计算产生。
<radius>x<sigma> 中的 x 是小写字母 x，不是乘号。

边框

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

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

注

brdcolor 的值 RRGGBBAA，RRGGBB 表示边框颜色；AA 表示不透明度，取值 [0-255]，值越大越透明，00 表示完全不透明，FF 表示完全透明。
<w>x<h> 中的 x 是小写字母 x，不是乘号。

画布

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

参数	值	说明
`/canvas/<w>x<h>a<x>a<y>`	宽x高axay，如 600x400a50a20	画布尺寸，`w` 表示画布宽，`h` 表示画布高，`x`、`y` 表示图片左上角在画布中的坐标，如果 `x`、`y` 不存在，则图片在画布中间
`/cvscolor/<cvscolor>`	RRGGBBAA，如 FF000000（红色不透明）	边框颜色和透明度，默认 FFFFFF00（白色不透明）

注

cvscolor 的值 RRGGBBAA，RRGGBB 表示边框颜色；AA 表示不透明度，取值 [0-255]，值越大越透明，00 表示完全不透明，FF 表示完全透明。
<w>x<h> 中的 x 是小写字母 x，不是乘号。

属性获取

参数	值	说明
`/info`	无	获取基本信息（包括宽、高、格式、帧数）
`/meta`	无	获取 EXIF 信息 + 基本信息
`/meta/<固定值>`	iptc	获取 IPTC 信息 + 基本信息
`/meta/<固定值>`	all	获取图片所有信息，当前是 EXIF 信息 + IPTC 信息 + 基本信息

注

上传预处理时，响应信息中默认包含图片基本信息（info），获取其他图片信息，见 FORM API 中的 x-gmkerl-type 参数。
/meta/all 获取到的信息会随着平台支持的信息增多而变化，请在使用时注意。

结果输出

参数	值	说明
`/format/<format>`	图片格式，如 jpg	输出格式，可选值 `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 图片渐进式加载，图片加载从模糊到清晰
`/noicc/<boolean>`	true	清除图片 ICC 信息，默认 `false`
`/strip/<boolean>`	true	去除图片所有元信息，包括 EXIF 、ICC 等。默认 `false`
`/gifto/<boolean>`	true	多帧 GIF 图片转为单帧 GIF 图片
`/exifswitch/<boolean>`	true	保留 EXIF 信息，默认会删除 EXIF 信息
`/ignore-error/<boolean>`	true	是否忽略错误返回原图，默认 `false`，返回错误

注

一般来说，quality（质量） 是 75，在这个值压缩大小与图片质量损失得到平衡。
compress 会对 JPG/PNG 进行一次压缩以减少图片体积，同时稍微延长了图片处理时间、降低了图片质量。
noicc 会导致图片质量轻微的下降。
大部分动态 GIF 可以通过省略相邻帧之间共同部分来优化图片体积。如果 coalesce 参数为 false，当对动态 GIF 做缩略或放大时，可能会导致图片质量下降。
ignore-error 只对 405、409、503 状态码有效，并会在响应头中附加 x-gmkerl-err-code 字段标记实际错误码。其他错误状态码无效，返回错误。

主题色提取

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

注

以 JSON 格式返回颜色。hex（十六进制） 表示颜色为 0xRRGGBB，如 0xff00aa；dec（十进制） 表示颜色为 12345678。

静态图渐变

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

注

gdori 取值：top,down（自上而下）、bottom,up（自下而上）、left,right（自左向右）、right,left（自右向左）。
RRGGBBAA：RRGGBB 表示边框颜色；AA 表示不透明度，取值 [0-255]，值越大越透明，00 表示完全不透明，FF 表示完全透明。

更多详细操作请移驾又拍云查看。

上一篇知晓云是否能够区分开发环境和生产环境？

下一篇 SDK 网络请求为什么会带上知晓云的域名？

知晓云-小程序开发快人一步

帮助支持

公告与新闻

知晓云新能力

常见问题

财务

数据表

文件

用户

引擎（触发器与云函数）

统计

模版消息

运营后台

设置

小程序码

短信

支付

团队管理

SDK

社群精灵

实战教程

联系客服