图片处理V2.0
概述
图片处理服务依托对象存储BOS系统对外提供灵活、多样、实时的图片处理服务。用户将原始图片上传到BOS上，通过调用简单的RESTful接口，实现对图片的实时处理，如缩略、裁剪、格式转换、旋转、加文字/图片水印等，处理结果图会通过CDN实时的返回给用户。
在访问速度上，图片处理服务集成了CDN功能，利用遍布在全国的高质量CDN节点，实现图片内容的加速分发，有效降低源站压力。
图片处理服务的架构如下图所示：
-
用户首次发送请求处理流程：
- 用户端首次发送图片处理请求;
- 首次请求，CDN未命中，请求会被直接发送到BOS源站进行处理；
- 根据用户发送的处理参数对图片进行实时处理；
- 处理后的结果图将被缓存到CDN节点上；
- 同时，将结果图返回给用户端。
-
用户端非首次访问图片处理流程：
- 用户端发送图片处理请求;
- 若CDN命中，则直接跳到步骤5；若CDN未命中，则跳到步骤3；
- 请求会被回源到BOS，并根据用户发送的处理参数对图片进行实时处理；
- 处理后的结果图被缓存到CDN节点上；
- 将结果图返回给用户端。
图片处理服务的灵活便捷体现在，您只要通过在原始图片的请求中直接添加处理参数，即可实时得到处理后的结果图。
计费方式
图片服务收费分为三个部分：
- CDN流量 在CDN上会产生请求流量，这些流量将会记录到CDN计费中，请参考CDN产品定价。
- BOS存储空间、请求次数、外网流出流量和CDN回源请求产生的流出流量 存储空间、请求次数、外网流出流量和CDN回源请求产生的流出流量按BOS标准计费。其中，CDN回源请求的图片流出流量，为处理后目标图的流出流量。请参考BOS产品定价。
- 图片处理数据量 BOS 图像处理包括图像基础处理费用和图像高级处理费用。图像基础处理费用是指对存储在 BOS 中的图像进行缩放、旋转、水印、格式变换、裁剪等操作时产生的费用，图像高级处理费用是指对存储在 BOS 中的图像进行 HEIC 压缩，WebP-M6 压缩等高阶操作。图像基础处理、图像高级处理中 HEIC 图像压缩及 WebP-M6 图像压缩服务于 2020 年 6 月 1 日开始正式计费。您可以登录控制台-财务查看用量数据。
使用方式
说明： 本文档介绍的是BOS图片处理V2.0版本，您仍然可以通过BOS图片处理V1.0版本方式来访问BOS图片处理服务，但今后V1.0版本功能将不再更新。
您需要先将原始图片上传到BOS，每个BOS Bucket默认开通图片处理的功能，无需开通，也无需使用特定域名访问。当访问图片URL时，在Querystring中通过x-bce-process参数指定图片处理命令，即可触发BOS图片处理功能。BOS支持通过命令和样式两种方式访问图片服务。
- 命令方式访问格式：
http://${domain}/${objectkey}?x-bce-process=image/${action},${key}_${value}. 样例：http://bucket-A.bj.bcebos.com/sample.jpg?x-bce-process=image/resize,m_fill,w_200,h_300。 -
样式方式访问格式：
http://${domain}/${objectkey}?x-bce-process=style/${stylename}. 样例：http://bucket-A.bj.bcebos.com/sample.jpg?x-bce-process=style/stylename。为了提升图片的安全性，尤其是在BOS中进行了处理并公开发布的图片，BOS也支持对指定Bucket内的图片开启原图保护。即开启原图保护后，如果图片获取者未验证被授权的签名，则只能通过样式方式访问处理后的图片，直接访问原图或通过处理参数访问的方式会被拒绝。目前支持在控制台对原图保护功能进行开启或关闭，也支持通过API进行相关操作，并可通过resource字段指定该功能生效范围。
规则与限制
- 支持的原图格式：jpg、png、bmp、webp、heic、gif。
- 支持的目标格式：jpg、png、bmp、webp、heic、gif。
- 支持图片大小不超过20MB，且图片宽高不超过10000px。
- 处理结果输出图片宽高不超过4096px，包括管道和子命令间的中间输出图片。
- 最多可以同时指定4组操作，即4个action。
- 一个action下不可以重复指定同一个参数。
图片处理命令
整体的图片处理命令形式为：x-bce-process=image/${action},${key}_${value},${key}_${value}/${action},${key}_${value}，说明如下：
- image：BOS支持多种数据处理形式，均使用x-bce-process参数触发，当使用图片处理时，需要指定此处名字为image。
- action：BOS支持多种图片处理命令，每种图片处理命令称作一种action，比如缩放resize，裁剪crop等。
- key：每种action支持多种具体的处理参数，比如缩放宽度w,高度h等。
- value：处理参数取值。
- 分隔符说明如下：
| 分隔符名称 | 分隔符 | 两侧顺序 | 说明 |
|---|---|---|---|
| 处理分隔符 | / | 有关 | 多个action之间的分隔符，前后action顺序执行 |
| 参数分隔符 | , | 无关 | 多处理参数项之间的分隔符 |
| 值分隔符 | _ | 固定顺序 | 参数名与参数值之间的分隔符 |
下文详细介绍各个action的使用。
缩放
对图片大小进行缩放处理。
action名称：resize
| 参数 | 取值 | 说明 |
|---|---|---|
| m | lfit，mfit，fill，pad，fixed | 设置缩略类型。非必选，默认lfit。 |
| w | 1-4096 | 设置缩略图的宽度，单位px。lfit类型必须设置w或h，fill fixed类型必须同时设置w和h。 |
| h | 1-4096 | 设置缩略图的高度，单位px。lfit类型必须设置w或h，fill fixed类型必须同时设置w和h。 |
| limit | 0,1 | 设置是否限制图片缩放的尺寸大小不可超过原图大小，0不限制，1限制。非必选，默认0不限制。 |
| color | 8位十六进制颜色码 | 指定pad类型下填充颜色，前6位分别表示RGB色，如ffffff；最后2位表示Alpha通道，可省略，省略时表示不透明。非必选，默认黑色。 |
缩略类型详细说明：
- lfit：等比缩放图片，缩放到能放到以w、h为宽高的矩形内的最大缩放图片。
- mfit：等比缩放图片，缩放到能包含住以w、h为宽高的矩形的最小缩放图片。
- fill：mfit基础上，对w、h矩形内的图片部分进行裁剪。
- pad：lfit基础上，对w、h矩形内的非图片空白部分进行指定颜色填充。
- fixed：强制缩放到指定w宽、h高。
示例
- 等比缩放图片，缩放后的图片宽最大200，高最大100.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/resize,m_lfit,w_200,h_100
- 等比缩放图片，缩放后的图片宽最大200，高最大100，并对200*100矩形内图片未占满的部分以红底色填充.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/resize,m_pad,w_200,h_100,color_FF0000
- 等比缩放图片，缩放后的图片宽最小200，高最小100.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/resize,m_mfit,w_200,h_100
- 等比缩放图片，缩放后的图片宽最小200，高最小100，并对超出200*100部分图片进行裁剪。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/resize,m_fill,w_200,h_100
- 强制缩放宽200，高100.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/resize,m_fixed,w_200,h_100
裁剪
对图片进行矩形裁剪操作。
action名称：crop
| 参数 | 取值 | 说明 |
|---|---|---|
| x | 0-图片宽度 | 裁剪左上角起点相对原点的x坐标，非必选，默认0。 |
| y | 0-图片高度 | 裁剪左上角起点相对原点的y坐标，非必选，默认0。 |
| w | 1-4096 | 裁剪后图片的宽度，如果指定的宽度超过了图片的宽度，则以图片宽度为准裁剪。单位为px。非必选，默认值原始图片宽度。 |
| h | 1-4096 | 裁剪后图片的高度，如果指定的高度超过了图片的高度，则以图片高度为准裁剪。单位为px。非必选，默认值原始图片高度。 |
示例
- 对图片以（10,10）坐标为起点，裁剪200*200.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/crop,x_10,y_10,w_200,h_200
内切圆裁剪
以图片中心为圆心，进行内切圆裁剪。
action名称：circle
| 参数 | 取值 | 说明 |
|---|---|---|
| r | 0-图片最小边大小的一半 | 以图片中心为圆心，从图片取出的半径为r的圆形区域，r如果超过最小边大小的一半，默认取原圆的最大内切圆。 |
示例
- 以100为半径，进行内切圆裁剪.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/circle,r_100
圆角矩形裁剪
将图片裁剪为圆角矩形。
action名称：rounded-corners
| 参数 | 取值 | 说明 |
|---|---|---|
| r | 1-4096 | 设置圆角的半径。如果指定半径r大于原图宽/高，则默认原图宽/高。 |
示例
- 以50为半径，进行圆角矩形裁剪.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/rounded-corners,r_50
旋转
对图片进行一定角度的旋转。
action名称：rotate
| 参数 | 取值 | 说明 |
|---|---|---|
| a | -360-360 | 图片旋转角度，正数表示顺时针旋转，负数表示逆时针旋转。 |
示例
- 将图片顺时针旋转30度.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/rotate,a_30
自适应方向旋转
根据exif信息进行自动旋转。
action名称：auto-orient
| 参数 | 取值 | 说明 |
|---|---|---|
| o | 0,1 | 0：按原图默认方向，不自动旋转；1：自适应旋转。 |
格式转换
对图片格式进行转换。
action名称：format
| 参数 | 取值 | 说明 |
|---|---|---|
| f | jpg、png、bmp、webp、heic、gif、auto | 指定目标图片的图片格式，如果为值auto则根据请求Header的Accept字段自动选择最优格式。 |
渐进显示
指定图片显示方式。
action名称：interlace
| 参数 | 取值 | 说明 |
|---|---|---|
| i | baseline，progressive | baseline：标准式，指图片按照从上到下的扫描方式显示；progressive：渐进式 ，指图片由模糊到清晰渐进显示。progressive 只对jpg、png格式图片有效，若指定其他格式，则默认显示方式仍为baseline。 |
质量变换
对图片质量进行压缩，质量参数对PNG、BMP和GIF格式无效。
action名称：quality
| 参数 | 取值 | 说明 |
|---|---|---|
| q | 1-100 | 指定图片的相对质量，假设原图质量为N，则压缩后质量为N * q% |
| Q | 1-100 | 指定图片的绝对质量，假设原图质量为N，如果Q < N，则按照Q进行重新编码，否则保持原图质量N不变 |
示例
- 将图片压缩至当前的30%
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/quality,q_30
水印
对一张图片添加水印处理。
action名称：watermark
| 图片水印参数 | 取值 | 说明 |
|---|---|---|
| bucket | - | 指定水印图片存储在BOS的Bucket名称，非必选，默认当前bucket。非当前bucket则要求该水印图片有公共读权限。 |
| image | - | 指定水印图片存储在BOS的Object名称，需要取url安全的Base64编码后的值。图片水印必选参数。 |
| t | 1-100 | 指定图片水印透明度，取值为100时，表示与原始透明度一致。非必选，默认值100。 |
| 文字水印参数 | 取值 | 说明 |
|---|---|---|
| text | - | 水印文字内容，需要进行url安全的Base64编码，且编码后最多不能超过200个字符。文字水印必选。 |
| size | 1-1024 | 指定水印字体大小，单位px。非必选，默认30。 |
| color | 8位十六进制颜色码 | 指定字体颜色，前6位分别表示RGB色，如ffffff；最后2位表示Alpha通道，可省略，省略时表示不透明。非必选，默认000000黑色。 |
| type | 支持的字体见下表 | 指定字体的字体类型，取值要求进行url安全的Base64编码。非必选。若指定的字体样式不在当前已支持的fontFamily列表中，则显示效果为默认字体宋体。 |
| style | normal、italic、bold | 指定字体样式。normal（常规）italic（斜体）bold（粗体）。非必选，默认normal。只有当字体支持style效果时，才会渲染文字效果。 |
| 公共水印参数 | 取值 | 说明 |
|---|---|---|
| g | 1-9 | 指定水印的锚点位置。非必选，默认9。具体含义见下方说明。 |
| x | -4096-4096 | 指定水印基于锚点的水平方向距离。非必选，默认值10。 |
| y | -4096-4096 | 指定水印基于锚点的垂直方向距离。非必选，默认值10。 |
| a | -360-360 | 指定水印旋转角度。正数表示顺时针旋转，负数表示逆时针旋转。非必选，默认值0。 |
说明：
- 目前不支持在一组action中同时指定图片和文字水印，只能指定图片或文字水印一种类型。如果需要指定图片和文字水印，可通过多组action实现。
- 锚点位置说明，将您的原始图片分成如下图所示9个区域，并按照图示位置进行编号，每个区域的锚点位置如图所示：
目前支持的字体类型如下：
| 字体 | 名称 | base64编码 |
|---|---|---|
| FZLanTingHei | 方正兰亭黑 | RlpMYW5UaW5nSGVp |
| FZFangSong | 方正仿宋 | RlpGYW5nU29uZw== |
| FZShuSong | 方正书宋 | RlpTaHVTb25n |
| FZKai | 方正楷体 | RlpLYWk= |
| FZHei | 方正黑体 | RlpIZWk= |
示例
- 添加图片水印
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/watermark,image_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=,g_9,a_90
- 添加文字水印
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/watermark,text_aGVsbG8=,g_9,color_ff0000
获取图片信息
此命令用来获取图片信息，如果图片有exif信息则返回包含exif的完整信息，如果图片不包含exif信息，则返回图片的基本信息。
action名称：info
此命令没有参数，以 x-bce-process=image/info 形式访问即可。
图片处理样式
图片样式是指您可以将一些常用的图片处理操作保存为一个别名，即一个样式。这样，一组复杂的操作，利用样式，可以通过一个简洁的访问即可达到相同效果。
样式访问
整体的图片样式访问形式为：x-bce-process=style/${stylename}，说明如下：
- style：当使用图片样式访问时，需要指定此处名字为style。
-
stylename：访问的style的名字。
说明，因为BOS的图片处理命令分新旧两种版本，因此，一个图片处理样式所对应的实际图片处理命令可以是新版或旧版。
这里x-bce-process=style/${stylename}的访问方式只能访问新版命令所对应的样式，旧版本命令所对应的样式仍需通过旧版本@!方式访问。
添加/删除样式
目前通过console添加的样式仍为旧版本命令的样式，新版本命令样式功能即将开通。
原图保护
BOS支持通过API实现原图保护功能，并可通过resource字段指定该功能生效范围，具体请参见原图保护。 对于开通原图保护的文件，不允许匿名下载访问该文件，或带自定义图片处理参数访问，只允许使用style样式访问或携带合法签名访问。