图片处理

快速入门¶

又拍云处理（图片处理）基于 CDN 或云存储服务，您在使用它之前，请确保您已经注册又拍云账号并完成实名验证，请确保您已经创建 CDN 服务或云存储服务。

收费方面，图片处理完全免费。

相关阅读：演示 WebP 如何让您的图片大小平均减少 70%，WebP 开发专题。

开发者指南¶

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 种可选，分别是：!（感叹号/默认值）、-（中划线）和 _（下划线），可登录又拍云控制台，在 「服务」 > 「功能配置」 > 「云处理」 中设置。

缩略图版本¶

缩略图版本在又拍云控制台，「服务」 > 「功能配置」 > 「云处理」 中创建，它里面包含许多图片处理功能。如下图：

例如

缩略图版本名称是 upyun520，

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

其中，! 是间隔标识符。

上传预处理（同步）¶

在上传图片时，对上传的图片进行处理，并保存处理后的图片到又拍云存储。

支持的 API： REST API | FORM API | 文件拉取。

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

举例

例 1：转换图片格式为 png

x-gmkerl-thumb: /format/png

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

x-gmkerl-thumb: /fw/300/unsharp/true/quality/80/format/png

上传预处理（异步）¶

在上传图片时，对上传的图片进行处理，生成一张或多张新的图片，同时保存上传的图片到又拍云存储。任务以异步的方式处理，处理完成后，回调通知用户处理结果。

支持的 API： FORM API。

参数名是 apps，参数值是 JSON 数组。一个 apps 最多允许包含 10 个图片处理任务。

设置了 apps 参数，会创建异步处理任务，否则为同步处理任务

apps 参数结构

save_as 支持的变量

注

• x-gmkerl-split 会在 x-gmkerl-thumb 的基础上把图片分成数块，用户可以根据回调信息中的行号跟列号来确定分块后的图片在原图中的位置。
• x-gmkerl-split 会输出多个图片，从左上角开始，往右列号从 0 依次增大，往下行号从 0 依次增大，序列号按行从左往右、从上到下、从 0 依次增大。

举例

apps = [
    {                                             
        "name": "thumb",
        "x-gmkerl-thumb": "/fw/300/quality/95",    
        "save_as": "/path/to/fw_300.jpg",          
        "notify_url": "http://your/notify/url"     
    },
    ......
]

回调通知

任务处理完成后，向 notify_url 地址发送回调通知。回调信息为 JSON 格式，字段名及含义如下：

imginfo 、 imginfos 中包含信息如下：

举例

例 1：输出单张图片的回调信息

{
    "task_id": "b52c96bea30646abf8170f333bbd42b9",
    "service": "upyun-demo",
    "status_code": 200,
    "imginfo": {
        "path": "/images/upyun.jpg",
        "type": "jpg",
        "width": 720,
        "height": 360,
        "frames": 1
    }
}

例 2：输出多张图片（使用了图片分块 x-gmkerl-split） 的回调信息

{
    "task_id": "b52c96bea30646abf8170f333bbd42b9",
    "service": "upyun-demo",
    "status_code": 200,
    "imginfos": [
      {
        "path": "/images/upyun.jpg-1.jpg",
        "type": "jpg",
        "width": 72,
        "height": 36,
        "frames": 1,
        "row": 0,
        "column": 0
      },
      {
        "path": "/images/upyun.jpg-2.jpg",
        "type": "jpg",
        "width": 72,
        "height": 36,
        "frames": 1,
        "row": 0,
        "column": 1
      }
    ]
}

原图保护密钥¶

• 上传图片时，保护密钥通过 REST API | FORM API 的 Content-Secret 设置。
• 已经存在存储的图片，可以通过编辑 Metadata 设置保护密钥。

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

例如，保护密钥是 abc，

访问图片 URL 是 https://p.upyun.com/docs/cloud/secret.jpg!abc。

如果保护密钥跟缩略图版本名称相同，当作保护密钥。特别地，对有保护密钥的图片进行处理时，不需要加保护密钥。

混合使用¶

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

URL 作图混合使用是：

https://p.upyun.com/docs/cloud/demo.jpg!upyun520/fw/500

上传预处理混合使用是：

x-gmkerl-thumb: upyun520/fw/500

特别地，参数只能出现在缩略图版本的后面，如 /fw/500 出现在 upyun520 后面。

状态码表¶

上传预处理的更多错误码，请查询 API 错误码表。

支持格式¶

其他约束

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

WebP 开发专题¶

有损 WebP 演示 ：WebP 如何让您的图片大小平均减少 70%

无损 WebP 指南 ：无损 WebP 正确的使用姿势

转成有损 WebP ：/format/webp

转成无损 WebP ：/format/webp/lossless/true

示例

JPG 转成有损 WebP：www.domain.com/a.jpg!/format/webp

PNG 转成无损 WebP：www.domain.com/a.png!/format/webp/lossless/true

GIF/动态 GIF 转成有损 WebP：www.domain.com/a.gif!/format/webp

SVG 转成无损 WebP：www.domain.com/a.svg!/format/webp/lossless/true

! 是间隔标识符，/format/webp、/lossless/true 更多解释见「功能」> 结果输出。

功能¶

缩小&放大¶

注

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

裁剪¶

注

• <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/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）请使用中文字体，否则会乱码。
• 字体列表：

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

旋转¶

翻转

注

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

锐化¶

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

高斯模糊¶

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

注

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

边框¶

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

注

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

画布¶

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

注

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

属性获取¶

注

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

结果输出¶

注

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

主题色提取¶

注

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

静态图渐变¶

注

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

如有疑问请 联系我们